Gerenciar pacotes Node.js

Nesta página, descrevemos as seguintes tarefas:

  • Como visualizar e excluir pacotes e versões de pacote
  • Como visualizar, criar, atualizar e excluir tags

Antes de começar

  1. Se não existir um repositório de destino, crie um novo repositório.
  2. Verifique se você tem as permissões necessárias para o repositório.
  3. Configure a autenticação do npm.
  4. (Opcional) Configure padrões para comandos gcloud.
  5. Se você estiver usando o auxiliar de credenciais do npm para autenticação, consiga um token de acesso antes de se conectar a um repositório com o npm.

Funções exigidas

Para ter as permissões necessárias para gerenciar pacotes, peça ao administrador para conceder a você os seguintes papéis do IAM no repositório:

Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Também é possível conseguir as permissões necessárias usando papéis personalizados ou outros papéis predefinidos.

Como conseguir um token de acesso

Os tokens de acesso são válidos por 60 minutos. Gere um token de acesso pouco antes de executar comandos que interagem com repositórios.

Para receber um token, use uma destas opções:

  • Use o comando npx para atualizar o token de acesso.

    1. Verifique se as credenciais para se conectar ao registro npm público estão no arquivo de configuração do npm do usuário, ~/.npmrc.

    2. Execute o seguinte comando no diretório do projeto Node.js.

      npx google-artifactregistry-auth

      Se o repositório do Artifact Registry estiver definido como seu registro global e os pacotes não estiverem no escopo, use o comando a seguir para que ele baixe o auxiliar de credenciais do registro npm público em vez do repositório do Artifact Registry.

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

  • Adicione um script ao arquivo package.json no seu projeto.

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

    Execute o script no diretório do projeto Node.js.

    npm run artifactregistry-login

O Artifact Registry lê as configurações do repositório no arquivo .npmrc do projeto e as usa para adicionar credenciais de token ao arquivo .npmrc do usuário. Armazenar o token no arquivo .npmrc do usuário isola as credenciais do código-fonte e do sistema de controle de origem.

Como adicionar pacotes

Modos de repositório:padrão

Só é possível publicar uma versão específica de um pacote uma vez. Essa é uma restrição npm para garantir que o conteúdo de uma versão de pacote publicada seja sempre o mesmo. Como resultado, você não poderá:

  • Substituir uma versão do pacote publicando-a novamente no repositório
  • Remover um pacote ou sua versão do repositório e, em seguida, publicar um pacote com o mesmo nome e número da versão

Se você não especificar uma tag ao publicar um pacote, o npm vai adicionar a tag latest. Para simplificar a instalação dos pacotes em uma etapa específica de desenvolvimento, considere publicar os pacotes com uma tag, como beta ou dev.

O Artifact Registry exige nomes de pacotes alfanuméricos em letras minúsculas para pacotes npm.

Para adicionar um pacote:

  1. Certifique-se de que o nome do pacote em package.json inclua o escopo configurado para seu repositório. O exemplo a seguir mostra um pacote com o escopo dev-repo.

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

  2. Se você estiver usando o auxiliar de credenciais para autenticar com um token de acesso, consiga um novo token.

  3. Adicione pacotes ao repositório. Use um comando npm ou yarn.

    Para adicionar uma tag ao pacote, inclua a flag --tag e substitua TAG pela tag que você quer usar. Se você não incluir a flag --tag, o npm definirá automaticamente a tag como latest.

    npm publish --tag=TAG

    yarn publish --tag TAG

Como visualizar pacotes e versões

Modos de repositório:padrão, remoto, virtual

Para ver informações do pacote com npm ou yarn:

  1. Se você estiver usando o auxiliar de credenciais para autenticar com um token de acesso, consiga um novo token.

  2. Execute o comando adequado:

    npm view

    yarn info

Para ver pacotes e versões de pacotes através da Google Cloud consola ou da gcloud:

Consola

  1. Abra a página Repositórios na Google Cloud consola.

    Abra a página Repositórios

  2. Na lista de repositórios, clique no repositório adequado.

    A página Pacotes apresenta os pacotes no repositório.

  3. Clique num pacote para ver as versões do pacote.

gcloud

Para listar os pacotes num repositório, execute o seguinte comando:

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

Substitua o seguinte:

  • REPOSITORY é o nome do repositório. Se tiver configurado um repositório predefinido, pode omitir esta flag para usar o predefinido.
  • LOCATION é a localização regional ou multirregional do repositório. Se configurou uma localização predefinida, pode omitir esta flag para usar a predefinição.

Para ver as versões de um pacote, execute o seguinte comando:

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

