npm Scripts: automatize tarefas no Node.js

npm Scripts no Node.js é o mecanismo usado para padronizar comandos de desenvolvimento, testes, build, lint, migração e execução. Os scripts ficam no package.json e podem chamar binários instalados localmente sem depender de ferramentas globais.

Uma boa coleção de scripts reduz diferenças entre máquinas e simplifica CI. Uma coleção desorganizada, por outro lado, esconde efeitos colaterais, repete lógica e cria comandos impossíveis de executar em todos os sistemas.

Neste guia, você aprenderá scripts básicos, argumentos, variáveis, ciclos de vida, execução paralela, portabilidade, segurança e boas práticas.

Estrutura básica

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

Executando scripts

npm run dev
npm test
npm start

start e test possuem atalhos, mas npm run funciona para qualquer nome.

Binários locais

O npm adiciona node_modules/.bin ao PATH do script. Assim, ferramentas instaladas no projeto podem ser chamadas diretamente:

{
  "scripts": {
    "lint": "eslint ."
  }
}

Isso evita exigir instalação global e mantém a versão sob controle do lockfile.

Encadeamento com &&

{
  "scripts": {
    "check": "npm run lint && npm run test && npm run build"
  }
}

O próximo comando só executa quando o anterior termina com sucesso.

Execução independente

O operador ; não é portável da mesma forma em todos os shells e continua mesmo após falhas. Prefira ferramentas JavaScript ou scripts separados quando a lógica cresce.

Passando argumentos

npm test -- --test-name-pattern="usuário"

O separador -- encaminha os argumentos ao comando do script.

Scripts pre e post

{
  "scripts": {
    "pretest": "npm run lint",
    "test": "node --test",
    "posttest": "node scripts/report.js"
  }
}

Esses hooks executam automaticamente ao redor do script principal. Use com moderação, pois comportamento implícito pode surpreender.

Variáveis de ambiente

{
  "scripts": {
    "start": "NODE_ENV=production node src/server.js"
  }
}

Essa sintaxe não é portátil para todos os sistemas. Prefira configuração externa do ambiente, um script Node.js ou ferramenta compatível quando o time usa plataformas diferentes.

Scripts Node.js para lógica complexa

{
  "scripts": {
    "release:check": "node scripts/release-check.js"
  }
}

Em vez de escrever uma linha enorme de shell, coloque validações, mensagens e tratamento de erros em JavaScript.

Falhando corretamente

// scripts/check-env.js
const required = ['DATABASE_URL', 'JWT_ISSUER'];
const missing = required.filter((name) => !process.env[name]);

if (missing.length) {
  console.error(`Variáveis ausentes: ${missing.join(', ')}`);
  process.exitCode = 1;
}

O código de saída diferente de zero permite que CI detecte falha.

Modo watch

{
  "scripts": {
    "dev": "node --watch src/server.js",
    "test:watch": "node --test --watch"
  }
}

Não use watch em produção. Ele é uma ferramenta de desenvolvimento.

Scripts de build

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

O build deve ser determinístico e não depender de arquivos gerados fora do repositório sem uma etapa explícita.

CI

{
  "scripts": {
    "ci": "npm run lint && npm run test && npm run build"
  }
}

O pipeline pode chamar comandos menores diretamente para obter logs mais claros. O script agregado é útil para reproduzir localmente.

Workspaces

npm run test --workspaces --if-present

Veja npm Workspaces no Node.js para execução em monorepos.

Scripts de instalação

preinstall, install e postinstall podem executar código ao instalar dependências. Evite uso desnecessário, downloads sem validação e ações que dependem de rede instável.

prepare e prepublishOnly

prepare pode executar durante instalação de repositórios Git e publicação. prepublishOnly executa antes de publicar. Teste o fluxo para não exigir ferramentas ausentes no consumidor.

Segurança

• revise scripts de dependências;
• não coloque tokens na linha de comando;
• não aceite argumentos externos sem validação;
• evite downloads de origem arbitrária;
• restrinja permissões do ambiente de CI;
• fixe dependências no lockfile.

Segredos em argumentos

Argumentos podem aparecer em histórico, logs e lista de processos. Forneça segredos pelo mecanismo seguro do ambiente e redija logs conforme Secret Management no Node.js.

Portabilidade

Operadores, expansão de variáveis e comandos Unix podem falhar no Windows. Para equipes multiplataforma, prefira scripts Node.js ou ferramentas que abstraem o shell.

Nomes consistentes

Use convenções previsíveis:

• dev para desenvolvimento;
• start para produção;
• test e test:watch;
• lint e lint:fix;
• build e clean;
• db:migrate e db:seed.

Documentação

O README deve explicar pré-requisitos, variáveis e efeitos dos scripts destrutivos. Um nome curto não substitui documentação.

Erros comuns

• depender de instalação global;
• escrever shell não portátil;
• esconder lógica em pre e post;
• não propagar código de erro;
• executar watch em produção;
• colocar segredo no comando;
• usar postinstall sem necessidade;
• duplicar comandos no CI.

Checklist recomendado

• scripts pequenos e claros;
• binários locais;
• códigos de saída corretos;
• portabilidade testada;
• sem segredos em argumentos;
• hooks mínimos;
• build reproduzível;
• comando local equivalente ao CI;
• documentação de scripts destrutivos.

Conclusão

npm Scripts no Node.js transforma tarefas recorrentes em uma interface padronizada do projeto. Eles funcionam melhor quando apenas coordenam comandos simples e delegam lógica complexa a arquivos JavaScript testáveis.

Mantenha scripts explícitos, portáveis e seguros. Com dependências locais e códigos de saída corretos, o mesmo fluxo pode ser usado por desenvolvedores e automações.

Consulte a documentação oficial de npm scripts e a referência do npm run-script.