Halo semuanya. Baru-baru ini saya menemukan tugas untuk menyiapkan paket npm pribadi. Semuanya terdengar sangat menarik dan menjanjikan sampai ternyata tidak banyak yang bisa dilakukan di sana. Semuanya akan berakhir di sini, tetapi tugas kedua muncul - untuk menulis repositori demo untuk paket npm, yang dapat diambil, dikloning dan didasarkan padanya dengan cepat membuat sesuatu yang berguna dan dengan gaya yang sama.
Hasilnya adalah proyek dengan pemformatan yang disesuaikan, gaya kode, pengujian untuk setiap kumpulan, batas cakupan kode, laporan cakupan kode dan dokumentasi otomatis. Ditambah penerbitan nyaman di npm. Detail tentang pengaturan - di bawah potongan.
Persyaratan
Pertama, saya menemukan apa yang sudah kita miliki:
- Proyek-proyek baru ditulis dalam TypeScript
- Selain proyek-proyek baru, ada banyak proyek dalam JavaScript murni
- Ada persyaratan untuk menulis tes dan hasilnya harus dikirim untuk analisis
Lalu ia memperkirakan Daftar Keinginannya - karena ada waktu dan keinginan, mengapa tidak santai saja. Yang saya inginkan lebih banyak:
- Saya ingin gaya pemformatan yang seragam
- Saya ingin gaya TypeScript terpadu
- Saya ingin dokumentasi, tetapi saya tidak ingin menulisnya
- Secara umum, saya ingin mengotomatiskan semuanya dengan maksimal. Apa yang akan fyr-fyr-fyr dan dalam produksi
Akibatnya, persyaratan mulai berlaku sebagai berikut:
- Modul harus TypeScript dan diuji menggunakan TsLint
- Modul harus digunakan dari bawah TypeScript dan dari bawah JavaScript
- Pengujian harus dikonfigurasi pada git hook, cakupan kode minimum juga harus dikonfigurasi, statistik seharusnya
- Pemformatan harus dikonfigurasikan
- Dokumentasi harus dibuat dari kode.
- Publikasi harus nyaman dan konsisten.
- Semua itu bisa otomatis
Tampaknya menyenangkan, Anda perlu mencoba.
Gerakan awal
Kami membuat (mengkloning) repositori, menginisialisasi package.json, mengatur TypeScript secara lokal. Secara umum, kami mengatur semua dependensi secara lokal, karena semuanya akan masuk ke server. Jangan lupa untuk memperbaiki dependensi versi .
git init npm init npm i -D typescript ./node_modules/.bin/tsc --init
Segera di tempat Anda perlu mengubah tsconfig.json untuk diri Anda sendiri - tetapkan target, libs, sertakan / kecualikan, outDir, dan opsi lainnya.
Untuk mempertahankan format seragam, saya mengambil dua alat. Yang pertama adalah file .editorconfig. Ini dipahami oleh semua IDE utama (WebStorm, VSCode, Visual Studio, dll.), Tidak memerlukan instalasi apa pun yang berlebihan, dan bekerja dengan sejumlah besar tipe file - js, ts, md, dan sebagainya.
#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
Sekarang, autoformatting akan berperilaku kurang lebih sama dengan kolega saya.
Alat kedua lebih cantik . Ini adalah paket npm yang memeriksa dan, jika mungkin, secara otomatis memperbaiki format teks Anda. Instal secara lokal dan tambahkan perintah pertama ke package.json
npm i -D prettier
package.json
"prettier": "prettier --config .prettierrc.json --write src*.ts"
Prettier tidak memiliki perintah init, jadi Anda perlu mengkonfigurasinya secara manual. Buat .prettierrc.json di root proyek dengan sesuatu seperti konten kontroversial ini (jika ada, posnya sama sekali bukan tentang kutipan mana yang lebih baik, tetapi Anda dapat mencoba)
.prettierrc.json
{ "tabWidth": 4, "useTabs": false, "semi": true, "singleQuote": true, "trailingComma": "es5", "arrowParens": "always" }
Sekarang buat folder src, buat index.ts dengan beberapa konten bersyarat di dalamnya dan coba jalankan lebih cantik. Jika dia tidak menyukai format Anda, ia akan memperbaikinya secara otomatis. Sangat nyaman Jika Anda tidak ingin mengingat ini hanya selama komit / push, Anda dapat mengonfigurasinya untuk autorun atau menginstal ekstensi untuk studio.
Gaya Kode
Dengan gaya kode, semuanya juga tidak rumit. Untuk JavaScript, ada eslint , untuk TypeScript, ada tslint . Kami menempatkan tslint dan membuat tsconfig.js untuk menyimpan pengaturan
npm i -D tslint ./node_modules/.bin/tslint --init
package.json
"lint": "tslint -c tslint.json 'src/**/*.ts' 'tests/**/*.spec.ts'"
Anda bisa menulis aturan Anda sendiri, atau Anda bisa menggunakan aturan yang ada menggunakan parameter extended. Di sini , misalnya, konfigurasi dari airbnb.
Pengembang Tslint sedang bercanda module.exports = { extends: "./tslint-base.json", rules: { "no-excessive-commenting": [true, {maxComments: Math.random() * 10}] } };
Bukankah itu cantik?
Ada poin penting - persimpangan tslint dan lebih cantik dalam fungsi (misalnya, dalam panjang string atau "menggantung" koma). Jadi, jika Anda menggunakan keduanya, Anda perlu memantau kepatuhan atau meninggalkan sesuatu.
Namun, bagi mereka yang ingin memeriksa tidak semua file, tetapi hanya dipentaskan - ada paket bertahap
Tes
Apa yang kita butuhkan dari semua tes di atas? Pertama, sehingga mereka mulai secara otomatis, kedua, kontrol cakupan, ketiga laporan, lebih disukai dalam format lcov (jika ada, lcov dipahami dengan baik oleh analis yang berbeda - dari SonarQube ke CodeCov). Kami akan berurusan dengan otomasi sedikit kemudian, sambil menyiapkan tes sendiri.
Kami menempatkan karma , melati , dan semua kotak tubuh yang sesuai
npm i -D karma karma-jasmine jasmine karma-typescript karma-chrome-launcher @types/jasmine ./node_modules/.bin/karma init
Kami memodifikasi karma.conf.js sedikit dan segera mengkonfigurasi pekerjaan dengan cakupan
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: {} } } }, }
Dan, tentu saja, jangan lupa untuk menambahkan perintah baru ke package.json
package.json
"test": "karma start"
Jika Anda menggunakan atau berencana menggunakan CI, maka lebih baik meletakkan HeadlessChrome :
npm i -D puppeteer
Dan pra-konfigurasi Karma (perbaikan Chrome di ChromeHeadless) plus sesuatu yang lain. Hasil edit dapat dilihat di repositori demo .
Jalankan tes, periksa apakah semuanya berfungsi. Pada saat yang sama, periksa laporan cakupan (ada di folder cakupan) dan hapus dari kontrol versi, itu tidak diperlukan di repositori.
Laporkan:
Gaya berkomitmen
Komit juga dapat disatukan (dan pada saat yang sama membawa seseorang ke kehangatan, jika Anda berlebihan, jadi lebih baik tanpa fanatisme). Untuk ini, saya mengambil komitmen . Ia bekerja dalam bentuk dialog, mendukung format changelog konvensional (Anda dapat membuat changelog dari komitmennya) dan ada plugin VsCode untuknya
npm i -D commitizen npm i -D cz-conventional-changelog
cz-konvensional-changelog adalah adaptor yang bertanggung jawab atas pertanyaan, dan sebagai hasilnya, untuk format komit Anda
Tambahkan perintah baru ke bagian skrip
"commit":"git-cz"
Dan bagian package.json baru - konfigurasi untuk komit
"config": { "commitizen": { "path": "./node_modules/cz-conventional-changelog" } }
Dialog dengan komitmen terlihat seperti ini:
Dokumentasi
Sekarang ke dokumentasi. Kami akan memiliki dua jenis dokumentasi - dari kode dan dari komitmen. Untuk dokumentasi dari kode, saya mengambil typedoc (analog dengan esdoc tetapi untuk TypeScript). Sangat mudah untuk mengatur dan bekerja. Hal utama adalah jangan lupa untuk menghapus hasil karyanya dari kontrol versi.
npm i typedoc -D
dan perbarui package.json
package.json
"doc": "typedoc --out docs/src/ --readme ./README.md"
Bendera --readme akan memaksa readme untuk dimasukkan di halaman dokumentasi utama, yang nyaman.
Jenis dokumentasi kedua adalah changelog, dan paket konvensional-changelog-cli akan membantu kami.
npm i -D conventional-changelog-cli
package.json
"changelog": "conventional-changelog -p angular -i CHANGELOG.md -s"
Dari sudut hanya ada pemformatan dan tidak lebih. Sekarang untuk memperbarui changelog, jalankan npm run changelog. Hal utama adalah menulis komit dengan hati-hati. Yah, kami selalu menulis komitmen yang sempurna, jadi ini seharusnya tidak menjadi masalah.
Membangun
Karena paket kami juga bisa digunakan untuk JavaScript, kami harus mengubah TypeScript menjadi JavaScript. Selain itu, akan menyenangkan untuk membuat bundel yang diperkecil, untuk berjaga-jaga. Untuk ini kita perlu uglifyjs dan sedikit paket tweak.json
npm i -D uglifyjs
package.json
"clean":"rmdir dist /S /Q", "build": "tsc --p ./ --sourceMap false", "bundle": "uglifyjs ./dist/*.js --compress --mangle --output ./dist/index.min.js"
Omong-omong, jika Anda ingin mengontrol ukuran proyek Anda, ada dua paket yang lebih menarik
Mereka juga dapat diintegrasikan dalam proses commit / push / publish untuk tetap dalam ukuran bundel yang dapat diterima. Sangat, sangat membantu.
Otomasi
Yah, kami telah mengambil langkah-langkah dasar, sekarang semuanya perlu diotomatisasi, jika tidak maka akan sangat tidak nyaman untuk bekerja.
Untuk ini kita perlu satu paket lagi - husky . Ia menulis ulang git hooks dan memanggil perintah yang terkait dari package.json. Misalnya, ketika Anda komit, precommit akan bekerja, push - prepush, dan sebagainya. Jika skrip mengembalikan kesalahan, komit akan gagal.
npm i -D husky
package.json
"precommit":"npm run prettier", "prepush": "call npm run lint && call npm run test"
Ada nuansa penting di sini, penggunaan sintaks panggilan tidak lintas platform dan tidak akan lepas landas pada sistem unix. Jadi jika Anda ingin melakukan semuanya dengan jujur, Anda harus menginstal paket npm-run-all juga, ia melakukan hal yang sama tetapi lintas-platform.
Posting
Nah, di sini kita sampai pada publikasi paket kami (walaupun kosong). Mari kita pikirkan apa yang kita inginkan dari publikasi?
- Uji semuanya lagi
- Kumpulkan artefak bangunan
- Kumpulkan dokumentasi
- Naikkan versi
- Tag pemicu
- Kirim ke npm
Tangan melakukan semuanya - sedih. Atau Anda lupa sesuatu, atau Anda perlu menulis daftar periksa. Juga perlu untuk mengotomatisasi. Anda dapat meletakkan paket lain - lepaskan . Dan Anda dapat menggunakan kait asli dari npm sendiri - preversion, versi, postversion, misalnya seperti ini:
"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'
Masih menentukan untuk package.json apa yang akan disertakan dalam paket, titik masuk dan path ke tipe kita (jangan lupa untuk menentukan flag --declaration di tsconfig.json untuk mendapatkan file d.ts)
package.json
"main": "./dist/index.min.js", "types": "./dist/index.d.ts", "files": [ "dist/", "src/", "tests/" ]
Ya, sepertinya hanya itu saja. Sekarang sudah cukup untuk dilakukan
npm version ... npm publish
Dan semuanya akan dilakukan secara otomatis.
Bonus
Sebagai bonus, ada repositori demo yang mendukung semua + CI ini menggunakan travis-ci. Biarkan saya mengingatkan Anda bahwa HeadlessChrome dikonfigurasi di sana, jadi jika ini penting bagi Anda, saya sarankan Anda untuk melihat di sana.
Ucapan Terima Kasih
Terima kasih banyak kepada Alexei Volkov untuk laporannya tentang JsFest, yang menjadi dasar artikel ini.
Berkat max7z , tidak bisa dihancurkan , justboris untuk mengklarifikasi bahwa jalan menuju dependensi lokal dapat dihilangkan.
Dan beberapa statistik
- Ukuran Node_modules: 444 MB (NTFS)
- Jumlah dependensi dari level pertama: 17
- Total Paket Yang Digunakan: 643
Tautan yang bermanfaat