Substitua o seguinte:

  • PACKAGE é o ID do pacote ou o identificador totalmente qualificado do pacote.
  • REPOSITORY é o nome do repositório. Se tiver configurado um repositório predefinido, pode omitir esta flag para usar o predefinido.
  • LOCATION é a localização regional ou multirregional do repositório. Use esta flag para ver repositórios numa localização específica. Se configurou uma localização predefinida, pode omitir esta flag para usar a predefinição.

A visualização de pacotes e versões do console Google Cloud ou da CLI gcloud está disponível apenas para repositórios padrão e remotos.

Para repositórios remotos, a lista retornada precisa incluir todas as dependências diretas e transitivas armazenadas em cache no repositório.

Listar arquivos

Modos de repositório:padrão, remoto

É possível listar arquivos em um repositório, em todas as versões de um pacote especificado ou em uma versão específica de um pacote.

Para todos os comandos a seguir, é possível definir um número máximo de arquivos a serem retornados adicionando a flag --limit ao comando.

Para listar todos os arquivos no projeto, repositório e local padrão quando os valores padrão estiverem configurados:

gcloud artifacts files list

Para listar arquivos em um projeto, repositório e local especificados, execute o comando:

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

Para listar arquivos de todas as versões de um pacote específico:

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

Para listar arquivos de uma versão específica do pacote:

gcloud artifacts files list \
    --project=PROJECT \
    --repository=REPOSITORY \
    --location=LOCATION \
    --package=PACKAGE \
    --version=VERSION
Para listar arquivos de uma tag específica:

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

Substitua os seguintes valores:

  • LOCATION: o local regional ou multirregional do repositório.
  • PROJECT: o ID do projeto do Google Cloud . Se o ID do projeto contiver dois pontos (:), consulte Projetos com escopo de domínio.
  • REPOSITORY: o nome do repositório em que a imagem está armazenada.
  • PACKAGE: o nome do pacote.
  • VERSION: a versão do pacote.
  • TAG: a tag associada ao pacote.

Exemplos

Considere as seguintes informações do pacote:

  • Projeto: my-project
  • Repositório: my-repo
  • Local do repositório: us-west1
  • Pacote: my-app

O comando a seguir lista todos os arquivos no repositório my-repo no local us-west1 no projeto padrão:

gcloud artifacts files list \
    --location=us-west1 \
    --repository=my-repo
O comando a seguir lista os arquivos na versão 1.0 do pacote.

gcloud artifacts files list \
    --project=my-project \
    --location=us-west1 \
    --repository=my-repo \
    --package=my-app \
    --version=1.0
O comando a seguir lista os arquivos na versão do pacote com a tag 1.0-dev

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

Como marcar pacotes

Modos de repositório:padrão

Pode ver, adicionar, atualizar e eliminar etiquetas. As etiquetas podem ajudar a gerir versões semânticas dos seus pacotes e simplificar a instalação de pacotes numa fase específica do desenvolvimento.

Por exemplo, pode etiquetar a versão candidata atual com rc. A sua equipa pode instalar a versão correta com base na etiqueta em vez de um especificador de versão, e a anulação da publicação de versões de pré-lançamento não usadas não afeta as suas dependências no pacote de versão candidata.

Visualizar etiquetas

Para ver etiquetas de um pacote:

Consola

  1. Abra a página Repositórios na Google Cloud consola.

    Abra a página Repositórios

  2. Clique no pacote para ver as versões e as etiquetas associadas.

  3. Selecione a versão do pacote a etiquetar.

  4. Na linha da versão selecionada, clique em Mais ações (Mais ações) e, de seguida, clique em Editar etiquetas.

  5. Escreva novas etiquetas no campo e, de seguida, clique em GUARDAR.

gcloud

Execute o comando:

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

Onde

  • PACKAGE é o nome do pacote no repositório.
  • REPOSITORY é o nome do repositório. Se configurou um repositório predefinido, pode omitir esta flag para usar o predefinido.
  • LOCATION é uma localização regional ou multirregional. Use esta flag para ver repositórios numa localização específica. Se tiver configurado uma localização predefinida, pode omitir esta flag para usar a predefinição.

Por exemplo, para ver as etiquetas do pacote my-package no repositório my-repo na localização predefinida, execute o comando:

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

Criar etiquetas

Pode criar uma etiqueta para uma versão específica de um pacote.

Para etiquetar uma imagem existente num repositório:

Consola

  1. Abra a página Repositórios na Google Cloud consola.

    Abra a página Repositórios

  2. Clique no pacote para ver as versões do mesmo.

  3. Selecione a versão do pacote a etiquetar.

  4. Na linha da versão selecionada, clique em Mais ações (Mais ações) e, de seguida, clique em Editar etiquetas.

  5. Escreva novas etiquetas no campo e, de seguida, clique em GUARDAR.

