Apakah Anda mencoba menggunakan Private Package di proyek perusahaan Anda tetapi terjebak pada konfigurasi .npmrc?

Mengapa Anda masih mendapatkan 404 Not Found bahkan setelah mengatur Token?

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

Memecahkan Dua Mitos .npmrc

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

Sederhananya, logika intinya hanya dua hal: Scope Mapping dan Authentication.

1. Scope Mapping

Ini memberitahu npm: Ketika Anda melihat paket yang dimulai dengan @company, jangan pergi ke npmjs.org resmi, pergilah ke GitLab Registry yang kami tentukan.

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

2. Authentication

Dengan alamat tersebut, Anda juga memerlukan kunci. Kuncinya 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, ini akan menyebabkan kegagalan izin
//gitlab.com/api/v4/:_authToken=${GITLAB_TOKEN}

Banyak orang gagal dalam konfigurasi sering kali karena jalurnya memiliki garis miring tambahan atau kurang satu tingkat.

Neraka Ketergantungan dan Kesalahan 404

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

Mengapa ini terjadi? Itu karena ketika npm menyelesaikan ketergantungan, jika tidak ada hubungan yang benar, ia akan tersesat.

Terutama ketika Anda memiliki dua Scope yang berbeda (misalnya @team-a dan @team-b) di Grup GitLab yang berbeda, .npmrc menjadi sangat kompleks dan sulit dipelihara. Ditambah lagi, Registry yang berbeda mungkin memerlukan Token yang berbeda, mengelola variabel lingkungan ini saja sudah melelahkan.

Apakah ada cara yang lebih cerdas?

Solusi yang Disarankan: Unified Download Group Registry & Independent Publish Project Registry

Mengapa Melakukan Ini?

Konfigurasi dalam Tindakan

Anda dapat langsung menyalin templat ini:

Ingatlah untuk menyerahkan tugas melindungi Token ke variabel lingkungan, jangan pernah melakukan hardcode Token dalam kode!

# .npmrc
# @company scope menggunakan registry level group
# Semua paket @company/* akan diinstal dari registry ini
@company:registry=https://gitlab.com/api/v4/groups/YOUR_GROUP_ID/-/packages/npm/

# Konfigurasi autentikasi GitLab npm registry
# Gunakan token autentikasi gitlab.com umum (mencakup semua permintaan level group dan project)
//gitlab.com/api/v4/groups/YOUR_GROUP_ID/-/packages/npm/:_authToken=${GITLAB_NPM_TOKEN}
# Gunakan registry proyek untuk menerbitkan paket
//gitlab.com/api/v4/projects/YOUR_PROJECT_ID/packages/npm/:_authToken=${GITLAB_NPM_TOKEN}


# Paket publik lainnya tetap masuk ke registry 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 “Unified Download Group Registry” dan “Independent Publish Project Registry”, kita dapat mengurangi biaya pemeliharaan secara signifikan dan membuat alur pengembangan lebih lancar.

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