Mengelola paket Node.js

Halaman ini menjelaskan tugas-tugas berikut:

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

Sebelum memulai

1. Jika repositori target tidak ada, buat repositori baru.
2. Pastikan Anda memiliki izin yang diperlukan untuk repositori.
3. Konfigurasi autentikasi untuk npm.
4. (Opsional) Konfigurasi default untuk perintah gcloud.
5. Jika Anda menggunakan credential helper 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: Penulis Artifact Registry (roles/artifactregistry.writer)
• Menghapus paket: Administrator Repositori Artifact Registry (roles/artifactregistry.repoAdmin)

Untuk mengetahui informasi selengkapnya tentang pemberian 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 memperbarui token akses.

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

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

     npx google-artifactregistry-auth
     

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

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

• Tambahkan skrip ke file package.json di 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 di file .npmrc project Anda dan menggunakannya untuk menambahkan kredensial token ke file .npmrc pengguna Anda. Menyimpan token di 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 tertentu dari paket satu kali. Ini adalah batasan npm untuk memastikan bahwa konten versi paket yang dipublikasikan selalu sama. Akibatnya, Anda tidak dapat:

• Menimpa 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 Anda pada tahap pengembangan tertentu, pertimbangkan untuk memublikasikan paket Anda dengan tag, seperti beta atau dev.

Artifact Registry menerapkan nama paket huruf kecil alfanumerik 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 credential helper untuk mengautentikasi dengan token akses, dapatkan token baru.

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

   Untuk menandai 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 credential helper 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 Repositori di Google Cloud konsol.

   Buka halaman Repositori

2. Dalam daftar repositori, klik repositori yang sesuai.

   Halaman Paket mencantumkan paket di repositori.

3. Klik paket untuk melihat versi paket.

gcloud

Untuk mencantumkan 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 flag ini untuk menggunakan default.
• LOCATION adalah lokasi repositori regional atau multi-regional. Gunakan tanda 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 Google Cloud konsol 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 di repositori, file di semua versi paket tertentu, atau file di versi tertentu dari paket.

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

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

gcloud artifacts files list

Untuk mencantumkan file di project, repositori, dan lokasi tertentu, 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: your Google Cloud project ID. Jika project ID Anda berisi titik dua (:), lihat Project dengan 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

Menandai 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 Repositori di Google Cloud konsol.

   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]

Di mana

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

Misalnya, untuk melihat tag 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 tertentu dari paket.

Untuk memberi tag pada gambar yang ada di repositori:

Konsol

1. Buka halaman Repositori di Google Cloud konsol.

   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]

Di 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 tanda ini untuk melihat repositori di lokasi tertentu. Jika Anda mengonfigurasi lokasi default, Anda dapat menghapus flag ini untuk menggunakan lokasi default.
• REPOSITORY adalah nama repositori. Jika Anda mengonfigurasi repositori default, Anda dapat menghapus tanda ini untuk menggunakan default.

Misalnya, untuk membuat tag release-candidate untuk paket versi 1.0.0 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 Repositori di Google Cloud konsol.

   Buka halaman Repositori

2. Klik paket untuk melihat versi paket.

3. Pilih versi paket dengan tag yang akan 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]

Di 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 tanda ini untuk melihat repositori di lokasi tertentu. Jika Anda mengonfigurasi lokasi default, Anda dapat menghapus flag ini untuk menggunakan lokasi default.
• REPOSITORY adalah nama repositori. Jika Anda mengonfigurasi repositori default, Anda dapat menghapus tanda ini untuk menggunakan default.

Misalnya, untuk mengubah tag 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

Membatalkan pemberian tag pada versi paket

Anda dapat menghapus tag yang ada dari versi paket.

Untuk menghapus tag:

Konsol

1. Buka halaman Repositori di Google Cloud konsol.

   Buka halaman Repositori

2. Klik gambar untuk melihat versi gambar.

3. Pilih versi gambar yang akan dihapus 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]

Di mana

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

   yarn

   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 Anda 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 tersebut tersedia di keduanya.

test-repo memiliki nilai prioritas terendah dan akan menayangkan artefak yang disimpan jika tidak ada repositori upstream lain 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 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 tersebut. Ini adalah batasan npm untuk memastikan bahwa konten versi paket yang dipublikasikan selalu sama.

Jika Anda ingin mendorong pengguna untuk menginstal versi paket yang diperbarui, 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 tidak digunakan lagi.

Sebelum menghapus paket atau versi paket, pastikan Anda telah mengomunikasikan atau mengatasi semua dependensi penting di dalamnya.

Untuk menghapus paket:

Konsol

1. Buka halaman Repositori di Google Cloud konsol.

   Buka halaman Repositori

2. Dalam daftar repositori, klik repositori yang sesuai.

   Halaman Paket mencantumkan paket di repositori.

3. Pilih paket yang ingin Anda hapus.

4. Klik DELETE.

5. Di kotak dialog konfirmasi, klik HAPUS.

gcloud

Jalankan perintah berikut:

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

Ganti kode berikut:

• PACKAGE adalah nama paket di repositori.
• 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 tanda 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 Repositori di Google Cloud konsol.

   Buka halaman Repositori

2. Dalam 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 Anda hapus.

5. Klik DELETE.

6. Di kotak dialog konfirmasi, klik HAPUS.

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 Anda mengonfigurasi repositori default, Anda dapat menghapus tanda ini untuk menggunakan default.
• LOCATION adalah lokasi repositori regional atau multi-regional. Gunakan tanda 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 berikutnya

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