Geekly articles weekly

قمنا بإعداد مشروع npm مناسب لأنفسنا وللفريق أو القليل عن أدوات الواجهة الأمامية الحديثة


مرحبا بالجميع. لقد صادفت مؤخرًا مهمة إعداد حزم npm الخاصة. بدا كل شيء مثيرًا للاهتمام وواعدًا للغاية حتى اتضح أنه لا يوجد الكثير للقيام به هناك. كل شيء كان سينتهي هنا ، ولكن المهمة الثانية نشأت - لكتابة مستودع تجريبي لحزمة npm ، والتي يمكن أخذها واستنساخها واستنادها إليها بسرعة لإنشاء شيء مفيد وبنفس النمط.


وكانت النتيجة مشروعًا بتنسيق مخصص ونمط الكود واختبارات لكل تجمع وحدود على تغطية الكود وتقريرًا عن تغطية الكود والتوثيق التلقائي. بالإضافة إلى النشر المريح في npm. تفاصيل حول الإعداد - تحت القطع.


المتطلبات


أولاً ، اكتشفت ما لدينا بالفعل:


  • تتم كتابة المشاريع الجديدة في TypeScript
  • بالإضافة إلى المشاريع الجديدة ، هناك مجموعة من المشاريع في JavaScript خالص
  • هناك متطلبات لكتابة الاختبارات ويجب إرسال النتائج للتحليل

ثم قدر قائمة أمنياته - بما أن هناك وقت ورغبة ، فلماذا لا تأخذ الأمر بسهولة. ما أريده أكثر:


  • اريد اسلوب تنسيق موحد
  • أريد نمط TypeScript موحد
  • أريد التوثيق ، لكني لا أريد كتابته
  • بشكل عام ، أريد أتمتة كل شيء إلى أقصى حد. ماذا يمكن أن يكون fyr-fyr-fyr وفي الإنتاج

ونتيجة لذلك ، تبلورت المتطلبات على النحو التالي:


  • يجب أن تكون الوحدة TypeScript ومختبرة باستخدام TsLint
  • يجب استخدام الوحدة من تحت TypeScript ومن JavaScript
  • يجب تكوين الاختبارات على ربط git ، يجب تكوين الحد الأدنى من تغطية الرمز أيضًا ، يجب أن تكون الإحصائيات
  • يجب تكوين التنسيق
  • يجب إنشاء الوثائق من التعليمات البرمجية.
  • يجب أن يكون النشر ملائمًا ومتسقًا.
  • كل ما يمكن أتمتة

يبدو أنه لطيف ، عليك المحاولة.


إيماءات أولية


نقوم بإنشاء (استنساخ) المستودع ، وتهيئة package.json ، وتعيين TypeScript محليًا. بشكل عام ، قمنا بتعيين كل التبعيات محليًا ، لأن كل شيء سيذهب إلى الخادم. لا تنس إصلاح تبعيات الإصدار .


git init npm init npm i -D typescript ./node_modules/.bin/tsc --init

مباشرة على الفور تحتاج إلى تعديل tsconfig.json لنفسك - تعيين الهدف ، libs ، تضمين / استبعاد ، outDir وخيارات أخرى.


نمط التنسيق


للحفاظ على تنسيق موحد ، أخذت أداتين. الأول هو ملف. editorconfig. يتم فهمه من قبل جميع IDEs الرئيسية (WebStorm ، VSCode ، Visual Studio ، وما إلى ذلك) ، ولا يتطلب تثبيت أي شيء غير ضروري ، ويعمل مع عدد كبير من أنواع الملفات - js و ts و md وما إلى ذلك.


 #root = true [*] indent_style = space end_of_line = lf charset = utf-8 trim_trailing_whitespace = true insert_final_newline = true max_line_length = 100 indent_size = 4 [*.md] trim_trailing_whitespace = false

الآن ، سيتصرف التنسيق التلقائي بشكل أو بآخر مع زملائي.


