Gestionar paquetes de Node.js

En esta página se describen las siguientes tareas:

• Ver y eliminar paquetes y versiones de paquetes
• Ver, crear, actualizar y eliminar etiquetas

Antes de empezar

1. Si el repositorio de destino no existe, crea uno.
2. Verifica que tienes los permisos necesarios para el repositorio.
3. Configura la autenticación para npm.
4. (Opcional) Configura los valores predeterminados de los comandos de gcloud.
5. Si usas el asistente de credenciales de npm para la autenticación, obtén un token de acceso antes de conectarte a un repositorio con npm.

Roles obligatorios

Para obtener los permisos que necesitas para gestionar paquetes, pide a tu administrador que te conceda los siguientes roles de gestión de identidades y accesos en el repositorio:

• Ver paquetes, archivos de paquetes y etiquetas: Lector de Artifact Registry (roles/artifactregistry.reader)
• Descargar o instalar paquetes: Lector de Artifact Registry (roles/artifactregistry.reader)
• Añadir paquetes a un repositorio: Escritor de Artifact Registry (roles/artifactregistry.writer)
• Eliminar paquetes: Administrador de repositorios de Artifact Registry (roles/artifactregistry.repoAdmin)

Para obtener más información sobre cómo conceder roles, consulta el artículo Gestionar el acceso a proyectos, carpetas y organizaciones.

También puedes conseguir los permisos necesarios a través de roles personalizados u otros roles predefinidos.

Obtener un token de acceso

Los tokens de acceso son válidos durante 60 minutos. Genera un token de acceso poco antes de ejecutar comandos que interactúen con repositorios.

Para obtener un token, utiliza una de estas opciones:

• Usa el comando npx para actualizar el token de acceso.

  1. Asegúrate de que las credenciales para conectarte al registro público de npm estén en el archivo de configuración de npm de tu usuario, ~/.npmrc.

  2. Ejecuta el siguiente comando en el directorio de tu proyecto Node.js.

     npx google-artifactregistry-auth
     

     Si tu repositorio de Artifact Registry está configurado como registro global y tus paquetes no tienen un ámbito definido, usa el siguiente comando para que el comando pueda descargar el asistente de credenciales del registro público de npm en lugar de tu repositorio de Artifact Registry.

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

• Añade una secuencia de comandos al archivo package.json de tu proyecto.

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

  Ejecuta la secuencia de comandos en el directorio del proyecto de Node.js.

  npm run artifactregistry-login
  

Artifact Registry lee los ajustes del repositorio de Artifact Registry en el archivo .npmrc de tu proyecto y los usa para añadir credenciales de token al archivo .npmrc de tu usuario. Almacenar el token en el archivo .npmrc del usuario aísla tus credenciales de tu código fuente y de tu sistema de control de código fuente.

Añadir paquetes

Modos de repositorio: estándar

Solo puedes publicar una versión específica de un paquete una vez. Se trata de una restricción de npm para asegurarse de que el contenido de una versión publicada de un paquete sea siempre el mismo. Por lo tanto, no puedes hacer lo siguiente:

• Sobrescribir una versión de un paquete publicándola de nuevo en el repositorio
• Eliminar un paquete o su versión del repositorio y, a continuación, publicar un paquete con el mismo nombre y número de versión

Si no especificas una etiqueta al publicar un paquete, npm añade la etiqueta latest. Para simplificar la instalación de tus paquetes en una fase de desarrollo específica, te recomendamos que los publiques con una etiqueta, como beta o dev.

Artifact Registry aplica nombres de paquetes alfanuméricos en minúsculas para los paquetes npm.

Para añadir un paquete, sigue estos pasos:

1. Asegúrate de que el nombre del paquete en package.json incluya el ámbito configurado para tu repositorio. En el siguiente ejemplo se muestra un paquete con el ámbito dev-repo.

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

2. Si usas el asistente de credenciales para autenticarte con un token de acceso, obtén un nuevo token.

3. Añade paquetes al repositorio. Puedes usar el comando npm o yarn.

   Para etiquetar el paquete, incluye la marca --tag y sustituye TAG por la etiqueta que quieras usar. Si no incluye la marca --tag, npm asignará automáticamente la etiqueta latest.

   npm publish --tag=TAG
   

   yarn publish --tag TAG
   

