Mengelola paket Node.js

Halaman ini menjelaskan tugas berikut:

• Melihat dan menghapus paket serta versi paket
• Melihat, membuat, memperbarui, dan menghapus tag

Sebelum memulai

1. Jika repositori target tidak ada, buat repositori baru.
2. Verifikasi bahwa Anda memiliki izin yang diperlukan untuk repositori.
3. Mengonfigurasi autentikasi untuk npm.
4. (Opsional) Konfigurasikan default untuk perintah gcloud.
5. Jika Anda menggunakan helper kredensial npm untuk autentikasi, dapatkan token akses sebelum terhubung ke repositori dengan npm.

Peran yang diperlukan

Untuk mendapatkan izin yang Anda perlukan untuk mengelola paket, minta administrator untuk memberi Anda peran IAM berikut di repositori:

• Melihat paket, file dalam paket, dan tag: Pembaca Artifact Registry (roles/artifactregistry.reader)
• Mendownload atau menginstal paket: Pembaca Artifact Registry (roles/artifactregistry.reader)
• Menambahkan paket ke repositori: Artifact Registry Writer (roles/artifactregistry.writer)
• Menghapus paket: Artifact Registry Repository Administrator (roles/artifactregistry.repoAdmin)

Untuk mengetahui informasi selengkapnya tentang cara memberikan peran, lihat Mengelola akses ke project, folder, dan organisasi.

Anda mungkin juga bisa mendapatkan izin yang diperlukan melalui peran khusus atau peran bawaan lainnya.

Mendapatkan token akses

Token akses berlaku selama 60 menit. Buat token akses sesaat sebelum menjalankan perintah yang berinteraksi dengan repositori.

Untuk mendapatkan token, gunakan salah satu opsi berikut:

• Gunakan perintah npx untuk memuat ulang token akses.

  1. Pastikan kredensial untuk terhubung ke registry npm publik ada dalam file konfigurasi npm pengguna Anda, ~/.npmrc.

  2. Jalankan perintah berikut di direktori project Node.js Anda.

     npx google-artifactregistry-auth
     

     Jika repositori Artifact Registry ditetapkan sebagai registry global dan paket Anda tidak dicakup, gunakan perintah berikut agar perintah dapat mendownload helper kredensial dari registry npm publik, bukan repositori Artifact Registry Anda.

     npm_config_registry=https://registry.npmjs.org npx google-artifactregistry-auth
     

• Tambahkan skrip ke file package.json dalam project Anda.

  "scripts": {
   "artifactregistry-login": "npx google-artifactregistry-auth"
  }
  

  Jalankan skrip di direktori project Node.js Anda.

  npm run artifactregistry-login
  

Artifact Registry membaca setelan repositori Artifact Registry dalam file .npmrc project Anda dan menggunakannya untuk menambahkan kredensial token ke file .npmrc pengguna Anda. Menyimpan token dalam file .npmrc pengguna akan mengisolasi kredensial Anda dari kode sumber dan sistem kontrol sumber Anda.

Menambahkan paket

Mode repositori: standar

Anda hanya dapat memublikasikan versi paket tertentu satu kali. Ini adalah batasan npm untuk memastikan bahwa konten versi paket yang dipublikasikan selalu sama. Akibatnya, Anda tidak dapat:

• Menutupi versi paket dengan memublikasikannya lagi ke repositori
• Menghapus paket atau versinya dari repositori, lalu memublikasikan paket dengan nama dan nomor versi yang sama

Jika Anda tidak menentukan tag saat memublikasikan paket, npm akan menambahkan tag latest. Untuk menyederhanakan penginstalan paket pada tahap pengembangan tertentu, pertimbangkan untuk memublikasikan paket dengan tag, seperti beta atau dev.

Artifact Registry menerapkan nama paket alfanumerik huruf kecil untuk paket npm.

Untuk menambahkan paket:

