Administra paquetes de Node.js

En esta página, se describen las siguientes tareas:

  • Visualizar y borrar paquetes y versiones de paquetes
  • Visualizar, crear, actualizar y borrar etiquetas

Antes de comenzar

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

Obtén 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 los repositorios.

Para obtener un token, usa 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 la Administración de socios de red estén en el archivo de configuración de la Administración de socios de red de tu usuario, ~/.npmrc.

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

      npx google-artifactregistry-auth
      
  • Agrega una secuencia de comandos al archivo package.json en 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 la configuración del repositorio de Artifact Registry en el archivo .npmrc del proyecto y la usa para agregar credenciales de token al archivo .npmrc del usuario. El almacenamiento del token en tu archivo .npmrc del usuario aísla las credenciales de tu código fuente y del sistema de control de origen.

Agrega paquetes

Solo puedes publicar una versión específica de un paquete una vez. Esta es una restricción de npm para garantizar que el contenido de la versión de un paquete publicado siempre sea el mismo. Como resultado, no puedes hacer lo siguiente:

  • Reemplazar una versión del paquete si la vuelves a publicar en el repositorio
  • Quitar un paquete o su versión del repositorio y, luego, publicar un paquete con el mismo nombre y el mismo número de versión.

Si no especificas una etiqueta cuando publicas un paquete, npm agrega la etiqueta latest. Para simplificar la instalación de tus paquetes en una etapa de desarrollo específica, considera publicar tus paquetes con una etiqueta, como beta o dev.

Para agregar un paquete, haz lo siguiente:

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

    "name": "@dev-repo/my-package"
    
  2. Si usas el auxiliar de credenciales para autenticar con un token de acceso, obtén un token nuevo.

  3. Agrega paquetes al repositorio. Puedes usar un comando de npm o yarn.

    Para etiquetar el paquete, incluye la marca --tag y reemplaza TAG por la etiqueta que deseas usar. Si no incluyes la marca --tag, npm establece la etiqueta en latest de forma automática.

    npm publish --tag=TAG
    
    yarn publish --tag TAG
    

Visualiza paquetes y versiones

Para obtener información sobre el paquete con npm o yarn, haz lo siguiente:

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

  2. Ejecuta el comando adecuado:

    npm view
    
    yarn info
    

Para ver paquetes y versiones de paquetes con Google Cloud Console o gcloud, haz lo siguiente:

Console

  1. Abre la página Repositorios en Google Cloud Console.

    Abrir la página Repositorios

  2. En la lista de repositorios, haz clic en el repositorio correspondiente.

    En la página Paquetes, se enumeran los paquetes del repositorio.

  3. Haz clic en un paquete para ver las versiones de este.

gcloud

Para enumerar los paquetes en un repositorio, ejecuta el siguiente comando:

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

Donde

  • REPOSITORY es el nombre del repositorio. Si configuraste un repositorio predeterminado, puedes omitir esta marca para usarlo.
  • LOCATION es una ubicación regional o multirregional. Usa esta marca para ver los repositorios en una ubicación específica. Si configuraste una ubicación predeterminada, puedes omitir esta marca para usarla.

Para ver las versiones de un paquete, ejecuta el siguiente comando:

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

Donde

  • PACKAGE es el ID del paquete o identificador completamente calificado del paquete.
  • REPOSITORY es el nombre del repositorio. Si configuraste un repositorio predeterminado, puedes omitir esta marca para usarlo.
  • LOCATION es una ubicación regional o multirregional. Usa esta marca para ver los repositorios en una ubicación específica. Si configuraste una ubicación predeterminada, puedes omitir esta marca para usarla.

Etiqueta paquetes

Puedes ver, agregar, actualizar y borrar etiquetas. Las etiquetas pueden ayudarte a administrar versiones semánticas de tus paquetes y optimizar la instalación de paquetes en una etapa específica del desarrollo.

Por ejemplo, puedes etiquetar la compilación candidata para el lanzamiento actual con rc. De esta forma, el equipo puede instalar la versión correcta en función de la etiqueta en lugar de un especificador de versiones, y anular la publicación de las versiones previas al lanzamiento que no se usen no dañará tus dependencias en el paquete candidato.

