package.json no Node.js: scripts e dependências

package.json no Node.js é o arquivo que descreve um projeto JavaScript: nome, versão, scripts, dependências, formato de módulos, entradas públicas, requisitos de runtime e metadados de publicação.

Ele não serve apenas para instalar pacotes. Ferramentas de build, testes, lint, gerenciadores de dependências e o próprio Node.js interpretam campos diferentes. Uma configuração descuidada pode publicar arquivos privados, carregar o formato de módulo errado ou instalar dependências de produção desnecessárias.

Neste guia, você aprenderá os campos mais importantes, scripts, dependências, engines, exports, workspaces, arquivos publicados, segurança e validação para produção.

Criando o arquivo

npm init -y

O comando gera uma base que deve ser revisada. Remova campos inúteis e não aceite valores padrão sem entender seu efeito.

Nome do pacote

{
  "name": "api-client"
}

Para publicação, o nome precisa seguir as regras do registry. Pacotes privados podem usar escopo:

{
  "name": "@empresa/api-client",
  "private": true
}

private: true reduz risco de publicação acidental.

Versão

{
  "version": "1.4.2"
}

A versão comunica compatibilidade. Mudanças incompatíveis, novos recursos e correções devem seguir uma política clara.

Descrição e licença

{
  "description": "Cliente HTTP interno para serviços",
  "license": "MIT"
}

Use uma licença válida e coerente com o repositório. Em projetos privados, registre a política interna em vez de copiar uma licença aleatória.

Scripts

{
  "scripts": {
    "dev": "node --watch src/server.js",
    "start": "node src/server.js",
    "test": "node --test",
    "lint": "eslint .",
    "check": "npm run lint && npm test"
  }
}

Scripts padronizam tarefas entre desenvolvimento local e CI. Evite comandos que dependam de ferramentas globais.

dependencies

Dependências necessárias em produção ficam em dependencies:

{
  "dependencies": {
    "pino": "^9.0.0"
  }
}

Não coloque framework ou driver usado em runtime dentro de devDependencies.

devDependencies

{
  "devDependencies": {
    "eslint": "^9.0.0"
  }
}

Inclua ferramentas de teste, lint, build e desenvolvimento que não são carregadas pela aplicação publicada.

peerDependencies

Bibliotecas e plugins usam peer dependencies quando esperam que o consumidor forneça uma dependência compatível:

{
  "peerDependencies": {
    "fastify": "^5.0.0"
  }
}

Não use peer dependency apenas para reduzir tamanho. Ela expressa uma relação de integração.

optionalDependencies

Dependências opcionais podem falhar durante a instalação sem interromper todo o processo. O código deve detectar a ausência e oferecer comportamento controlado.

engines

{
  "engines": {
    "node": ">=22"
  }
}

Declare a versão mínima realmente testada. O campo orienta consumidores e ferramentas, mas a política de bloqueio depende do gerenciador usado.

type

{
  "type": "module"
}

O campo define como arquivos .js são interpretados. Veja ESM no Node.js e CommonJS no Node.js.

main

{
  "main": "./dist/index.cjs"
}

main define a entrada tradicional. Pacotes modernos devem considerar exports para limitar caminhos públicos.

exports

{
  "exports": {
    ".": "./dist/index.js",
    "./errors": "./dist/errors.js"
  }
}

O artigo Package Exports no Node.js explica subpaths e encapsulamento.

imports

{
  "imports": {
    "#config": "./src/config.js",
    "#logger": "./src/logger.js"
  }
}

Aliases internos começam com # e não viram API pública.

files

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

O campo controla quais arquivos entram no pacote. Verifique com:

npm pack --dry-run

Não publique segredos, fixtures privadas ou código-fonte desnecessário.

bin

{
  "bin": {
    "minha-cli": "./bin/cli.js"
  }
}

O arquivo deve possuir shebang adequado e permissões corretas no pacote.

workspaces

{
  "workspaces": [
    "apps/*",
    "packages/*"
  ]
}

Workspaces ajudam a gerenciar monorepos, dependências locais e scripts por pacote.

configuração de publicação

{
  "publishConfig": {
    "access": "public"
  }
}

Revise registry e visibilidade antes de publicar. Pacotes corporativos podem exigir registry privado.

sideEffects

Ferramentas de bundling interpretam sideEffects para remover código não utilizado. Não marque como falso se módulos executam registro global, importam CSS ou alteram estado.

scripts de ciclo de vida

Scripts como preinstall, postinstall, prepare e prepublishOnly executam em momentos específicos. Eles aumentam risco de cadeia de suprimentos e devem ser mínimos.

Não baixe binários de origem não verificada durante instalação.

Overrides

O campo overrides pode forçar versões transitivas em projetos npm:

{
  "overrides": {
    "pacote-vulneravel": "2.4.1"
  }
}

Use como correção controlada e remova quando a árvore principal estiver atualizada.

Lockfile

O package-lock.json registra a árvore resolvida. Ele deve ser versionado em aplicações para instalações reproduzíveis. Não edite manualmente.

Metadados do repositório

{
  "repository": {
    "type": "git",
    "url": "git+https://example.com/empresa/projeto.git"
  },
  "bugs": {
    "url": "https://example.com/empresa/projeto/issues"
  }
}

Esses dados ajudam consumidores e automações a localizar código e suporte.

Validação no CI

O pipeline deve verificar JSON válido, versão de Node suportada, presença de licença, pacote gerado e testes de consumo.

npm ci
npm test
npm pack --dry-run

Segurança

• use private: true quando o pacote não deve ser publicado;
• revise scripts de instalação;
• não coloque tokens no arquivo;
• restrinja arquivos publicados;
• fixe permissões do registry;
• audite dependências;
• proteja o lockfile.

Erros comuns

• versão mínima não testada;
• dependência de produção em devDependencies;
• exports apontando para arquivo ausente;
• publicar pasta inteira;
• scripts dependentes de ferramenta global;
• misturar ESM e CommonJS sem estratégia;
• executar download inseguro no postinstall;
• não validar o tarball.

Checklist recomendado

• nome e versão corretos;
• private configurado;
• type explícito;
• scripts reproduzíveis;
• dependências classificadas;
• engines documentado;
• exports testado;
• files restrito;
• lockfile versionado;
• npm pack conferido.

Conclusão

package.json no Node.js é o contrato operacional do projeto. Ele orienta runtime, instalação, testes, publicação e compatibilidade. Quanto mais explícita a configuração, menor a chance de comportamento diferente entre máquinas e ambientes.

Mantenha o arquivo enxuto, revise cada campo e teste o pacote como consumidor. Uma boa configuração não depende de convenções ocultas e não publica conteúdo além do necessário.

Consulte a documentação oficial do package.json no npm e a documentação de pacotes do Node.js.