Ver paquetes y versiones

Modos de repositorio: estándar, remoto y virtual

Para obtener información sobre un paquete con npm o yarn, sigue estos pasos:

1. Si usas el asistente de credenciales para autenticarte con un token de acceso, obtén un nuevo token.

2. Ejecuta el comando adecuado:

   npm view
   

   yarn info
   

Para ver los paquetes y las versiones de los paquetes mediante la consola Google Cloud o gcloud, sigue estos pasos:

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

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

Ver paquetes y versiones desde la consola de Google Cloud o la CLI de gcloud solo está disponible para repositorios estándar y remotos.

En el caso de los repositorios remotos, la lista devuelta debe incluir todas las dependencias directas y transitivas que estén almacenadas en caché en el repositorio.

Mostrar archivos

Modos de repositorio: estándar y remoto

Puedes enumerar los archivos de un repositorio, los archivos de todas las versiones de un paquete especificado o los archivos de una versión concreta de un paquete.

En todos los comandos siguientes, puedes definir un número máximo de archivos que se devuelvan añadiendo la marca --limit al comando.

Para enumerar todos los archivos del proyecto, el repositorio y la ubicación predeterminados cuando se configuran los valores predeterminados, haz lo siguiente:

gcloud artifacts files list

Para enumerar los archivos de un proyecto, un repositorio y una ubicación específicos, ejecuta el siguiente comando:

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

Para enumerar los archivos de todas las versiones de un paquete específico, haz lo siguiente:

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

Para enumerar los archivos de una versión específica de un paquete, sigue estos pasos:

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

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

Sustituye los siguientes valores:

• LOCATION: la ubicación regional o multirregional del repositorio.
• PROJECT: tu Google Cloud ID de proyecto. Si el ID de tu proyecto contiene dos puntos (:), consulta Proyectos con ámbito de dominio.
• REPOSITORY: el nombre del repositorio en el que se almacena la imagen.
• PACKAGE: el nombre del paquete.
• VERSION: la versión del paquete.
• TAG: la etiqueta asociada al paquete.

Ejemplos

Tenga en cuenta la siguiente información del paquete:

• Proyecto: my-project
• Repositorio: my-repo
• Ubicación del repositorio: us-west1
• Paquete: my-app

El siguiente comando muestra todos los archivos del repositorio my-repo en la ubicación us-west1 del proyecto predeterminado:

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

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

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

Etiquetar paquetes

Modos de repositorio: estándar

Puedes ver, añadir, actualizar y eliminar etiquetas. Las etiquetas pueden ayudarte a gestionar las versiones semánticas de tus paquetes y a optimizar la instalación de paquetes en una fase específica del desarrollo.

Por ejemplo, puedes etiquetar la compilación candidata actual con rc. De esta forma, tu equipo podrá instalar la versión correcta en función de la etiqueta en lugar de un especificador de versión, y al dejar de publicar versiones preliminares sin usar, no se romperán las dependencias del paquete de la versión candidata.

Ver etiquetas

Para ver las etiquetas de un paquete:

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

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

Crear etiquetas

Puedes crear una etiqueta para una versión específica de un paquete.

Para etiquetar una imagen de un repositorio, sigue estos pasos:

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

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

Actualizar etiquetas

Puedes cambiar una etiqueta asociada a una versión de un paquete.

Para cambiar una etiqueta, sigue estos pasos:

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

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

Eliminar etiquetas de versiones de paquetes

Puede quitar una etiqueta de una versión de un paquete.

Para quitar una etiqueta:

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

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

Instalar paquetes

Modos de repositorio: estándar, remoto y virtual

Para instalar un paquete desde el repositorio de paquetes de Node.js, sigue estos pasos:

1. Si usas el asistente de credenciales para autenticarte con un token de acceso, obtén un nuevo token.