1. Pastikan nama paket di package.json menyertakan cakupan yang dikonfigurasi untuk repositori Anda. Contoh berikut menunjukkan paket dengan cakupan dev-repo.

   "name": "@dev-repo/my-package"
   

2. Jika Anda menggunakan helper kredensial untuk mengautentikasi dengan token akses, dapatkan token baru.

3. Tambahkan paket ke repositori. Anda dapat menggunakan perintah npm atau yarn.

   Untuk memberi tag pada paket, sertakan flag --tag dan ganti TAG dengan tag yang ingin Anda gunakan. Jika Anda tidak menyertakan flag --tag, npm akan otomatis menetapkan tag ke latest.

   npm publish --tag=TAG
   

   yarn publish --tag TAG
   

Melihat paket dan versi

Mode repositori: standar, jarak jauh, virtual

Untuk mendapatkan informasi paket dengan npm atau yarn:

1. Jika Anda menggunakan helper kredensial untuk mengautentikasi dengan token akses, dapatkan token baru.

2. Jalankan perintah yang sesuai:

   npm view
   

   yarn info
   

Untuk melihat paket dan versi paket menggunakan konsol Google Cloud atau gcloud:

Konsol

1. Buka halaman Repositories di konsol Google Cloud.

   Buka halaman Repositori

2. Di daftar repositori, klik repositori yang sesuai.

   Halaman Paket mencantumkan paket di repositori.

3. Klik paket untuk melihat versi paket.

gcloud

Untuk menampilkan daftar paket dalam repositori, jalankan perintah berikut:

gcloud artifacts packages list [--repository=REPOSITORY] [--location=LOCATION]

Ganti kode berikut:

• REPOSITORY adalah nama repositori. Jika Anda mengonfigurasi repositori default, Anda dapat menghapus tanda ini untuk menggunakan default.
• LOCATION adalah lokasi repositori regional atau multi-regional. Jika Anda mengonfigurasi lokasi default, Anda dapat menghilangkan tanda ini untuk menggunakan default.

Untuk melihat versi paket, jalankan perintah berikut:

gcloud artifacts versions list --package=PACKAGE \
    [--repository=REPOSITORY] [--location=LOCATION]

Ganti kode berikut:

• PACKAGE adalah ID paket atau ID yang sepenuhnya memenuhi syarat untuk paket.
• REPOSITORY adalah nama repositori. Jika Anda mengonfigurasi repositori default, Anda dapat menghapus tanda ini untuk menggunakan default.
• LOCATION adalah lokasi repositori regional atau multi-regional. Gunakan flag ini untuk melihat repositori di lokasi tertentu. Jika Anda mengonfigurasi lokasi default, Anda dapat menghilangkan tanda ini untuk menggunakan default.

Melihat paket dan versi dari Konsol Google Cloud atau gcloud CLI hanya tersedia untuk repositori standar dan jarak jauh.

Untuk repositori jarak jauh, daftar yang ditampilkan harus menyertakan semua dependensi langsung dan transitif yang di-cache di repositori.

Mencantumkan file

Mode repositori: standar, jarak jauh

Anda dapat mencantumkan file dalam repositori, file dalam semua versi paket yang ditentukan, atau file dalam versi paket tertentu.

Untuk semua perintah berikut, Anda dapat menetapkan jumlah maksimum file yang akan ditampilkan dengan menambahkan flag --limit ke perintah.

Untuk mencantumkan semua file dalam project, repositori, dan lokasi default saat nilai default dikonfigurasi:

gcloud artifacts files list

Untuk mencantumkan file dalam project, repositori, dan lokasi yang ditentukan, jalankan perintah:

gcloud artifacts files list \
    --project=PROJECT \
    --repository=REPOSITORY \
    --location=LOCATION

Untuk mencantumkan file untuk semua versi paket tertentu:

gcloud artifacts files list \
    --project=PROJECT \
    --repository=REPOSITORY \
    --location=LOCATION \
    --package=PACKAGE

Untuk mencantumkan file untuk versi paket tertentu:

gcloud artifacts files list \
    --project=PROJECT \
    --repository=REPOSITORY \
    --location=LOCATION \
    --package=PACKAGE \
    --version=VERSION

Untuk mencantumkan file untuk tag tertentu:

gcloud artifacts files list \
    --project=PROJECT \
    --repository=REPOSITORY \
    --location=LOCATION \
    --package=PACKAGE \
    --tag=TAG

Ganti nilai berikut:

• LOCATION: lokasi regional atau multi-regional repositori.
• PROJECT: Google Cloud project ID Anda. Jika project ID Anda berisi titik dua (:), lihat Project cakupan domain.
• REPOSITORY: nama repositori tempat image disimpan.
• PACKAGE: nama paket.
• VERSION: versi paket.
• TAG: tag yang terkait dengan paket.

Contoh

Pertimbangkan informasi paket berikut:

• Project: my-project
• Repositori: my-repo
• Lokasi repositori: us-west1
• Paket: my-app

Perintah berikut mencantumkan semua file di repositori my-repo di lokasi us-west1 dalam project default:

gcloud artifacts files list \
    --location=us-west1 \
    --repository=my-repo

Perintah berikut mencantumkan file dalam versi 1.0 paket.

gcloud artifacts files list \
    --project=my-project \
    --location=us-west1 \
    --repository=my-repo \
    --package=my-app \
    --version=1.0

Perintah berikut mencantumkan file dalam versi paket dengan tag 1.0-dev

gcloud artifacts files list \
    --project=my-project \
    --location=us-west1 \
    --repository=my-repo \
    --package=my-app \
    --tag=1.0-dev

Memberi tag pada paket

Mode repositori: standar

Anda dapat melihat, menambahkan, memperbarui, dan menghapus tag. Tag dapat membantu Anda mengelola versi semantik paket dan menyederhanakan penginstalan paket pada tahap pengembangan tertentu.

Misalnya, Anda dapat memberi tag pada build kandidat rilis saat ini dengan rc. Tim Anda kemudian dapat menginstal versi yang benar berdasarkan tag, bukan penentu versi, dan membatalkan publikasi versi pra-rilis yang tidak digunakan tidak akan merusak dependensi Anda pada paket kandidat rilis.

Melihat tag

Untuk melihat tag paket:

Konsol

1. Buka halaman Repositories di konsol Google Cloud.

   Buka halaman Repositori

2. Klik paket untuk melihat versi dan tag terkait.

3. Pilih versi paket yang akan diberi tag.

4. Di baris versi yang dipilih, klik Tindakan lainnya (), lalu klik Edit tag.

5. Ketik tag baru ke dalam kolom, lalu klik SIMPAN.

gcloud

Jalankan perintah:

gcloud artifacts tags list --package=PACKAGE \
    [--repository=REPOSITORY] [--location=LOCATION]

Dari mana

• PACKAGE adalah nama paket dalam repositori.
• REPOSITORY adalah nama repositori. Jika mengonfigurasi repositori default, Anda dapat menghapus tanda ini untuk menggunakan default.
• LOCATION adalah lokasi regional atau multi-regional. Gunakan flag ini untuk melihat repositori di lokasi tertentu. Jika Anda mengonfigurasi lokasi default, Anda dapat menghapus flag ini untuk menggunakan default.

Misalnya, untuk melihat tag untuk paket my-package di repositori my-repo di lokasi default, jalankan perintah:

gcloud artifacts tags list --package=my-pkg --repository=my-repo

Membuat tag

Anda dapat membuat tag untuk versi paket tertentu.

Untuk memberi tag pada gambar yang ada di repositori:

Konsol

1. Buka halaman Repositories di konsol Google Cloud.

   Buka halaman Repositori

2. Klik paket untuk melihat versi paket.

3. Pilih versi paket yang akan diberi tag.

4. Di baris versi yang dipilih, klik Tindakan lainnya (), lalu klik Edit tag.

