Skip to main content

Trabalhando com o registro npm

Você pode configurar o npm para publicar pacotes no GitHub Packages e usar pacotes armazenados no GitHub Packages como dependências em um projeto npm.

O GitHub Packages está disponível com GitHub Free, GitHub Pro, GitHub Free for organizations, GitHub Team, GitHub Enterprise Cloud, GitHub Enterprise Server 3.0 ou superior e o GitHub AE.
O GitHub Packages não está disponível para repositórios privados de contas que utilizam planos antigos por-repositório. Além disso, as contas que usam os planos de legado por repositório não podem acessar o Container registry já que essas contas são cobradas por repositório. Para obter mais informações, confira "produtos de GitHub".

Autenticar-se no GitHub Packages

Você precisa de um token de acesso para publicar, instalar e excluir pacotes.

Você pode usar um PAT (token de acesso pessoal) para se autenticar no GitHub Packages ou na API do GitHub. Ao criar um token de acesso pessoal, você pode atribuir diferentes escopos de token, dependendo da sua necessidade. Para obter mais informações sobre escopos relacionados a pacotes para um PAT, confira "Sobre as permissões para pacotes do GitHub".

Para efetuar a autenticação em um registro do GitHub Packages dentro de um fluxo de trabalho de GitHub Actions, você pode utilizar:

  • GITHUB_TOKEN para publicar pacotes associados ao repositório do fluxo de trabalho.

  • um PAT para instalar pacotes associados a outros repositórios privados (que não podem ser acessados pelo GITHUB_TOKEN).

    Se o seu fluxo de trabalho estiver usando um PAT (token de acesso pessoal) para se autenticar em um registro, então é altamente recomendável atualizar seu fluxo de trabalho para usar o GITHUB_TOKEN.

Para obter diretrizes sobre como atualizar seus fluxos de trabalho que se autenticam em um registro com um token de acesso pessoal, confira "Como atualizar um fluxo de trabalho que acessa um registro usando PAT."

Para obter mais informações sobre o GITHUB_TOKEN, confira "Autenticação em um fluxo de trabalho".

Para obter mais informações sobre as melhores práticas ao usar um registro em ações, confira "Proteção de segurança para GitHub Actions".

Você também pode optar por dar permissões de acesso a pacotes independentemente para Codespaces e GitHub Actions. Para obter mais informações, confira "Como garantir que os codespaces acessem seu pacote e Como garantir o acesso do fluxo de trabalho ao seu pacote".

Efetuando a autenticação com um token de acesso pessoal

Você deve usar um token de acesso pessoal com os escopos apropriados para publicar e instalar pacotes no GitHub Packages. Para obter mais informações, confira "Sobre o GitHub Packages".

Você pode se autenticar no GitHub Packages com o npm editando o arquivo ~/.npmrc por usuário para incluir seu token de acesso pessoal ou fazendo logon no npm na linha de comando com seu nome de usuário e o token de acesso pessoal.

Para se autenticar adicionando seu token de acesso pessoal ao arquivo ~/.npmrc, edite o arquivo ~/.npmrc para que o projeto inclua a linha a seguir, substituindo TOKEN pelo token de acesso pessoal. Crie um arquivo ~/.npmrc se ele não existir.

//npm.pkg.github.com/:_authToken=TOKEN

Para se autenticar fazendo logon no npm, use o comando npm login substituindo USERNAME pelo seu nome de usuário do GitHub, TOKEN pelo token de acesso pessoal e PUBLIC-EMAIL-ADDRESS pelo seu endereço de email.

Se o GitHub Packages não é o registro de pacote padrão para usar o npm e você deseja usar o comando npm audit, recomendamos que você use o sinalizador --scope com o proprietário do pacote quando se autenticar no GitHub Packages.

$ npm login --scope=@OWNER --registry=https://npm.pkg.github.com

> Username: USERNAME
> Password: TOKEN
> Email: PUBLIC-EMAIL-ADDRESS