الأداة الثانية أجمل . هذه حزمة npm تقوم بالتحقق من تنسيق النص الخاص بك وتصحيحه تلقائيًا ، إذا أمكن. قم بتثبيته محليًا وأضف الأمر الأول إلى package.json


 npm i -D prettier

حزمة


 "prettier": "prettier --config .prettierrc.json --write src/**/*.ts"

لا يحتوي Prettier على أمر init ، لذا تحتاج إلى تهيئته يدويًا. قم بإنشاء .prettierrc.json في جذر المشروع بشيء مثل هذا المحتوى المثير للجدل (إذا كان أي شيء ، فإن المنشور ليس على الإطلاق حول الاقتباسات الأفضل ، ولكن يمكنك المحاولة)


.prettierrc.json


 { "tabWidth": 4, "useTabs": false, "semi": true, "singleQuote": true, "trailingComma": "es5", "arrowParens": "always" }

الآن قم بإنشاء مجلد src ، وأنشئ index.ts مع بعض المحتوى الشرطي فيه وحاول تشغيله بشكل أجمل. إذا لم يعجبه تنسيقك ، فسيصلحه تلقائيًا. مريح للغاية. إذا كنت لا تريد أن تتذكر هذا فقط أثناء الالتزام / الدفع ، يمكنك تكوينه للتشغيل التلقائي أو تثبيت ملحق للاستوديو.


نمط الرمز


مع نمط الكود ، كل شيء ليس معقدًا أيضًا. بالنسبة لـ JavaScript ، يوجد eslint ؛ بالنسبة لـ TypeScript ، هناك tslint . نضع tslint وننشئ tsconfig.js لتخزين الإعدادات


 npm i -D tslint ./node_modules/.bin/tslint --init

حزمة


 "lint": "tslint -c tslint.json 'src/**/*.ts' 'tests/**/*.spec.ts'"

يمكنك كتابة القواعد الخاصة بك ، أو يمكنك استخدام القواعد الموجودة باستخدام معلمة التوسيع. هنا ، على سبيل المثال ، تكوين من airbnb.


يمزح مطورو Tslint
 module.exports = { extends: "./tslint-base.json", rules: { "no-excessive-commenting": [true, {maxComments: Math.random() * 10}] } };

حسنا ليست جميلة؟


هناك نقطة مهمة - تتقاطع tslint وأجمل في الوظائف (على سبيل المثال ، في طول سلسلة أو فواصل "معلقة"). لذلك ، إذا كنت تستخدم كليهما ، فستحتاج إلى مراقبة الامتثال أو التخلي عن شيء ما.


ومع ذلك ، بالنسبة لأولئك الذين يرغبون في التحقق من جميع الملفات ، ولكن فقط على مراحل - هناك حزمة على مراحل


الاختبارات


ماذا نحتاج من الاختبارات قبل كل شيء؟ أولاً ، حتى يبدأوا تلقائيًا ، ثانيًا ، التحكم في التغطية ، ثالثًا بعض التقارير ، ويفضل أن يكون بتنسيق lcov (إذا كان أي شيء ، فإن lcov مفهومة جيدًا من قبل محللين مختلفين - من SonarQube إلى CodeCov). سنتعامل مع الأتمتة بعد ذلك بقليل ، أثناء إعداد الاختبارات بأنفسهم.


نضع الكارما والياسمين وجميع أدوات الجسم المقابلة


 npm i -D karma karma-jasmine jasmine karma-typescript karma-chrome-launcher @types/jasmine ./node_modules/.bin/karma init

نقوم بتعديل karma.conf.js قليلاً ونقوم على الفور بتكوين العمل مع التغطية


karma.conf.js
 karmaTypescriptConfig : { include: ["./src/**/*.ts", "./tests/**/*.spec.ts"], tsconfig: "./tsconfig.json", reports: { "html": "coverage", "lcovonly": { directory: './coverage', filename: '../lcov.dat' } }, coverageOptions: { threshold: { global: { statements: 60, branches: 60, functions: 60, lines: 60, excludes: [] }, file: { statements: 60, branches: 60, functions: 60, lines: 60, excludes: [], overrides: {} } } }, }