5. Ketik tag baru ke dalam kolom, lalu klik SIMPAN.

gcloud

Jalankan perintah berikut:

gcloud artifacts tags create TAG --package=PACKAGE \
    version=VERSION [--location=LOCATION] [--repository=REPOSITORY]

Dari mana

• TAG adalah tag yang ingin Anda terapkan ke paket.
• PACKAGE adalah nama paket di repositori.
• VERSION adalah versi paket yang ingin Anda beri tag.
• LOCATION adalah lokasi regional atau multi-regional. Gunakan flag ini untuk melihat repositori di lokasi tertentu. Jika Anda mengonfigurasi lokasi default, Anda dapat menghapus flag ini untuk menggunakan default.
• REPOSITORY adalah nama repositori. Jika mengonfigurasi repositori default, Anda dapat menghapus tanda ini untuk menggunakan default.

Misalnya, untuk membuat tag release-candidate untuk versi 1.0.0 paket my-package di repositori my-repo di lokasi default, jalankan perintah:

gcloud artifacts tags create release-candidate --version=1.0.0 \
    --package=my-pkg --repository=my-repo

Memperbarui tag

Anda dapat mengubah tag yang terkait dengan versi paket.

Untuk mengubah tag yang ada:

Konsol

1. Buka halaman Repositories di konsol Google Cloud.

   Buka halaman Repositori

2. Klik paket untuk melihat versi paket.

3. Pilih versi paket dengan tag yang ingin diubah.

4. Di baris versi yang dipilih, klik Tindakan lainnya (), lalu klik Edit tag.

5. Edit tag, lalu klik SIMPAN.

gcloud

Jalankan perintah berikut:

gcloud artifacts tags update TAG --package=PACKAGE \
    version=VERSION [--location=LOCATION] [--repository=REPOSITORY]

Dari mana

• TAG adalah tag yang ingin Anda terapkan ke paket.
• PACKAGE adalah nama paket di repositori.
• VERSION adalah versi paket yang ingin Anda beri tag.
• LOCATION adalah lokasi regional atau multi-regional. Gunakan flag ini untuk melihat repositori di lokasi tertentu. Jika Anda mengonfigurasi lokasi default, Anda dapat menghapus flag ini untuk menggunakan default.
• REPOSITORY adalah nama repositori. Jika mengonfigurasi repositori default, Anda dapat menghapus tanda ini untuk menggunakan default.

Misalnya, untuk mengubah tag untuk versi 1.0.0 paket my-package menjadi production di repositori my-repo di lokasi default, jalankan perintah:

gcloud artifacts tags update production --version=1.0.0 \
    --package=my-pkg --repository=my-repo

Menghapus tag versi paket

Anda dapat menghapus tag yang ada dari versi paket.

Untuk menghapus tag:

Konsol

1. Buka halaman Repositories di konsol Google Cloud.

   Buka halaman Repositori

2. Klik gambar untuk melihat versi gambar.

3. Pilih versi gambar yang akan dibatalkan tagnya.

4. Di baris versi yang dipilih, klik Tindakan lainnya (), lalu klik Edit tag.

5. Hapus tag, lalu klik SIMPAN.

gcloud

Jalankan perintah berikut:

gcloud artifacts tags delete TAG --package=PACKAGE \
    [--location=<LOCATION] [--repository=REPOSITORY]

Dari mana

• TAG adalah tag yang ingin Anda terapkan ke paket.
• PACKAGE adalah nama paket di repositori.
• LOCATION adalah lokasi regional atau multi-regional. Gunakan flag ini untuk melihat repositori di lokasi tertentu. Jika Anda mengonfigurasi lokasi default, Anda dapat menghapus flag ini untuk menggunakan default.
• REPOSITORY adalah nama repositori. Jika mengonfigurasi repositori default, Anda dapat menghapus tanda ini untuk menggunakan default.

Misalnya, untuk menghapus tag release-candidate dari paket my-package di repositori my-repo di lokasi default, jalankan perintah:

gcloud artifacts tags delete release-candidate --package=my-pkg \
    --repository=my-repo

Menginstal paket

Mode repositori: standar, jarak jauh, virtual

Untuk menginstal paket dari repositori paket Node.js:

1. Jika Anda menggunakan helper kredensial untuk mengautentikasi dengan token akses, dapatkan token baru.

2. Gunakan perintah npm install atau yarn add.

   npm

   Untuk menginstal versi dengan tag latest:

   npm install @SCOPE/PACKAGE
   

   Untuk menginstal versi dengan tag yang berbeda:

   npm install @SCOPE/PACKAGE@TAG
   

   Untuk menginstal versi tertentu:

   npm install @SCOPE/PACKAGE@VERSION
   

   benang

   Untuk menginstal versi dengan tag latest:

   yarn add @SCOPE/PACKAGE
   

   Untuk menginstal versi dengan tag yang berbeda:

   yarn add @SCOPE/PACKAGE@TAG
   

   Untuk menginstal versi tertentu:

   yarn add @SCOPE/PACKAGE@VERSION
   

   Ganti nilai berikut:

   • SCOPE adalah cakupan yang terkait dengan repositori. Jika repositori paket Node.js Anda tidak dikonfigurasi dengan cakupan, hapus @SCOPE/ dari perintah.
   • PACKAGE adalah nama paket di repositori.
   • TAG adalah tag untuk versi yang ingin Anda instal.
   • VERSION adalah nomor versi yang ingin Anda instal.

Saat menentukan paket sebagai dependensi di package.json, pastikan Anda menyertakan cakupan untuk repositori. Contoh berikut menunjukkan cakupan @dev-repo untuk paket bernama my-package.

"dependencies": {
  "@dev-repo/my-package": ">=1.0.0"
}

Untuk repositori standar, Anda mendownload paket langsung dari repositori.

Untuk repositori jarak jauh, Anda mendownload salinan paket yang di-cache dan dependensinya. Jika salinan yang di-cache tidak ada, repositori jarak jauh akan mendownload paket dari sumber upstream dan meng-cache-nya sebelum menayangkannya kepada Anda. Anda dapat memverifikasi bahwa repositori jarak jauh mengambil paket dari sumber upstream dengan melihat daftar paket di repositori.

Untuk repositori virtual, Artifact Registry menelusuri repositori upstream untuk paket yang diminta.

• Repositori jarak jauh upstream akan mendownload dan meng-cache paket yang diminta jika salinan yang di-cache tidak ada. Repositori virtual hanya menayangkan paket yang diminta, bukan menyimpannya.
• Jika Anda meminta versi yang tersedia di lebih dari satu repositori upstream, Artifact Registry akan memilih repositori upstream yang akan digunakan berdasarkan setelan prioritas yang dikonfigurasi untuk repositori virtual.

Misalnya, pertimbangkan repositori virtual dengan setelan prioritas berikut untuk repositori upstream:

• main-repo: Prioritas ditetapkan ke 100
• secondary-repo1: Prioritas ditetapkan ke 80.
• secondary-repo2: Prioritas ditetapkan ke 80.
• test-repo: Prioritas ditetapkan ke 20.

main-repo memiliki nilai prioritas tertinggi, sehingga repositori virtual selalu menelusurinya terlebih dahulu.

secondary-repo1 dan secondary-repo2 memiliki prioritas yang ditetapkan ke 80. Jika paket yang diminta tidak tersedia di main-repo, Artifact Registry akan menelusuri repositori ini berikutnya. Karena keduanya memiliki nilai prioritas yang sama, Artifact Registry dapat memilih untuk menayangkan paket dari salah satu repositori jika versi tersedia di keduanya.

test-repo memiliki nilai prioritas terendah dan akan menayangkan artefak yang disimpan jika tidak ada repositori upstream lainnya yang memilikinya.

Menghapus paket