Publicando um pacote

Observação: os nomes e os escopos dos pacotes só devem usar letras minúsculas.

O registro GitHub Packages armazena pacotes npm em sua organização ou conta pessoal e permite que você associe um pacote a um repositório. Você pode escolher se deve herdar permissões de um repositório ou definir permissões granulares, independentemente de um repositório.

Por padrão, o GitHub Packages publica um pacote no repositório do GitHub que você especificar no campo de nome do arquivo package.json. Por exemplo, você publicará um pacote chamado @my-org/test no repositório my-org/test do GitHub. Se você estiver executando o npm v8.5.3 ou posterior, poderá adicionar um resumo para a página de listagem de pacotes incluindo um arquivo README.md em seu diretório de pacotes. Para obter mais informações, confira "Como trabalhar com package.json" e "Como criar módulos do Node.js" na documentação do npm.

Você pode publicar vários pacotes no mesmo repositório do GitHub incluindo um campo URL no arquivo package.json. Para obter mais informações, confira "Como publicar vários pacotes no mesmo repositório".

Quando um pacote é publicado, ele não é vinculado automaticamente a um repositório. No entanto, você pode optar por vincular seu pacote publicado a um repositório usando a interface do usuário ou a linha de comando. Para obter mais informações, confira "Como conectar um repositório a um pacote".

Configure o mapeamento do escopo para seu projeto usando um arquivo .npmrc local no projeto ou usando a opção publishConfig em package.json. GitHub Packages só é compatível com pacotes npm com escopo definido. Os pacotes com escopo têm nomes com o formato de @owner/name. Os pacotes com escopo sempre começam com um símbolo @. Talvez seja necessário atualizar o nome no package.json para usar o nome com escopo. Por exemplo, "name": "@codertocat/hello-world-npm".

Ao publicar um pacote pela primeira vez a visibilidade-padrão será privada. Quando um pacote é vinculado ao repositório, a visibilidade do pacote depende da visibilidade do repositório. Para alterar a visibilidade ou definir permissões de acesso, confira "Como configurar o controle de acesso e a visibilidade de um pacote".

Após publicar um pacote, você poderá visualizá-lo no GitHub. Para obter mais informações, confira "Como ver pacotes".

Como publicar um pacote usando um arquivo .npmrc local

Use um arquivo .npmrc para configurar o mapeamento do escopo para seu projeto. No arquivo .npmrc, use a URL e o proprietário da conta do GitHub Packages para que o GitHub Packages saiba o local para o qual as solicitações de pacote devem ser roteadas. O uso de um arquivo .npmrc impede que outros desenvolvedores publiquem o pacote acidentalmente em npmjs.org em vez de no GitHub Packages.

  1. Autenticar para GitHub Packages. Para obter mais informações, confira "Autenticação no GitHub Packages". 2. No mesmo diretório do arquivo package.json, crie ou edite um arquivo .npmrc para incluir uma linha especificando a URL do GitHub Packages e o proprietário da conta. Substitua OWNER pelo nome da conta de usuário ou de organização que é o proprietário do repositório que contém seu projeto.

    @OWNER:registry=https://npm.pkg.github.com
  2. Adicione o arquivo .npmrc ao repositório em que o GitHub Packages pode encontrar seu projeto. Para obter mais informações, confira "Como adicionar um arquivo a um repositório".

  3. Verifique o nome do pacote no package.json do projeto. O campo name precisa conter o escopo e o nome do pacote. Por exemplo, se o pacote for chamado "test" e você o estiver publicando na organização "My-org" do GitHub, o campo name no package.json deverá ser @my-org/test.

  4. Verifique o campo repository em package.json do seu projeto. O campo repository deve corresponder à URL do repositório do GitHub. Por exemplo, se a URL do repositório for github.com/my-org/test, o campo de repositório deverá ser https://github.com/my-org/test.git. 1. Publicar um pacote:

    $ npm publish