وبطبيعة الحال ، لا تنس أن تضيف أمرًا جديدًا إلى package.json


حزمة


 "test": "karma start"

إذا كنت تستخدم أو تخطط لاستخدام CI ، فمن الأفضل وضع HeadlessChrome :


 npm i -D puppeteer

وقم بتهيئة Karma مسبقًا (إصلاح Chrome على ChromeHeadless) بالإضافة إلى شيء آخر. يمكن الاطلاع على التعديلات في المستودع التجريبي .


قم بإجراء الاختبارات ، وتحقق من أن كل شيء يعمل. في نفس الوقت ، تحقق من تقرير التغطية (موجود في مجلد التغطية) وقم بإزالته من التحكم في الإصدار ، ليس هناك حاجة إليه في المستودع.


تقرير:



أسلوب الالتزام


يمكن أيضًا توحيد الالتزامات (وفي الوقت نفسه إحضار شخص ما إلى الأبيض ، إذا بالغت في ذلك ، فمن الأفضل بدون تعصب). لهذا ، أخذت ملتزم . يعمل على شكل حوار ، ويدعم تنسيق سجل التغيير التقليدي (يمكنك إنشاء سجل للتغيير من التزاماته) وهناك ملحق VsCode له


 npm i -D commitizen npm i -D cz-conventional-changelog

cz-traditional-changelog عبارة عن محول مسؤول عن الأسئلة ، ونتيجة لذلك ، يتم تنسيق التزاماتك


إضافة أمر جديد لقسم البرامج النصية


 "commit":"git-cz"

وقسم package.json جديد - التكوين للالتزام


 "config": { "commitizen": { "path": "./node_modules/cz-conventional-changelog" } }

يبدو الحوار مع الملتزمين كما يلي:



التوثيق


الآن إلى الوثائق. سيكون لدينا نوعان من الوثائق - من التعليمات البرمجية ومن الأوامر. للحصول على وثائق من التعليمات البرمجية ، أخذت typedoc (مشابه لـ esdoc لكن لـ TypeScript). من السهل جدًا الإعداد والعمل. الشيء الرئيسي هو عدم نسيان إزالة نتائج عمله من التحكم في الإصدار.


 npm i typedoc -D

وتحديث package.json


حزمة


 "doc": "typedoc --out docs/src/ --readme ./README.md"

ستفرض علامة --readme أن يتم تضمين الملف التمهيدي في صفحة التوثيق الرئيسية ، وهو أمر ملائم.


النوع الثاني من الوثائق هو سجل التغيير ، وستساعدنا حزمة التغيير-التغيير التقليدية cli في ذلك.


 npm i -D conventional-changelog-cli

حزمة


 "changelog": "conventional-changelog -p angular -i CHANGELOG.md -s"

من الزاوية هناك تنسيق فقط وليس أكثر. الآن من أجل تحديث سجل التغيير فقط قم بتشغيل npm run changelog. الشيء الرئيسي هو كتابة الالتزامات بعناية. حسنًا ، نكتب دائمًا تعهدات مثالية ، لذلك لا ينبغي أن يكون هذا مشكلة.


بناء


نظرًا لأن مجموعتنا يجب أن تعمل مع JavaScript أيضًا ، نحتاج إلى تحويل TypeScript إلى JavaScript. بالإضافة إلى ذلك ، سيكون من الجيد إنشاء حزمة مصغرة ، في حالة حدوث ذلك. لهذا نحن بحاجة إلى uglifyjs ومجموعة صغيرة من القرص


 npm i -D uglifyjs

حزمة


 "clean":"rmdir dist /S /Q", "build": "tsc --p ./ --sourceMap false", "bundle": "uglifyjs ./dist/*.js --compress --mangle --output ./dist/index.min.js"