gcloud

Execute o seguinte comando:

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

Onde

  • TAG é a etiqueta que quer aplicar ao pacote.
  • PACKAGE é o nome do pacote no repositório.
  • VERSION é a versão do pacote que quer etiquetar.
  • LOCATION é uma localização regional ou multirregional. Use esta flag para ver repositórios numa localização específica. Se tiver configurado uma localização predefinida, pode omitir esta flag para usar a predefinição.
  • REPOSITORY é o nome do repositório. Se configurou um repositório predefinido, pode omitir esta flag para usar o predefinido.

Por exemplo, para criar a etiqueta release-candidate para a versão 1.0.0 do pacote my-package no repositório my-repo na localização predefinida, execute o comando:

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

A atualizar etiquetas

Pode alterar uma etiqueta associada a uma versão de pacote.

Para alterar uma etiqueta existente:

Consola

  1. Abra a página Repositórios na Google Cloud consola.

    Abra a página Repositórios

  2. Clique no pacote para ver as versões do mesmo.

  3. Selecione a versão do pacote com a etiqueta a alterar.

  4. Na linha da versão selecionada, clique em Mais ações (Mais ações) e, de seguida, clique em Editar etiquetas.

  5. Edite a etiqueta e, de seguida, clique em GUARDAR.

gcloud

Execute o seguinte comando:

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

Onde

  • TAG é a etiqueta que quer aplicar ao pacote.
  • PACKAGE é o nome do pacote no repositório.
  • VERSION é a versão do pacote que quer etiquetar.
  • LOCATION é uma localização regional ou multirregional. Use esta flag para ver repositórios numa localização específica. Se tiver configurado uma localização predefinida, pode omitir esta flag para usar a predefinição.
  • REPOSITORY é o nome do repositório. Se configurou um repositório predefinido, pode omitir esta flag para usar o predefinido.

Por exemplo, para alterar a etiqueta da versão 1.0.0 do pacote my-package para production no repositório my-repo na localização predefinida, execute o comando:

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

Remover etiquetas de versões de pacotes

Pode remover uma etiqueta existente de uma versão do pacote.

Para remover uma etiqueta:

Consola

  1. Abra a página Repositórios na Google Cloud consola.

    Abra a página Repositórios

  2. Clique na imagem para ver as versões da imagem.

  3. Selecione a versão da imagem para desmarcar.

  4. Na linha da versão selecionada, clique em Mais ações (Mais ações) e, de seguida, clique em Editar etiquetas.

  5. Elimine a etiqueta e, de seguida, clique em GUARDAR.

gcloud

Execute o seguinte comando:

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

Onde

  • TAG é a etiqueta que quer aplicar ao pacote.
  • PACKAGE é o nome do pacote no repositório.
  • LOCATION é uma localização regional ou multirregional. Use esta flag para ver repositórios numa localização específica. Se tiver configurado uma localização predefinida, pode omitir esta flag para usar a predefinição.
  • REPOSITORY é o nome do repositório. Se configurou um repositório predefinido, pode omitir esta flag para usar o predefinido.

Por exemplo, para remover a etiqueta release-candidate do pacote my-package no repositório my-repo na localização predefinida, execute o comando:

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

Como instalar pacotes

Modos de repositório:padrão, remoto, virtual

Para instalar um pacote do repositório de pacotes do Node.js:

  1. Se você estiver usando o auxiliar de credenciais para autenticar com um token de acesso, consiga um novo token.

  2. Use o comando npm install ou yarn add.

    npm

    Para instalar a versão com a tag latest:

    npm install @SCOPE/PACKAGE

    Para instalar a versão com uma tag diferente:

    npm install @SCOPE/PACKAGE@TAG

    Para instalar uma versão específica:

    npm install @SCOPE/PACKAGE@VERSION

    yarn

    Para instalar a versão com a tag latest:

    yarn add @SCOPE/PACKAGE

    Para instalar a versão com uma tag diferente:

    yarn add @SCOPE/PACKAGE@TAG

    Para instalar uma versão específica:

    yarn add @SCOPE/PACKAGE@VERSION

    Substitua os seguintes valores:

    • SCOPE é o escopo associado ao repositório. Se o repositório de pacotes do Node.js não estiver configurado com um escopo, omita @SCOPE/ do comando.
    • PACKAGE é o nome do pacote no repositório.
    • TAG é a tag da versão que você quer instalar.
    • VERSION é o número da versão que você quer instalar.