Mode repositori: standar, jarak jauh

Anda dapat menghapus paket dan semua versinya, atau menghapus versi tertentu.

• Setelah menghapus paket, Anda tidak dapat mengurungkan tindakan tersebut.
• Untuk repositori jarak jauh, hanya salinan paket yang di-cache yang akan dihapus. Sumber upstream tidak terpengaruh. Jika Anda menghapus paket yang di-cache, Artifact Registry akan mendownload dan meng-cache-nya lagi saat repositori menerima permintaan untuk versi paket yang sama.

Setelah versi paket dipublikasikan, Anda tidak dapat memublikasikan ulang paket dengan kombinasi nama dan versi yang sama, bahkan setelah menghapus versi. Ini adalah batasan npm untuk memastikan bahwa konten versi paket yang dipublikasikan selalu sama.

Jika Anda ingin mendorong pengguna untuk menginstal versi paket yang diupdate, gunakan perintah npm deprecate untuk menandai versi lama paket sebagai tidak digunakan lagi. Saat pengguna mencoba menginstal paket yang tidak digunakan lagi, Artifact Registry akan menampilkan peringatan penghentian penggunaan.

Sebelum menghapus paket atau versi paket, pastikan Anda telah menyampaikan atau mengatasi dependensi penting apa pun di dalamnya.

Untuk menghapus paket:

Konsol

1. Buka halaman Repositories di konsol Google Cloud.

   Buka halaman Repositori

2. Di daftar repositori, klik repositori yang sesuai.

   Halaman Paket mencantumkan paket di repositori.

3. Pilih paket yang ingin dihapus.

4. Klik HAPUS.

5. Di kotak dialog konfirmasi, klik DELETE.

gcloud

Jalankan perintah berikut:

gcloud artifacts packages delete PACKAGE \
    [--repository=REPOSITORY] [--location=LOCATION] [--async]

Ganti kode berikut:

• PACKAGE adalah nama paket dalam repositori.
• REPOSITORY adalah nama repositori. Jika mengonfigurasi repositori default, Anda dapat menghapus tanda ini untuk menggunakan default.
• LOCATION adalah lokasi repositori regional atau multi-regional. Gunakan flag ini untuk melihat repositori di lokasi tertentu. Jika Anda mengonfigurasi lokasi default, Anda dapat menghilangkan tanda ini untuk menggunakan default.

Flag --async menyebabkan perintah segera ditampilkan, tanpa menunggu operasi yang sedang berlangsung selesai.

Untuk menghapus versi paket:

Konsol

1. Buka halaman Repositories di konsol Google Cloud.

   Buka halaman Repositori

2. Di daftar repositori, klik repositori yang sesuai.

   Halaman Paket mencantumkan paket di repositori.

3. Klik paket untuk melihat versi paket tersebut.

4. Pilih versi yang ingin dihapus.

5. Klik HAPUS.

6. Di kotak dialog konfirmasi, klik DELETE.

gcloud

Jalankan perintah berikut:

gcloud artifacts versions delete VERSION \
    --package=PACKAGE \
    [--repository=REPOSITORY] [--location=LOCATION] \
    [--async]

Ganti kode berikut:

• VERSION adalah nama versi yang akan dihapus.
• PACKAGE adalah nama paket di repositori.
• REPOSITORY adalah nama repositori. Jika mengonfigurasi repositori default, Anda dapat menghapus tanda ini untuk menggunakan default.
• LOCATION adalah lokasi repositori regional atau multi-regional. Gunakan flag ini untuk melihat repositori di lokasi tertentu. Jika Anda mengonfigurasi lokasi default, Anda dapat menghilangkan tanda ini untuk menggunakan default.

Flag --async menyebabkan perintah segera ditampilkan, tanpa menunggu operasi yang sedang berlangsung selesai.

Langkah selanjutnya

• Pelajari cara mengelola paket Maven
• Pelajari cara mengelola image container
• Mendownload file satu per satu dalam paket