Apakah Anda terjebak pada konfigurasi .npmrc karena proyek perusahaan Anda perlu menggunakan Private Package?

Mengapa masih menampilkan 404 Not Found meskipun Token sudah diatur?

Ketika sebuah perusahaan memiliki beberapa tim dan beberapa paket (misalnya @frontend, @backend), bagaimana Anda bisa mengelola .npmrc dengan elegan?

Membongkar Dua Mitos .npmrc

Untuk memahami .npmrc, Anda perlu memahami cara kerjanya terlebih dahulu.

Sederhananya, logika intinya bermuara pada dua hal: Pemetaan Cakupan (Scope Mapping) dan Autentikasi (Authentication).

1. Pemetaan Cakupan (Scope Mapping)

Ini memberi tahu npm: Ketika Anda melihat paket yang dimulai dengan @company, jangan mencarinya di npmjs.org resmi, tetapi pergilah ke GitLab Registry yang kami tentukan.

@company:registry=https://gitlab.com/api/v4/groups/100/-/packages/npm/

2. Autentikasi (Authentication)

Dengan alamat tersebut, Anda juga memerlukan kunci. Kunci tersebut adalah AuthToken Anda.

Berikut adalah aturan yang sangat penting: URL Registry dan jalur AuthToken harus “cocok persis”.

# ✅ Benar: Jalur persis sama dengan registry yang ditentukan di atas
//gitlab.com/api/v4/groups/100/-/packages/npm/:_authToken=${GITLAB_TOKEN}

# ❌ Salah: Jalur tidak cocok, yang akan menyebabkan kegagalan izin
//gitlab.com/api/v4/:_authToken=${GITLAB_TOKEN}

Banyak orang gagal mengonfigurasi seringkali karena kelebihan garis miring atau kurang satu tingkat di jalur.

Neraka Dependensi dan Kesalahan 404

Situasi yang paling memusingkan adalah: Anda menginstal paket A, yang bergantung pada paket B (juga pribadi), dan kemudian npm memuntahkan 404 Not Found.

Mengapa ini terjadi? Itu karena npm tersesat saat menyelesaikan dependensi jika tidak ada korespondensi yang benar.

Terutama ketika Anda memiliki dua Cakupan yang berbeda (misalnya @team-a dan @team-b) di Grup GitLab yang berbeda, .npmrc bisa menjadi sangat rumit dan sulit dikelola. Ditambah dengan fakta bahwa Registry yang berbeda mungkin memerlukan Token yang berbeda, mengelola variabel lingkungan ini saja sudah cukup membuat Anda kenyang.

Apakah ada cara yang lebih cerdas?

Solusi yang Direkomendasikan: Unduh Terpadu Group Registry & Terbitkan Independen Project Registry

Mengapa melakukan ini?

Konfigurasi dalam Tindakan

Anda dapat menyalin template ini secara langsung:

Ingatlah untuk menyerahkan pekerjaan melindungi Token ke variabel lingkungan, jangan pernah meng-hardcode Token secara langsung dalam kode!

# .npmrc
# Token autentikasi tingkat domain umum (mencakup semua permintaan instalasi tingkat grup dan proyek)
//gitlab.com/:_authToken=${GITLAB_NPM_TOKEN}

# Untuk penerbitan: token autentikasi tingkat proyek (npm publish memerlukan pencocokan jalur yang tepat)
//gitlab.com/api/v4/projects/YOUR_PROJECT_ID/packages/npm/:_authToken=${GITLAB_NPM_TOKEN}

# cakupan @company menggunakan registry tingkat grup
# Semua paket @company/* akan diinstal dari registry ini
@company:registry=https://gitlab.com/api/v4/groups/YOUR_GROUP_ID/-/packages/npm/

# Paket publik lainnya tetap masuk ke perpustakaan resmi
registry=https://registry.npmjs.org/

Konfigurasikan publishConfig di package.json untuk menerbitkan paket ke GitLab Project Registry yang sesuai.

{
  "name": "@company/my-package",
  "publishConfig": {
    "@company:registry": "https://gitlab.com/api/v4/projects/YOUR_PROJECT_ID/packages/npm/"
  }
}

Kesimpulan

Melalui strategi “Unduh Terpadu Group Registry” dan “Terbitkan Independen Project Registry”, kita dapat secara signifikan mengurangi biaya pemeliharaan dan membuat proses pengembangan lebih lancar.

Menguasai logika ini, GitLab NPM Registry akan menjadi penolong yang kuat dalam proses pengembangan perusahaan Anda!