Publicar Pacote no npm

Publicar pacote no npm transforma uma biblioteca Node.js em um artefato versionado que pode ser instalado por outros projetos. O processo envolve mais do que executar npm publish: é preciso definir nome, licença, exports, arquivos incluídos, build, versão, autenticação, testes e política de manutenção.

Uma publicação incorreta pode expor chaves privadas, enviar código-fonte desnecessário, quebrar tipos ou ocupar uma versão que não pode ser sobrescrita. Por isso, o pacote deve ser inspecionado como tarball e testado em um projeto consumidor antes de chegar ao registry.

Neste guia, você aprenderá a preparar um pacote público com scope, controlar conteúdo, testar, usar 2FA, dist-tags, provenance, trusted publishing e staged publishing.

Conta e autenticação

Crie uma conta npm e habilite autenticação de dois fatores. Confirme a sessão:

npm whoami
npm profile get

Para entrar:

npm login

Não compartilhe tokens nem grave credenciais em .npmrc versionado.

Nome do pacote

Um pacote sem scope:

{
  "name": "minha-biblioteca"
}

Um pacote com scope:

{
  "name": "@empresa/minha-biblioteca"
}

Scopes evitam colisões e agrupam pacotes de usuário ou organização.

Inicialização

mkdir minha-biblioteca
cd minha-biblioteca
npm init --scope=@empresa

A documentação de publicação de pacotes scoped recomenda criar README, revisar conteúdo e testar antes da publicação.

package.json básico

{
  "name": "@empresa/domain",
  "version": "1.0.0",
  "description": "Objetos e regras de domínio reutilizáveis",
  "type": "module",
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "default": "./dist/index.js"
    }
  },
  "types": "./dist/index.d.ts",
  "files": ["dist", "README.md", "LICENSE"],
  "license": "MIT",
  "repository": {
    "type": "git",
    "url": "git+https://github.com/empresa/domain.git"
  },
  "scripts": {
    "build": "tsc -p tsconfig.build.json",
    "test": "node --test",
    "prepack": "npm run test && npm run build"
  }
}

Descrição e keywords

{
  "description": "Validação e regras de pedidos para Node.js",
  "keywords": ["nodejs", "typescript", "domain", "validation"]
}

Use termos relevantes, não listas enganosas.

Licença

Escolha uma licença e inclua o arquivo correspondente. Sem licença clara, consumidores não sabem quais usos são permitidos. Confirme direitos sobre todo código e assets publicados.

README

O README deve incluir:

• objetivo;
• instalação;
• exemplo mínimo;
• API pública;
• versões suportadas do Node.js;
• configuração;
• migração;
• licença e suporte.

Exports e tipos

Defina entry points explícitos e declarations:

{
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "default": "./dist/index.js"
    },
    "./errors": {
      "types": "./dist/errors.d.ts",
      "default": "./dist/errors.js"
    }
  }
}

Veja Exports e Imports no package.json.

Campo files

{
  "files": [
    "dist",
    "README.md",
    "LICENSE"
  ]
}

O allowlist é mais seguro do que depender apenas de .npmignore. Arquivos obrigatórios e regras do npm ainda podem ser incluídos.

.npmignore

Quando necessário:

src/
test/
coverage/
.github/
.env*
*.log

O npm pode usar .gitignore quando .npmignore não existe. Mesmo assim, inspecione o resultado.

Segredos

Nunca publique:

• .env;
• tokens;
• chaves SSH;
• certificados privados;
• dados pessoais;
• fixtures de produção;
• configurações internas.

Consulte Gestão de Segredos no Node.js.

Inspecionando o tarball

npm pack --dry-run

Revise lista, tamanho e entry points. Depois gere o pacote:

npm pack

O arquivo .tgz representa o que será publicado.

Teste em consumidor temporário

mkdir /tmp/teste-pacote
cd /tmp/teste-pacote
npm init -y
npm install /caminho/empresa-domain-1.0.0.tgz

node --input-type=module -e "import('@empresa/domain').then(console.log)"

Compile também um consumidor TypeScript para verificar declarations e exports.

Build antes do pack

{
  "scripts": {
    "clean": "node scripts/clean.js",
    "build": "tsc -p tsconfig.build.json",
    "prepack": "npm run clean && npm run check && npm run build"
  }
}

Veja npm Scripts no Node.js.

Versionamento

npm version patch
npm version minor
npm version major

Não publique a mesma versão duas vezes. Consulte Semantic Versioning no Node.js.