بالمناسبة ، إذا كنت تريد التحكم في حجم مشروعك ، فهناك حزمتان أكثر إثارة للاهتمام



يمكن أيضًا دمجها في عملية الالتزام / الدفع / النشر للبقاء في حجم الحزمة المقبول. مفيد جدا جدا.


الأتمتة


حسنًا ، لقد اتخذنا بالفعل الخطوات الأساسية ، والآن يجب أن يكون كل شيء مؤتمتًا ، وإلا فلن يكون العمل صريحًا.


لهذا نحن بحاجة إلى حزمة واحدة أخرى - أجش . يعيد كتابة خطافات git ويستدعي الأوامر المرتبطة من package.json. على سبيل المثال ، عندما تلتزم ، ستعمل الأوامر المسبقة والدفع المسبق وما إلى ذلك. إذا أعاد النص البرمجي خطأ ، فسوف يفشل الالتزام.


 npm i -D husky

حزمة


 "precommit":"npm run prettier", "prepush": "call npm run lint && call npm run test"

هناك فارق بسيط مهم هنا ، استخدام بنية الاتصال ليس عبر الأنظمة الأساسية ولن ينطلق في أنظمة يونكس. لذلك إذا كنت ترغب في القيام بكل شيء بصدق ، فعليك تثبيت حزمة npm-all-all أيضًا ، فهي تفعل نفس الشيء ولكن عبر الأنظمة الأساسية.


نشر


حسنًا ، نأتي إلى نشر الحزمة (وإن كانت فارغة). دعونا نفكر ماذا نريد من المنشور؟


  • اختبر كل شيء مرة أخرى
  • جمع التحف الفنية
  • اجمع الوثائق
  • رفع الإصدار
  • علامات الزناد
  • إرسال إلى npm

الأيدي تفعل كل شيء - حزين. أو تنسى شيئًا ما ، أو تحتاج إلى كتابة قائمة تحقق. من الضروري أيضا أتمتة. يمكنك وضع حزمة أخرى - إطلاق العنان . ويمكنك استخدام الخطافات الأصلية لـ npm نفسها - المنعكس ، الإصدار ، postversion ، على سبيل المثال مثل:


 "preversion": "npm run test", "version": "call npm run clean && call npm run build && npm run bundle && call npm run doc && call npm run changelog && git add . && git commit -m 'changelogupdate' --no-verify", "postversion": "git add . && git push && git push --tags",

يبقى تحديد ل package.json ما يجب تضمينه في الحزمة ونقطة الإدخال والمسار لأنواعنا (لا تنس تحديد علامة --declaration في tsconfig.json للحصول على ملفات d.ts)


حزمة


 "main": "./dist/index.min.js", "types": "./dist/index.d.ts", "files": [ "dist/", "src/", "tests/" ]

حسنًا ، يبدو أن هذا كل شيء. الآن يكفي القيام بذلك


 npm version ... npm publish

وكل شيء آخر سيتم تلقائيًا.


مكافأة


كمكافأة ، هناك مستودع تجريبي يدعم كل هذا + CI باستخدام travis-ci. دعني أذكرك بأنه تم تكوين HeadlessChrome هناك ، لذلك إذا كان هذا مهمًا بالنسبة لك ، أنصحك بالنظر إليه.


شكر وتقدير


شكرا جزيلا لأليكسي فولكوف على تقريره عن JsFest ، والذي أصبح أساس هذا المقال.


بفضل max7z ، غير قابل للتدمير ، justboris لتوضيح أنه يمكن حذف المسارات إلى التبعيات المحلية.


وبعض الإحصائيات


  • حجم العقدة: 444 ميجا بايت (NTFS)
  • عدد التبعيات من المستوى الأول: 17
  • مجموع العبوات المستخدمة: 643

روابط مفيدة


Source: https://habr.com/ru/post/ar417429/

More articles:


All Articles