Ao especificar um pacote como uma dependência em package.json, inclua o escopo do repositório. O exemplo a seguir mostra o escopo @dev-repo de um pacote chamado my-package.

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

Para repositórios padrão, você baixa um pacote diretamente do repositório.

Para um repositório remoto, faça o download de uma cópia em cache do pacote e das dependências dele. Se não houver uma cópia em cache, o repositório remoto vai baixar o pacote da origem upstream e armazená-lo em cache antes de disponibilizá-lo para você. Para verificar se o repositório remoto recuperou os pacotes da fonte upstream, confira a lista de pacotes no repositório.

Para um repositório virtual, o Artifact Registry pesquisa nos repositórios upstream o pacote solicitado.

  • Os repositórios remotos upstream vão baixar e armazenar em cache o pacote solicitado se não houver uma cópia em cache. Os repositórios virtuais apenas veiculam os pacotes solicitados, não os armazenam.
  • Se você solicitar uma versão disponível em mais de um repositório upstream, o Artifact Registry vai escolher um repositório upstream para usar com base nas configurações de prioridade configuradas para o repositório virtual.

Por exemplo, considere um repositório virtual com as seguintes configurações de prioridade para repositórios upstream:

  • main-repo: prioridade definida como 100
  • secondary-repo1: prioridade definida como 80.
  • secondary-repo2: prioridade definida como 80.
  • test-repo: prioridade definida como 20.

main-repo tem o valor de prioridade mais alto, então o repositório virtual sempre o pesquisa primeiro.

secondary-repo1 e secondary-repo2 têm prioridade definida como 80. Se um pacote solicitado não estiver disponível em main-repo, o Artifact Registry vai pesquisar nesses repositórios em seguida. Como ambos têm o mesmo valor de prioridade, o Artifact Registry pode veicular um pacote de qualquer repositório se a versão estiver disponível nos dois.

test-repo tem o menor valor de prioridade e vai veicular um artefato armazenado se nenhum dos outros repositórios upstream tiver esse artefato.

Como excluir pacotes

Modos de repositório:padrão, remoto

É possível excluir um pacote e todas as versões dele ou uma versão específica.

  • Depois de excluir um pacote, não é possível desfazer a ação.
  • Para repositórios remotos, apenas a cópia em cache do pacote é excluída. A fonte upstream não é afetada. Se você excluir um pacote em cache, o Artifact Registry vai fazer o download e armazenar em cache novamente na próxima vez que o repositório receber uma solicitação para a mesma versão do pacote.

Depois que uma versão do pacote é publicada, não é possível republicar um pacote com o mesmo nome e combinação de versões, mesmo após excluir a versão. Essa é uma restrição npm para garantir que o conteúdo de uma versão de pacote publicada seja sempre o mesmo.

Se você quiser incentivar os usuários a instalar uma versão atualizada do pacote, use o comando npm deprecate para marcar a versão antiga do pacote como obsoleta. Quando um usuário tenta instalar o pacote obsoleto, o Artifact Registry retorna um aviso de suspensão de uso.

Before you delete a package or package version, verify that any you have communicated or addressed any important dependencies on it.

To delete a package:

Console

  1. Open the Repositories page in the Google Cloud console.

    Abra a página Repositórios

  2. In the repository list, click the appropriate repository.

    The Packages page lists the packages in the repository.

  3. Select the package that you want to delete.

  4. Click DELETE.

  5. In the confirmation dialog box, click DELETE.

gcloud

Run the following command:

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

Replace the following:

  • PACKAGE is the name of the package in the repository.
  • REPOSITORY is the name of the repository. If you configured a default repository, then you can omit this flag to use the default.
  • LOCATION is the regional or multi-regional location of the repository. Use this flag to view repositories in a specific location. If you configured a default location, then you can omit this flag to use the default.

The --async flag causes the command to return immediately, without waiting for the operation in progress to complete.

To delete versions of a package:

Console

  1. Open the Repositories page in the Google Cloud console.

    Abra a página Repositórios

  2. In the repository list, click the appropriate repository.

    The Packages page lists the packages in the repository.

  3. Click a package to view versions of that package.

  4. Select versions that you want to delete.

  5. Click DELETE.

  6. In the confirmation dialog box, click DELETE.

gcloud

Run the following command:

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

Replace the following:

  • VERSION is the name of the version to delete.
  • PACKAGE is the name of the package in the repository.
  • REPOSITORY is the name of the repository. If you configured a default repository, then you can omit this flag to use the default.
  • LOCATION is the regional or multi-regional location of the repository. Use this flag to view repositories in a specific location. If you configured a default location, then you can omit this flag to use the default.

The --async flag causes the command to return immediately, without waiting for the operation in progress to complete.

A seguir