Como publicar um pacote usando publishConfig no arquivo package.json

Use o elemento publishConfig no arquivo package.json para especificar o registro em que deseja publicar o pacote. Para obter mais informações, confira "publishConfig" na documentação do npm.

  1. Edite o arquivo package.json do pacote e inclua uma entrada publishConfig.

    "publishConfig": {
      "registry":"https://npm.pkg.github.com"
    },
    1. Verifique o campo repository em package.json do seu projeto. O campo repository deve corresponder à URL do repositório do GitHub. Por exemplo, se a URL do repositório for github.com/my-org/test, o campo de repositório deverá ser https://github.com/my-org/test.git. 1. Publicar um pacote:
    $ npm publish

Publicar vários pacotes no mesmo repositório

Para publicar vários pacotes no mesmo repositório, inclua a URL do repositório do GitHub no campo repository do arquivo package.json de cada pacote.

Para garantir que a URL do repositório esteja correta, substitua REPOSITÓRIO pelo nome do repositório que contém o pacote que você deseja publicar, e o PROPRIETÁRIO pelo nome de usuário ou conta de organização no GitHub que é proprietário do repositório.

O GitHub Packages corresponderá ao repositório baseado na URL, em vez de ser baseado no nome do pacote.

"repository":"https://github.com/OWNER/REPOSITORY",

Instalando um pacote

Você pode instalar pacotes do GitHub Packages adicionando os pacotes como dependências no arquivo package.json do projeto. Para obter mais informações sobre como usar um package.json no seu projeto, confira "Como trabalhar com package.json" na documentação do npm.

Por padrão, você pode adicionar pacotes a partir de uma organização. Para obter mais informações, confira "Como instalar pacotes de outras organizações".

Você também precisa adicionar o arquivo .npmrc ao projeto para que todas as solicitações de instalação de pacotes passem pelo GitHub Packages. Ao rotear todas as solicitações de pacote por meio do GitHub Packages, você pode usar pacotes com escopo e sem escopo de npmjs.org. Para obter mais informações, confira "npm-scope" na documentação do npm.

  1. Autenticar para GitHub Packages. Para obter mais informações, confira "Autenticação no GitHub Packages". 2. No mesmo diretório do arquivo package.json, crie ou edite um arquivo .npmrc para incluir uma linha especificando a URL do GitHub Packages e o proprietário da conta. Substitua OWNER pelo nome da conta de usuário ou de organização que é o proprietário do repositório que contém seu projeto.

    @OWNER:registry=https://npm.pkg.github.com
  2. Adicione o arquivo .npmrc ao repositório em que o GitHub Packages pode encontrar seu projeto. Para obter mais informações, confira "Como adicionar um arquivo a um repositório".

  3. Configure package.json no projeto para usar o pacote que você está instalando. Para adicionar as dependências de pacote ao arquivo package.json para o GitHub Packages, especifique o nome do pacote com escopo completo, como @my-org/server. Para pacotes de npmjs.com, especifique o nome completo, como @babel/core ou @lodash. Por exemplo, o package.json a seguir usa o pacote @octo-org/octo-app como uma dependência.

    {
      "name": "@my-org/server",
      "version": "1.0.0",
      "description": "Server app that uses the @octo-org/octo-app package",
      "main": "index.js",
      "author": "",
      "license": "MIT",
      "dependencies": {
        "@octo-org/octo-app": "1.0.0"
      }
    }
    
  4. Instale o pacote.

    $ npm install

Instalar pacotes de outras organizações

Por padrão, você só pode usar pacotes do GitHub Packages de uma organização. Caso deseje encaminhar solicitações de pacotes para várias organizações e usuários, adicione mais linhas ao arquivo .npmrc substituindo OWNER pelo nome da conta de usuário ou da organização que é o proprietário do repositório que contém o projeto.

@OWNER:registry=https://npm.pkg.github.com
@OWNER:registry=https://npm.pkg.github.com