Recentemente, no meu trabalho, me deparei com a seguinte necessidade: publicar um pacote de maneira privada. Depois de avaliar algumas possibilidades, percebi que a melhor forma de fazer isso seria utilizando o GitHub Packages.

O que é o GitHub Packages?

O GitHub Packages permite que você armazene pacotes de diferentes tipos (como npm, Maven, Docker, etc.) diretamente no GitHub. Você pode torná-los públicos ou privados, dependendo da necessidade do seu projeto. Você pode conferir mais informações aqui.

Passo 1: Configurando o projeto e necessidades

Primeiro, é necessário que você tenha um repositório no GitHub onde o seu pacote será armazenado. Para garantir que o pacote seja privado, certifique-se de que o repositório é privado.

Passo 2: Criando o seu pacote

Criando o package.json: Substitua <seu-usuario-ou-organizacao> pelo usuário ou organização desejada.

npm init --scope=@<seu-usuario-ou-organizacao>

Isso vai gerar um package.json com o campo name já formatado com o escopo. Utilizando o meu perfil do GitHub como exemplo:

{
  "name": "@carloshendvpm/meu-pacote",
  "version": "1.0.0",
  "description": "Meu pacote privado no GitHub Packages",
  ...
}

Passo 3: Configurando o registro para GitHub Packages

Agora, é preciso garantir que o npm saiba que você deseja publicar esse pacote no GitHub Packages, e não no registro público do npm. Para isso, adicione o campo publishConfig ao seu package.json:

"publishConfig": {
  "registry": "https://npm.pkg.github.com/"
}

Isso informa ao npm que ele deve usar o GitHub Packages como destino de publicação. O seu package.json deve ficar assim:

{
  "name": "@carloshendvpm/meu-pacote",
  "version": "1.0.0",
  "type": "module",
  "repository": {
    "url": "https://github.com/carloshendvpm/meu-pacote.git"
  },
  "dependencies": {
    ...
  },
  "devDependencies": {
    ...
  },
  "publishConfig": {
    "registry": "https://npm.pkg.github.com/"
  }
}

Passo 4: Utilizando GitHub Actions para publicar o pacote

Crie um diretório chamado .github/workflows dentro do seu projeto. E, dentro do diretório workflows, crie um arquivo publish.yml com o seguinte conteúdo:

name: Publish package to GitHub Packages
on:
  release:
    types: [published]
  workflow_dispatch:
jobs:
  build:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      packages: write
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20.x'
          registry-url: 'https://npm.pkg.github.com'
          scope: '@carloshendvpm'
      - name: Install dependencies
        run: npm install
      - name: Publish package
        run: npm publish --access restricted
        env:
          NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Essa action será executada na adição de uma nova release. Isso pode ser alterado de acordo com sua preferência. Além disso, utilizei o workflow_dispatch, que permite executar essa action diretamente da interface do GitHub, manualmente. É importante salientar que o GITHUB_TOKEN é gerado automaticamente pelo GitHub. Você pode conferir mais sobre isso aqui.

Passo 5: Criar a nova release

Preencha as informações de tag e crie a nova release. Isso acionará a execução da action.

Passo 6: Usando o pacote nos seus projetos

Antes de instalar o pacote, siga estas etapas:

Crie um token de acesso pessoal no GitHub para autenticação com a API do GitHub e instalação do seu pacote. Vá em Configurações / Configurações de Desenvolvedor / Token de Acesso Pessoal e gere um novo token com a permissão de leitura.
No projeto onde o pacote será utilizado, crie um arquivo chamado .npmrc na raiz do projeto.
Adicione a seguinte configuração no seu arquivo .npmrc, substituindo <GITHUB_TOKEN> pelo token gerado anteriormente:

//npm.pkg.github.com/:_authToken=<GITHUB_TOKEN>
@organizationName:registry=https://npm.pkg.github.com

Agora, você já pode instalar o pacote no seu projeto utilizando:

Via package.json:

"@carloshendvpm/meu-pacote": "1.0.0"

Via terminal:

npm install @carloshendvpm/meu-pacote@1.0.0

Conclusão

Espero ter ajudado de alguma forma. Em breve, pretendo trazer um tutorial completo sobre a criação de um package utilizando a Svelte Library. Se tiver alguma sugestão, não hesite em comentar ou me corrigir caso tenha notado algum erro.

Como publicar um package npm de forma privada utilizando Github Packages