Publicação pública scoped

npm publish --access public

Pacotes scoped são privados por padrão em determinados fluxos; --access public deixa a intenção explícita.

Configuração publishConfig

{
  "publishConfig": {
    "access": "public",
    "provenance": true
  }
}

Revise o registry configurado para não publicar no destino errado.

2FA

Publicação direta exige política de autenticação adequada, como 2FA ou token granular configurado conforme as regras atuais do npm. Prefira mecanismos sem token de longa duração em CI.

Trusted publishing com OIDC

Trusted publishing permite que um workflow autorizado obtenha credencial temporária via OIDC. Isso evita armazenar um token npm permanente no repositório.

Configure o package no npm para confiar no repositório e workflow exatos. No GitHub Actions, use:

permissions:
  contents: read
  id-token: write

Fixe actions, proteja branch e execute publicação somente após checks.

Provenance

Provenance vincula o pacote ao workflow e repositório que o produziram, ajudando consumidores a verificar origem.

npm publish --provenance --access public

Veja Supply Chain no Node.js.

Staged publishing

O npm oferece staged publishing em fluxos suportados. O CI envia o pacote para uma área de staging e um mantenedor revisa e aprova com 2FA antes da publicação.

npm stage publish

npm stage list @empresa/domain
npm stage approve ID

Esse processo adiciona revisão humana sem fornecer 2FA ao CI.

Dist-tags

npm publish --tag next
npm dist-tag add @empresa/domain@2.0.0-beta.1 beta
npm dist-tag ls @empresa/domain

Use next ou beta para pré-releases. Confirme antes de alterar latest.

Pacote privado

Para pacote interno:

{
  "name": "@empresa/internal-sdk",
  "private": false,
  "publishConfig": {
    "access": "restricted"
  }
}

Já aplicações que nunca devem ser publicadas usam private: true.

Workspaces

npm publish -w @empresa/domain
npm pack -w @empresa/domain --dry-run

Veja npm Workspaces no Node.js.

CI de release

Uma pipeline deve:

1. fazer checkout seguro;
2. configurar Node.js;
3. executar npm ci;
4. rodar lint, typecheck e testes;
5. gerar build;
6. inspecionar pack;
7. publicar via OIDC ou staging;
8. criar release e changelog.

Consulte CI para Node.js com GitHub Actions.

Não publique de pull request

PRs podem conter código não confiável. Publique somente de branch ou tag protegida, após aprovação e checks. Não exponha credenciais em workflows acionados por forks.

Deprecar versão

npm deprecate @empresa/domain@1.2.0 "Use 1.2.1; esta versão contém um bug"

Depreciação avisa durante instalação sem apagar o artefato.

Unpublish

Remover pacote possui políticas e impacto em consumidores. Prefira deprecar e publicar correção. Nunca conte com a possibilidade de sobrescrever uma versão removida.

Transferência e colaboradores

Use organizações, equipes e permissões mínimas. Evite pacote crítico controlado por uma única conta. Exija 2FA para mantenedores.

Monitoramento pós-release

Após publicar:

• instale a versão do registry em projeto limpo;
• confirme página e README;
• verifique dist-tag;
• acompanhe issues;
• publique correção se necessário;
• não tente alterar tarball existente.

Erros comuns

• Sem npm pack: arquivos faltam ou segredos entram.
• Scope público sem access: publicação falha ou fica restrita.
• Versão já usada: não pode sobrescrever.
• Token longo no CI: risco de vazamento.
• Exports apontam para arquivo ausente: instalação quebra.
• Types não incluídos: TypeScript falha.
• Beta em latest: consumidores recebem versão instável.
• Publicar de PR: supply chain comprometida.

Checklist

• Nome e scope corretos.
• Versão SemVer nova.
• README e licença.
• Exports e tipos válidos.
• Campo files restritivo.
• Nenhum segredo.
• Lint, testes e build aprovados.
• npm pack --dry-run revisado.
• Tarball testado.
• 2FA, OIDC ou staging configurado.
• Dist-tag confirmado.
• Provenance habilitada.

Conclusão

Publicar pacote no npm exige tratar o tarball como um produto. Nome, versão, exports, tipos, documentação e arquivos incluídos formam o contrato entregue aos consumidores.

Teste o pacote empacotado, use autenticação forte, prefira OIDC ou staged publishing e gere provenance. Com CI protegida e SemVer consistente, releases se tornam reproduzíveis e reduzem o risco de expor dados ou quebrar projetos dependentes.