Visualiza etiquetas

Para ver las etiquetas de un paquete, haz lo siguiente:

Console

  1. Abre la página Repositorios en Cloud Console.

    Abrir la página Repositorios

  2. Haz clic en el paquete para ver las versiones y las etiquetas asociadas.

  3. Selecciona la versión del paquete que deseas etiquetar.

  4. En la fila de la versión seleccionada, haz clic en Más acciones (Más acciones) y, luego, en Editar etiquetas.

  5. Escribe las etiquetas nuevas en el campo y haz clic en GUARDAR.

gcloud

Ejecuta el comando:

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

Donde

  • PACKAGE es el nombre del paquete en el repositorio.
  • REPOSITORY es el nombre del repositorio. Si configuraste un repositorio predeterminado, puedes omitir esta marca para usarlo.
  • LOCATION es una ubicación regional o multirregional. Usa esta marca para ver los repositorios en una ubicación específica. Si configuraste una ubicación predeterminada, puedes omitir esta marca para usarla.

Por ejemplo, para ver las etiquetas del paquete my-package del repositorio my-repo en la ubicación predeterminada, ejecuta el siguiente comando:

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

Crea etiquetas

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

Para etiquetar una imagen existente en un repositorio, haz lo siguiente:

Console

  1. Abre la página Repositorios en Cloud Console.

    Abrir la página Repositorios

  2. Haz clic en el paquete para ver las versiones de este.

  3. Selecciona la versión del paquete que deseas etiquetar.

  4. En la fila de la versión seleccionada, haz clic en Más acciones (Más acciones) y, luego, en Editar etiquetas.

  5. Escribe las etiquetas nuevas en el campo y haz clic en GUARDAR.

gcloud

Ejecuta el siguiente comando:

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

Donde

  • TAG es la etiqueta que deseas aplicar al paquete.
  • PACKAGE es el nombre del paquete en el repositorio.
  • VERSION es la versión del paquete que deseas etiquetar.
  • LOCATION es una ubicación regional o multirregional. Usa esta marca para ver los repositorios en una ubicación específica. Si configuraste una ubicación predeterminada, puedes omitir esta marca para usarla.
  • REPOSITORY es el nombre del repositorio. Si configuraste un repositorio predeterminado, puedes omitir esta marca para usarlo.

Por ejemplo, a fin de crear la etiqueta release-candidate para la versión 1.0.0 del paquete my-package en el repositorio my-repo en la ubicación predeterminada, ejecuta el siguiente comando:

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

Actualiza etiquetas

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

Para cambiar una etiqueta existente, haz lo siguiente:

Console

  1. Abre la página Repositorios en Cloud Console.

    Abrir la página Repositorios

  2. Haz clic en el paquete para ver las versiones de este.

  3. Selecciona la versión del paquete con la etiqueta que deseas cambiar.

  4. En la fila de la versión seleccionada, haz clic en Más acciones (Más acciones) y, luego, en Editar etiquetas.

  5. Edita la etiqueta y haz clic en GUARDAR.

gcloud

Ejecuta el siguiente comando:

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

Donde

  • TAG es la etiqueta que deseas aplicar al paquete.
  • PACKAGE es el nombre del paquete en el repositorio.
  • VERSION es la versión del paquete que deseas etiquetar.
  • LOCATION es una ubicación regional o multirregional. Usa esta marca para ver los repositorios en una ubicación específica. Si configuraste una ubicación predeterminada, puedes omitir esta marca para usarla.
  • REPOSITORY es el nombre del repositorio. Si configuraste un repositorio predeterminado, puedes omitir esta marca para usarlo.

Por ejemplo, para cambiar la etiqueta de la versión 1.0.0 del paquete my-package a production en el repositorio my-repo en la ubicación predeterminada, ejecuta el siguiente comando:

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

Quita las etiquetas de versiones de paquetes

Puedes quitar una etiqueta existente de una versión de un paquete.

Para quitar una etiqueta, haz lo siguiente:

Console

  1. Abre la página Repositorios en Cloud Console.

    Abrir la página Repositorios

  2. Haz clic en la imagen para ver las versiones de esta.

  3. Selecciona la versión de la imagen de la que deseas quitar una etiqueta.

  4. En la fila de la versión seleccionada, haz clic en Más acciones (Más acciones) y, luego, en Editar etiquetas.

  5. Borra la etiqueta y haz clic en GUARDAR.

gcloud

Ejecuta el siguiente comando:

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

Donde

  • TAG es la etiqueta que deseas aplicar al paquete.
  • PACKAGE es el nombre del paquete en el repositorio.
  • LOCATION es una ubicación regional o multirregional. Usa esta marca para ver los repositorios en una ubicación específica. Si configuraste una ubicación predeterminada, puedes omitir esta marca para usarla.
  • REPOSITORY es el nombre del repositorio. Si configuraste un repositorio predeterminado, puedes omitir esta marca para usarlo.

Por ejemplo, para quitar la etiqueta release-candidate del paquete my-package en el repositorio my-repo en la ubicación predeterminada, ejecuta el siguiente comando:

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

Instala paquetes

Para instalar un paquete desde el repositorio de paquetes de Node.js:

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

  2. Usa el comando npm install o yarn add.

    npm

    Para instalar una 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
    

    yarn

    Para instalar una 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
    

    Reemplaza los siguientes valores:

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

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

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

Borra paquetes

Después de publicar una versión de un paquete, no puedes volver a publicar un paquete con la misma combinación de nombre y versión, incluso después de borrar la versión. Esta es una restricción de npm para garantizar que el contenido de la versión de un paquete publicado siempre sea el mismo.

Si deseas alentar a los usuarios a instalar una versión actualizada del paquete, usa el comando npm deprecate para marcar la versión anterior del paquete como obsoleta. Cuando un usuario intenta instalar el paquete obsoleto, Artifact Registry muestra una advertencia de baja.

Antes de borrar un paquete o una versión de un paquete, verifica que se haya comunicado o abordado cualquier dependencia importante en este.

Para borrar un paquete, haz lo siguiente:

Console

  1. Abre la página Repositorios en Google Cloud Console.

    Abrir la página Repositorios

  2. En la lista de repositorios, haz clic en el repositorio correspondiente.

    En la página Paquetes, se enumeran los paquetes del repositorio.

  3. Selecciona el paquete que deseas borrar.

  4. Haz clic en BORRAR.

  5. En el cuadro de diálogo de confirmación, haz clic en BORRAR.

gcloud

Ejecuta el siguiente comando:

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

Donde

  • PACKAGE es el nombre del paquete en el repositorio.
  • REPOSITORY es el nombre del repositorio. Si configuraste un repositorio predeterminado, puedes omitir esta marca para usarlo.
  • LOCATION es una ubicación regional o multirregional. Usa esta marca para ver los repositorios en una ubicación específica. Si configuraste una ubicación predeterminada, puedes omitir esta marca para usarla.
  • --async se muestra de inmediato, sin necesidad de esperar a que se complete la operación en curso.

Para borrar versiones de un paquete:

Console

  1. Abre la página Repositorios en Google Cloud Console.

    Abrir la página Repositorios

  2. En la lista de repositorios, haz clic en el repositorio correspondiente.

    En la página Paquetes, se enumeran los paquetes del repositorio.

  3. Haz clic en un paquete para ver sus versiones.

  4. Selecciona las versiones que deseas borrar.

  5. Haz clic en BORRAR.

  6. En el cuadro de diálogo de confirmación, haz clic en BORRAR.

gcloud

Ejecuta el siguiente comando:

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

Donde

  • PACKAGE es el nombre del paquete en el repositorio.
  • REPOSITORY es el nombre del repositorio. Si configuraste un repositorio predeterminado, puedes omitir esta marca para usarlo.
  • LOCATION es una ubicación regional o multirregional. Usa esta marca para ver los repositorios en una ubicación específica. Si configuraste una ubicación predeterminada, puedes omitir esta marca para usarla.
  • --async se muestra de inmediato, sin necesidad de esperar a que se complete la operación en curso.

¿Qué sigue?