Gerenciar pacotes do 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 npm.

Funções exigidas

Para receber 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 como conceder papéis, consulte Gerenciar acesso.

Também é possível conseguir as permissões necessárias por meio de papéis personalizados ou de 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 registro global e os pacotes não estiverem com escopo, use o comando a seguir para que ele possa fazer o download do 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 do Artifact Registry 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 suas 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 de seus pacotes em um estágio de desenvolvimento específico, publique-os com uma tag, como beta ou dev.

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

Para adicionar um pacote:

  1. Verifique se o nome do pacote em package.json inclui 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 se autenticar com um token de acesso, consiga um novo token.

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

    Para marcar o pacote, inclua a sinalização --tag e substitua TAG pela tag que você quer usar. Se você não incluir a sinalização --tag, o npm vai 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 e virtual

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

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

  2. Execute o comando apropriado:

    npm view

    yarn info

Para visualizar pacotes e versões usando o console do Google Cloud ou gcloud:

Console

  1. Abra a página Repositórios no console do Google Cloud.

    Abrir a página Repositórios

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

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

  3. Clique em um pacote para visualizar as versões dele.

gcloud

Para listar pacotes em um repositório, execute o seguinte comando:

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

Por

  • REPOSITORY é o nome do repositório. Se você tiver configurado um repositório padrão, você pode omitir essa sinalização para usar o padrão.
  • LOCATION é um local regional ou multirregional. Use esta sinalização para ver repositórios em um local específico. Se você tiver configurado um local padrão, poderá omitir essa sinalização para usar o padrão.

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

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

Onde

  • PACKAGE é o ID do pacote ou o identificador totalmente qualificado do pacote.
  • REPOSITORY é o nome do repositório. Se você tiver configurado um repositório padrão, você pode omitir essa sinalização para usar o padrão.
  • LOCATION é um local regional ou multirregional. Use esta sinalização para ver repositórios em um local específico. Se você tiver configurado um local padrão, poderá omitir essa sinalização para usar o padrão.

A visualização de pacotes e versões do console do 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.

Como listar arquivos

Modos de repositório:padrão e remoto

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

Para todos os comandos a seguir, defina um número máximo de arquivos a serem retornados adicionando a sinalização --limit ao comando.

Para listar todos os arquivos do projeto, do repositório e do 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 os 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: seuID de projeto no Google Cloud. Caso o ID do projeto contenha 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.

Examples

Considere as seguintes informações do pacote:

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

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

gcloud artifacts files list \
    --location=us-central1 \
    --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-central1 \
    --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-central1 \
    --repository=my-repo \
    --package=my-app \
    --tag=1.0-dev

Como marcar pacotes

Modos de repositório:padrão

Você pode ver, adicionar, atualizar e excluir tags. As tags podem ajudar você a gerenciar versões semânticas dos pacotes e simplificar a instalação deles em um estágio específico de desenvolvimento.

Por exemplo, você pode marcar o build candidato a lançamento atual com rc. A equipe vai poder instalar a versão correta com base na tag em vez de usar um especificador de versão. Assim, o cancelamento da publicação de versões de pré-lançamento não usadas não corrompe as dependências no pacote candidato a lançamento.

Como visualizar tags

Para ver as tags de um pacote:

Console

  1. Abra a página Repositórios no console do Google Cloud.

    Abrir a página Repositórios

  2. Clique no pacote para visualizar as versões e tags associadas.

  3. Selecione a versão do pacote a ser marcada.

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

  5. Insira novas tags no campo e clique em SALVAR.

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 você tiver configurado um repositório padrão, você pode omitir essa sinalização para usar o padrão.
  • LOCATION é um local regional ou multirregional. Use esta sinalização para ver repositórios em um local específico. Se você tiver configurado um local padrão, poderá omitir essa sinalização para usar o padrão.

Por exemplo, para visualizar tags para o pacote my-package no repositório my-repo no local padrão, execute o comando:

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

Como criar tags

Você pode criar uma tag para uma versão específica de um pacote.

Para adicionar uma tag em uma imagem atual em um repositório:

Console

  1. Abra a página Repositórios no console do Google Cloud.

    Abrir a página Repositórios

  2. Clique no pacote para visualizar as versões do pacote.

  3. Selecione a versão do pacote a ser adicionar a tag.

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

  5. Insira novas tags no campo e clique em SALVAR.

gcloud

Execute este comando:

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

Onde

  • TAG é a tag que você quer aplicar ao pacote.
  • PACKAGE é o nome do pacote no repositório.
  • VERSION é a versão do pacote que você quer adicionar a tag.
  • LOCATION é um local regional ou multirregional. Use esta sinalização para ver repositórios em um local específico. Se você tiver configurado um local padrão, poderá omitir essa sinalização para usar o padrão.
  • REPOSITORY é o nome do repositório. Se você tiver configurado um repositório padrão, você pode omitir essa sinalização para usar o padrão.

Por exemplo, para criar a tag release-candidate para a versão 1.0.0 do pacote my-package no repositório my-repo no local padrão, execute o comando:

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

Como atualizar tags

É possível alterar uma tag associada a uma versão do pacote.

Para alterar uma tag existente, faça o seguinte:

Console

  1. Abra a página Repositórios no console do Google Cloud.

    Abrir a página Repositórios

  2. Clique no pacote para visualizar as versões do pacote.

  3. Selecione a versão do pacote com a tag a ser alterada.

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

  5. Edite a tag e clique em SALVAR.

gcloud

Execute este comando:

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

Onde

  • TAG é a tag que você quer aplicar ao pacote.
  • PACKAGE é o nome do pacote no repositório.
  • VERSION é a versão do pacote que você quer adicionar a tag.
  • LOCATION é um local regional ou multirregional. Use esta sinalização para ver repositórios em um local específico. Se você tiver configurado um local padrão, poderá omitir essa sinalização para usar o padrão.
  • REPOSITORY é o nome do repositório. Se você tiver configurado um repositório padrão, você pode omitir essa sinalização para usar o padrão.

Por exemplo, para alterar a tag da versão 1.0.0 do pacote my-package para production no repositório my-repo no local padrão, execute o comando:

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

Como desmarcar versões do pacote

É possível remover uma tag existente de uma versão de pacote.

Para remover uma tag:

Console

  1. Abra a página Repositórios no console do Google Cloud.

    Abrir a página Repositórios

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

  3. Selecione a versão da imagem para remover a tag.

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

  5. Exclua a tag e clique em SALVAR.

gcloud

Execute este comando:

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

Onde

  • TAG é a tag que você quer aplicar ao pacote.
  • PACKAGE é o nome do pacote no repositório.
  • LOCATION é um local regional ou multirregional. Use esta sinalização para ver repositórios em um local específico. Se você tiver configurado um local padrão, poderá omitir essa sinalização para usar o padrão.
  • REPOSITORY é o nome do repositório. Se você tiver configurado um repositório padrão, você pode omitir essa sinalização para usar o padrão.

Por exemplo, para remover a tag release-candidate do pacote my-package no repositório my-repo no local padrão, 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 e virtual

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

  1. Se você estiver usando o auxiliar de credenciais para se 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 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, faça o download de um pacote diretamente do repositório.

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

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

  • Os repositórios remotos upstream fazem o download e armazenam o pacote solicitado se não houver uma cópia em cache. Os repositórios virtuais só disponibilizam os pacotes solicitados, eles não os armazenam.
  • Se você solicitar uma versão disponível em mais de um repositório upstream, o Artifact Registry escolherá um repositório upstream para usar com base nas configurações de prioridade definidas 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: a prioridade foi definida como 100
  • secondary-repo1: a prioridade foi definida como 80.
  • secondary-repo2: a prioridade foi definida como 80.
  • test-repo: a prioridade foi definida como 20.

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

Tanto secondary-repo1 quanto 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 esses repositórios em seguida. Como ambos têm o mesmo valor de prioridade, o Artifact Registry pode disponibilizar um pacote de qualquer um dos repositórios se a versão estiver disponível em ambos.

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

Como excluir pacotes

Modos de repositório:padrão e 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.
  • No caso de repositórios remotos, somente a cópia em cache do pacote é excluída. A origem upstream não é afetada. Se você excluir um pacote armazenado em cache, o Artifact Registry fará o download e o armazenará em cache novamente na próxima vez que o repositório receber uma solicitação para essa 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 descontinuado, o Artifact Registry retorna um aviso de suspensão de uso.

Antes de excluir uma versão de pacote ou um pacote, verifique se você comunicou ou resolveu qualquer dependência importante nele.

Para excluir um pacote:

Console

  1. Abra a página Repositórios no console do Google Cloud.

    Abrir a página Repositórios

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

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

  3. Selecione o pacote que você quer excluir.

  4. Clique em EXCLUIR.

  5. Na caixa de diálogo de confirmação, clique em Excluir.

gcloud

Execute este comando:

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

Por

  • PACKAGE é o nome do pacote no repositório.
  • REPOSITORY é o nome do repositório. Se você tiver configurado um repositório padrão, você pode omitir essa sinalização para usar o padrão.
  • LOCATION é um local regional ou multirregional. Use esta sinalização para ver repositórios em um local específico. Se você tiver configurado um local padrão, poderá omitir essa sinalização para usar o padrão.
  • --async Retorna imediatamente, sem aguardar a conclusão da operação em andamento.

Para excluir versões de um pacote:

Console

  1. Abra a página Repositórios no console do Google Cloud.

    Abrir a página Repositórios

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

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

  3. Clique em um pacote para visualizar as versões dele.

  4. Selecione as versões que você quer excluir.

  5. Clique em EXCLUIR.

  6. Na caixa de diálogo de confirmação, clique em Excluir.

gcloud

Execute este comando:

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

Por

  • PACKAGE é o nome do pacote no repositório.
  • REPOSITORY é o nome do repositório. Se você tiver configurado um repositório padrão, você pode omitir essa sinalização para usar o padrão.
  • LOCATION é um local regional ou multirregional. Use esta sinalização para ver repositórios em um local específico. Se você tiver configurado um local padrão, poderá omitir essa sinalização para usar o padrão.
  • --async retorna imediatamente, sem aguardar a conclusão da operação em andamento.

A seguir