2. Usa el comando npm install o yarn add.

   npm

   Para instalar la versión con la etiqueta latest, sigue estos pasos:

   npm install @SCOPE/PACKAGE
   

   Para instalar la versión con una etiqueta diferente, sigue estos pasos:

   npm install @SCOPE/PACKAGE@TAG
   

   Para instalar una versión específica, sigue estos pasos:

   npm install @SCOPE/PACKAGE@VERSION
   

   lana

   Para instalar la versión con la etiqueta latest, sigue estos pasos:

   yarn add @SCOPE/PACKAGE
   

   Para instalar la versión con una etiqueta diferente, sigue estos pasos:

   yarn add @SCOPE/PACKAGE@TAG
   

   Para instalar una versión específica, sigue estos pasos:

   yarn add @SCOPE/PACKAGE@VERSION
   

   Sustituye los siguientes valores:

   • SCOPE es el ámbito asociado al repositorio. Si tu repositorio de paquetes de Node.js no está configurado con un ámbito, omite @SCOPE/ del comando.
   • PACKAGE es el nombre del paquete en el repositorio.
   • TAG es la etiqueta de la versión que quieres instalar.
   • VERSION es el número de versión que quieres instalar.

Cuando especifiques un paquete como dependencia en package.json, asegúrate de incluir el ámbito del repositorio. En el siguiente ejemplo se muestra el ámbito @dev-repo de un paquete llamado my-package.

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

En los repositorios estándar, los paquetes se descargan directamente del repositorio.

En el caso de un repositorio remoto, se descarga una copia en caché del paquete y sus dependencias. Si no existe una copia almacenada en caché, el repositorio remoto descarga el paquete de la fuente upstream y lo almacena en caché antes de proporcionártelo. Para comprobar que el repositorio remoto ha obtenido los paquetes de la fuente de nivel superior, consulta la lista de paquetes del repositorio.

En el caso de un repositorio virtual, Artifact Registry busca el paquete solicitado en los repositorios upstream.

• Los repositorios remotos upstream descargarán y almacenarán en caché el paquete solicitado si no existe una copia en caché. Los repositorios virtuales solo sirven los paquetes solicitados, no los almacenan.
• Si solicita una versión que está disponible en más de un repositorio upstream, Artifact Registry elige un repositorio upstream que se va a usar en función de los ajustes de prioridad configurados para el repositorio virtual.

Por ejemplo, supongamos que tiene un repositorio virtual con los siguientes ajustes de prioridad para los repositorios upstream:

• main-repo: prioridad definida como 100
• secondary-repo1: prioridad establecida en 80.
• secondary-repo2: prioridad establecida en 80.
• test-repo: prioridad establecida en 20.

main-repo tiene el valor de prioridad más alto, por lo que el repositorio virtual siempre lo busca primero.

Tanto secondary-repo1 como secondary-repo2 tienen la prioridad 80. Si un paquete solicitado no está disponible en main-repo, Artifact Registry buscará en estos repositorios. Como ambos tienen el mismo valor de prioridad, Artifact Registry puede elegir servir un paquete de cualquiera de los dos repositorios si la versión está disponible en ambos.

test-repo tiene el valor de prioridad más bajo y servirá un artefacto almacenado si ninguno de los otros repositorios upstream lo tiene.

Eliminar paquetes

Modos de repositorio: estándar y remoto

Puedes eliminar un paquete y todas sus versiones, o bien eliminar una versión específica.

• Una vez que elimines un paquete, no podrás deshacer la acción.
• En el caso de los repositorios remotos, solo se elimina la copia almacenada en caché del paquete. La fuente upstream no se ve afectada. Si eliminas un paquete almacenado en caché, Artifact Registry lo descargará y lo almacenará en caché de nuevo la próxima vez que el repositorio reciba una solicitud para la misma versión del paquete.

Una vez que se ha publicado una versión de un paquete, no se puede volver a publicar un paquete con la misma combinación de nombre y versión, aunque se elimine la versión. Se trata de una restricción de npm para asegurarse de que el contenido de una versión publicada de un paquete sea siempre el mismo.

Si quieres animar a los usuarios a instalar una versión actualizada de un paquete, usa el comando npm deprecate para marcar la versión antigua del paquete como obsoleta. Cuando un usuario intenta instalar el paquete obsoleto, Artifact Registry devuelve una advertencia de obsolescencia.

Antes de eliminar un paquete o una versión de un paquete, comprueba que has comunicado o resuelto las dependencias importantes que tenga.

Para eliminar un paquete, sigue estos pasos:

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

Para eliminar versiones de un paquete, sigue estos pasos:

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

Siguientes pasos

• Más información sobre cómo gestionar paquetes de Maven
• Consulta cómo gestionar imágenes de contenedor.
• Descargar archivos concretos de un paquete