Bagaimana Cara Memublikasikan Paket NPM Privat Perusahaan ke GitLab? Panduan Penyiapan pnpm Lengkap

Bayangkan Anda adalah seorang koki kepala. Untuk memastikan semua restoran jaringan Anda menghasilkan hidangan lezat yang sama, Anda telah mengembangkan serangkaian “saus rahasia”. Anda ingin saus-saus ini dikirim ke setiap cabang, tetapi Anda tidak ingin orang yang lewat mengambilnya begitu saja.

Dalam dunia pengembangan perangkat lunak, saus-saus rahasia ini adalah “paket privat” internal perusahaan.

Seiring bertambahnya proyek, Anda mungkin pernah merasakan kekesalan ini: menduplikasi komponen UI atau fungsi utilitas yang sama di setiap proyek, atau berjuang dengan Git Submodule sampai Anda meragukan pilihan hidup Anda. Faktanya, yang Anda butuhkan hanyalah “Dapur Privat (NPM Registry Privat)”. Hari ini, kita akan membahas cara menggunakan pnpm untuk memublikasikan paket ke GitLab, sehingga anggota tim dapat menginstalnya seperti paket sumber terbuka hanya dengan satu perintah.

Mengapa Anda Membutuhkan Paket Privat dan Scope?

Dalam semesta Node.js, paket privat harus memiliki “nama belakang”—ini adalah Scope.

Misalnya, jika nama perusahaan Anda adalah @my-company, nama paket Anda mungkin terlihat seperti ini: @my-company/ui-kit. Dengan nama belakang ini, saat pnpm melihatnya, ia tidak akan mencari di npmjs.org secara membabi buta. Sebaliknya, ia akan langsung menuju ke koordinat perusahaan yang Anda tentukan.

Keputusan Utama: Group Level vs. Project Level

Di GitLab, ini seperti memutuskan di mana Anda akan menyimpan bumbu-bumbu Anda:

Level	Deskripsi
Project Level (Tingkat Proyek)	Seperti brankas pribadi koki, hanya dapat digunakan untuk hidangan tertentu. Penyiapannya agak membosankan karena setiap paket memerlukan konfigurasi mandiri.
Group Level (Tingkat Grup)	Ini adalah konsep “Dapur Pusat”—sangat direkomendasikan! Cukup siapkan sekali, dan puluhan atau bahkan ratusan paket di bawah grup yang sama dapat berbagi pengaturan dan kredensial yang sama.

Menyiapkan “Paspor”: Access Token dan Variabel Lingkungan

Untuk masuk ke gudang pangan bawah tanah, Anda perlu mendapatkan “kartu akses” terlebih dahulu.

Buka Settings > Access Tokens di GitLab.
Ajukan Token, centang izin read_api (untuk mengunduh) dan write_package_registry (untuk memublikasikan).
Penting: Setelah Anda mendapatkan Token, jangan pernah menulisnya langsung secara hardcode di kode atau file .npmrc Anda! Itu seperti meninggalkan kunci brankas di pintu.

Pendekatan paling profesional adalah menyembunyikannya di “variabel lingkungan”. Tambahkan baris ini ke terminal Mac atau Linux Anda (misalnya, ~/.zshrc):

export GITLAB_TOKEN="GitLab_Token_Anda"

Dengan cara ini, sistem akan secara otomatis melampirkan kredensial untuk Anda, menjadikannya aman sekaligus nyaman.

Pengaturan Navigasi: Inti dari `.npmrc`

Selanjutnya, kita akan membuat peta navigasi, .npmrc, di akar proyek untuk memberi tahu pnpm ke mana harus pergi:

# Untuk apa pun yang dimulai dengan @my-company, pergilah ke GitLab
@my-company:registry=https://gitlab.com/api/v4/groups/<YOUR_GROUP_ID>/-/packages/npm/

# Atur autentikasi kartu akses (membaca variabel lingkungan yang baru saja kita buat)
//gitlab.com/api/v4/groups/<YOUR_GROUP_ID>/-/packages/npm/:_authToken="${GITLAB_TOKEN}"

Cukup ganti Group ID perusahaan Anda, dan jalan pun terbuka lebar!

Langkah Terakhir Sebelum Publikasi: Seni Pengemasan

Banyak orang terburu-buru memublikasikan paket setelah menyiapkan koneksi, hanya untuk secara tidak sengaja mengunggah file pengujian atau bahkan konfigurasi rahasia. Di sinilah bidang files dalam package.json sangat berguna.

Ini adalah konsep “allowlist” (daftar putih):

{
  "name": "@my-company/lib-1",
  "files": [
    "dist"
  ],
  "publishConfig": {
    "registry": "https://gitlab.com/api/v4/projects/<YOUR_PROJECT_ID>/packages/npm/"
  }
}

Pengaturan	Deskripsi
`files`	Beri tahu sistem secara eksplisit bahwa saya hanya ingin memublikasikan esensi yang dikompilasi di dalam `dist`, meninggalkan semua kekacauan lainnya.
`publishConfig`	Ini adalah asuransi ganda, memastikan paket ini tidak akan pernah secara tidak sengaja dipublikasikan ke laut lepas (npmjs.org).

Sebelum memublikasikan, disarankan untuk menggunakan perintah pnpm pack untuk membongkar dan memeriksa konten secara lokal. Setelah semuanya terlihat baik, jalankan pnpm publish dengan percaya diri!

Kesimpulan

Membangun dapur privat tidaklah sulit. Kuncinya adalah:

Ajukan Token dan lindungi dengan variabel lingkungan.
Konfigurasikan peta navigasi .npmrc yang benar.
Gunakan bidang files dalam package.json untuk pengiriman yang tepat.

Dengan menguasai alur kerja ini, Anda dapat membuat penggunaan kembali kode perusahaan Anda menjadi profesional, aman, dan elegan. Sekarang, bangunlah dapur pusat Anda sendiri!