Mempublikasikan ke npm dan Penerapan Versi Semantik

Sebelum menerbitkan, selalu jalankan npm publish --dry-run. Perintah ini menyimulasikan penerbitan tanpa benar-benar mengunggah apa pun, serta menunjukkan dengan tepat berkas mana yang akan disertakan, ukurannya, dan isi arsip paket. Perintah ini membantu menemukan kesalahan umum, seperti tidak sengaja menyertakan berkas sumber atau tidak menyertakan direktori dist.

Kontrol berkas yang diterbitkan menggunakan kolom files di package.json: "files": ["dist", "README.md"]. Pendekatan daftar izin ini lebih aman daripada .npmignore, yang merupakan daftar blokir dan dapat membocorkan berkas sensitif jika Anda lupa menambahkannya. Selalu sertakan dist, deklarasi tipe, dan dokumentasi. Jangan pernah menyertakan src, pengujian, atau node_modules.

Paket npm mengikuti pembuatan versi semantik (semver): MAJOR.MINOR.PATCH. Naikkan MAJOR untuk perubahan yang merusak kompatibilitas, seperti menghapus properti atau mengubah tanda tangan API. Naikkan MINOR untuk fitur baru yang kompatibel dengan versi sebelumnya, seperti komponen baru atau properti opsional baru. Naikkan PATCH untuk perbaikan kesalahan yang kompatibel dengan versi sebelumnya. Versi 0.x.x dianggap prastabil, sehingga apa pun dapat mengalami perubahan.

Penanda prarilis menunjukkan bahwa suatu versi belum siap untuk produksi: 1.0.0-alpha.1 untuk build eksperimental awal, 1.0.0-beta.2 untuk versi yang fiturnya sudah lengkap tetapi mungkin masih memiliki kesalahan, dan 1.0.0-rc.1 (kandidat rilis) untuk versi yang siap menjalani pengujian akhir. Terbitkan prarilis dengan npm publish --tag beta agar versi tersebut tidak menjadi versi yang dipasang secara bawaan.

Changesets adalah alat standar untuk mengelola pembuatan versi paket dan catatan perubahan di pustaka komponen. Alurnya: kontributor menjalankan yarn changeset add untuk mencatat perubahan dan jenis perubahannya (major/minor/patch). Integrasi berkelanjutan menjalankan yarn changeset version untuk menaikkan versi paket. Proses penerbitan menjalankan yarn changeset publish untuk menerbitkannya ke npm.

Changesets secara otomatis membuat dan memelihara CHANGELOG.md berdasarkan berkas perubahan yang dikomit oleh kontributor. Setiap entri mencakup nomor versi, tanggal rilis, dan uraian perubahan. Dengan demikian, tersedia riwayat setiap versi yang mudah dibaca tanpa perlu memelihara catatan perubahan secara manual.

semantic-release adalah alat pembuatan versi otomatis penuh yang menentukan versi berikutnya dari pesan komit konvensional (feat: → minor, fix: → patch, BREAKING CHANGE: → major). Alat ini menaikkan versi, membuat catatan perubahan, dan menerbitkan paket ke npm — semuanya dipicu oleh integrasi berkelanjutan saat penggabungan ke main. Tidak ada pengelolaan versi manual.

Paket tanpa lingkup (my-component) selalu bersifat publik. Paket dengan lingkup (@myorg/my-component) secara bawaan bersifat terbatas (pribadi) — terbitkan sebagai paket publik dengan npm publish --access public. Paket terbatas memerlukan akun npm berbayar atau organisasi. Pastikan pengaturan akses sebelum penerbitan pertama Anda.

Provenans npm menghubungkan paket yang Anda terbitkan dengan komit git tertentu melalui cara yang dapat diverifikasi. Aktifkan fitur ini dengan npm publish --provenance di GitHub Actions. Pengguna dapat memverifikasi bahwa paket yang mereka pasang dibuat dari komit sumber yang persis sama seperti yang ditampilkan di halaman registri npm. Hal ini secara signifikan meningkatkan keamanan rantai pasokan.

Jika suatu versi memiliki kesalahan kritis atau perubahan yang merusak kompatibilitas, tandai versi tersebut sebagai usang: npm deprecate your-package@1.2.3 "Security vulnerability, upgrade to 1.2.4". npm menampilkan peringatan keusangan kepada siapa pun yang memasang versi tersebut. Tindakan ini tidak menghapus versinya, karena npm secara bawaan tidak menghapus versi yang sudah diterbitkan, tetapi memberi tahu pengguna agar melakukan peningkatan.

Paket dengan lingkup menggunakan format @scope/package-name. Lingkup biasanya merupakan nama pengguna npm atau nama organisasi Anda. Paket dengan lingkup memperjelas siapa yang memelihara paket tersebut dan mencegah konflik penamaan dengan paket tanpa lingkup. Gunakan paket dengan lingkup untuk paket pribadi dan paket sumber terbuka yang terkait dengan organisasi Anda.

Gunakan npm publish --dry-run untuk melihat pratinjau dan kolom files untuk mengontrol apa yang diterbitkan. Pembuatan versi semantik: MAJOR untuk perubahan yang merusak kompatibilitas, MINOR untuk fitur baru, dan PATCH untuk perbaikan. Prarilis menggunakan penanda -alpha/-beta/-rc. Changesets mengotomatiskan pembuatan versi dan pembuatan CHANGELOG untuk pustaka kolaboratif. semantic-release mengotomatiskan proses berdasarkan komit konvensional. Aktifkan --provenance untuk keamanan rantai pasokan. Tandai versi yang memiliki kesalahan sebagai usang dengan npm deprecate.