Scripts do package.json

Q: Qual é a diferença entre prepare e prepublishOnly?

prepare é executado em npm install (incluindo dependências git) e antes de empacotar/publicar. prepublishOnly é executado apenas imediatamente antes de npm publish. Use prepare para builds que os consumidores precisam; use prepublishOnly para verificações exclusivas de publicação.

Q: Posso executar vários comandos em um único script?

Encadeie com && para que as etapas posteriores sejam ignoradas se uma etapa anterior falhar.

Q: Como passo argumentos para um script?

Argumentos após -- são encaminhados para o comando subjacente.

Q: O start deve executar tsx ou JS compilado?

start de produção deve executar node dist/... após build. O desenvolvimento usa tsx watch através de um script dev separado.

Q: Por que npm run build é executado em npm install na minha biblioteca?

prepare é executado após a instalação quando o pacote é instalado do git ou de um caminho local. Publique dist/ compilado no npm ou documente a etapa de compilação.

Q: Como silenciar a saída do ciclo de vida na CI?

Use --ignore-scripts apenas quando você controla totalmente o que é ignorado. Prefira npm run build explícito na CI em vez de depender de efeitos colaterais.

Q: Scripts podem chamar outros scripts de pacote?

Sim: "check": "npm run lint && npm run test". O npm resolve binários locais automaticamente.

Q: O que é executado antes de npm version?

preversion (opcional), em seguida, o aumento da versão, em seguida, postversion. Use postversion para enviar tags.

Q: Devo usar npx dentro de scripts?

Prefira devDependencies (tsx, eslint) e nomes de comando brutos (tsx, eslint) para que as versões sejam fixadas pelo lockfile.

Q: Como os monorepos organizam scripts?

O package.json raiz delega: "test": "turbo run test". Cada workspace mantém seus próprios scripts build/test.

Scripts de ciclo de vida do npm automatizam etapas de build, teste e publicação. Eles são o contrato entre desenvolvedores, CI e pipelines de implantação.

Receita

Cartão de receita de referência rápida - pronto para copiar e colar.

{
  "scripts": {
    "dev": "tsx watch src/index.ts",
    "build": "tsc -p tsconfig.build.json",
    "start": "node dist/index.js",
    "test": "node --import tsx --test test/**/*.test.ts",
    "typecheck": "tsc --noEmit",
    "prepare": "npm run build",
    "prepublishOnly": "npm test && npm run typecheck"
  }
}

Quando usar isso:

Você precisa de um comando (npm test) que funcione localmente e na CI.
Instalações Git ou npm publish precisam compilar TypeScript antes que os consumidores importem o pacote.
Você deseja salvaguardas que bloqueiem publicações com falha sem precisar lembrar de etapas manuais.

Exemplo de Trabalho

{
  "name": "@acme/billing-api",
  "version": "1.4.0",
  "type": "module",
  "main": "./dist/index.js",
  "types": "./dist/index.d.ts",
  "files": ["dist"],
  "scripts": {
    "dev": "tsx watch src/server.ts",
    "build": "tsc -p tsconfig.build.json",
    "start": "node dist/server.js",
    "test": "node --import tsx --test",
    "typecheck": "tsc --noEmit",
    "lint": "eslint .",
    "prepare": "npm run build",
    "prepublishOnly": "npm run lint && npm test && npm run typecheck",
    "postversion": "git push && git push --tags"
  }
}

# Desenvolvimento local
npm run dev
 
# Pipeline de CI (mesmos pontos de entrada)
npm ci
npm run lint
npm run typecheck
npm test
npm run build

O que isso demonstra:

dev usa tsx watch para iteração rápida de TypeScript sem uma etapa de compilação separada.
prepare é executado em npm install quando o pacote é instalado do git ou de um tarball empacotado.
prepublishOnly é executado apenas antes de npm publish, capturando regressões antes que cheguem ao registro.
postversion automatiza o push de tags após npm version patch.

Mergulho Profundo

Como Funciona

O npm executa scripts por nome: npm run <script> ou npm test para o alias test.
Hooks de ciclo de vida (prepare, prepublishOnly, postinstall) são acionados automaticamente em momentos definidos.
Scripts herdam PATH com node_modules/.bin pré-anexado, então CLIs locais são resolvidos sem npx.
npm run define npm_lifecycle_event para que os scripts possam ramificar com base no hook de acionamento.

Hooks de Ciclo de Vida Comuns

Hook	Quando é executado	Uso Típico
`prepare`	Após `npm install` (local e empacotado)	Compilar TypeScript, gerar tipos
`prepublishOnly`	Antes de `npm publish`	Testes, lint, verificação de build
`postinstall`	Após a instalação de dependências	Builds de add-on nativos (use com moderação)
`preversion` / `postversion`	Em torno de `npm version`	Changelog, push de tag git

Notas de TypeScript

{
  "scripts": {
    "dev": "tsx watch src/index.ts",
    "build": "tsc -p tsconfig.build.json",
    "typecheck": "tsc --noEmit -p tsconfig.json"
  }
}

Mantenha typecheck separado de build para que a CI possa falhar rapidamente sem emitir dist/.
Use tsx para desenvolvimento; envie JS compilado em dist/ para produção node dist/....

Armadilhas

Loops infinitos de prepare - prepare chamando npm install ou reinstalando o gatilho. Correção: compile ou copie apenas arquivos em prepare.
postinstall pesado - Instalações lentas frustram todos os desenvolvedores e trabalhos de CI. Correção: mova a configuração opcional para npm run setup documentado.
Ignorando testes na publicação - npm publish --ignore-scripts ignora prepublishOnly. Correção: force a publicação de CI a partir de commits marcados com verificações de script.
Variáveis de ambiente multiplataforma - NODE_ENV=production cmd falha em shells do Windows. Correção: use cross-env ou flags específicas do framework.
Dependências Git implícitas de prepare - Instalar do GitHub executa prepare, o que pode surpreender os consumidores. Correção: publique artefatos pré-compilados no npm em vez de URLs git para bibliotecas.

Alternativas

Alternativa	Use Quando	Não Use Quando
Makefile / `just`	Repositórios poliglotos, fluxos de trabalho com muitas operações	A equipe espera `npm test` em todos os lugares
Pipeline de tarefas do Turborepo	Monorepos com `build`/`test` em cache	Serviço de API de pacote único
Husky + lint-staged	Apenas formatação pré-commit	Substituir completamente os portões de CI

FAQs

Qual é a diferença entre prepare e prepublishOnly?

prepare é executado em npm install (incluindo dependências git) e antes de empacotar/publicar.
prepublishOnly é executado apenas imediatamente antes de npm publish.
Use prepare para builds que os consumidores precisam; use prepublishOnly para verificações exclusivas de publicação.

Posso executar vários comandos em um único script?

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

Encadeie com && para que as etapas posteriores sejam ignoradas se uma etapa anterior falhar.

Como passo argumentos para um script?

npm test -- --grep "billing"

Argumentos após -- são encaminhados para o comando subjacente.

O start deve executar tsx ou JS compilado?

start de produção deve executar node dist/... após build.
O desenvolvimento usa tsx watch através de um script dev separado.

Por que npm run build é executado em npm install na minha biblioteca?

prepare é executado após a instalação quando o pacote é instalado do git ou de um caminho local. Publique dist/ compilado no npm ou documente a etapa de compilação.

Como silenciar a saída do ciclo de vida na CI?

Use --ignore-scripts apenas quando você controla totalmente o que é ignorado. Prefira npm run build explícito na CI em vez de depender de efeitos colaterais.

Scripts podem chamar outros scripts de pacote?

Sim: "check": "npm run lint && npm run test". O npm resolve binários locais automaticamente.

O que é executado antes de npm version?

preversion (opcional), em seguida, o aumento da versão, em seguida, postversion. Use postversion para enviar tags.

Devo usar npx dentro de scripts?

Prefira devDependencies (tsx, eslint) e nomes de comando brutos (tsx, eslint) para que as versões sejam fixadas pelo lockfile.

Como os monorepos organizam scripts?

O package.json raiz delega: "test": "turbo run test". Cada workspace mantém seus próprios scripts build/test.

Relacionado

Lockfiles e Instalações Reproduzíveis - A CI usa o mesmo caminho de instalação
Publicando no npm - Higiene de semver e publicação
Noções Básicas de Gerenciadores de Pacotes - Seleção de gerenciador

Versões da Stack: Esta página foi escrita para Node.js 24.18.0 (Active LTS), npm 10+, TypeScript 5.6+, Express 5, Fastify 5 e NestJS 11.

Scripts do package.json

Scripts de ciclo de vida do npm automatizam etapas de build, teste e publicação. Eles são o contrato entre desenvolvedores, CI e pipelines de implantação.

Receita

Cartão de receita de referência rápida - pronto para copiar e colar.

{
  "scripts": {
    "dev": "tsx watch src/index.ts",
    "build": "tsc -p tsconfig.build.json",
    "start": "node dist/index.js",
    "test": "node --import tsx --test test/**/*.test.ts",
    "typecheck": "tsc --noEmit",
    "prepare": "npm run build",
    "prepublishOnly": "npm test && npm run typecheck"
  }
}

Quando usar isso:

Você precisa de um comando (npm test) que funcione localmente e na CI.
Instalações Git ou npm publish precisam compilar TypeScript antes que os consumidores importem o pacote.
Você deseja salvaguardas que bloqueiem publicações com falha sem precisar lembrar de etapas manuais.

Exemplo de Trabalho

{
  "name": "@acme/billing-api",
  "version": "1.4.0",
  "type": "module",
  "main": "./dist/index.js",
  "types": "./dist/index.d.ts",
  "files": ["dist"],
  "scripts": {
    "dev": "tsx watch src/server.ts",
    "build": "tsc -p tsconfig.build.json",
    "start": "node dist/server.js",
    "test": "node --import tsx --test",
    "typecheck": "tsc --noEmit",
    "lint": "eslint .",
    "prepare": "npm run build",
    "prepublishOnly": "npm run lint && npm test && npm run typecheck",
    "postversion": "git push && git push --tags"
  }
}

# Desenvolvimento local
npm run dev
 
# Pipeline de CI (mesmos pontos de entrada)
npm ci
npm run lint
npm run typecheck
npm test
npm run build

O que isso demonstra:

dev usa tsx watch para iteração rápida de TypeScript sem uma etapa de compilação separada.
prepare é executado em npm install quando o pacote é instalado do git ou de um tarball empacotado.
prepublishOnly é executado apenas antes de npm publish, capturando regressões antes que cheguem ao registro.
postversion automatiza o push de tags após npm version patch.

Mergulho Profundo

Como Funciona

O npm executa scripts por nome: npm run <script> ou npm test para o alias test.
Hooks de ciclo de vida (prepare, prepublishOnly, postinstall) são acionados automaticamente em momentos definidos.
Scripts herdam PATH com node_modules/.bin pré-anexado, então CLIs locais são resolvidos sem npx.
npm run define npm_lifecycle_event para que os scripts possam ramificar com base no hook de acionamento.

Hooks de Ciclo de Vida Comuns

Hook	Quando é executado	Uso Típico
`prepare`	Após `npm install` (local e empacotado)	Compilar TypeScript, gerar tipos
`prepublishOnly`	Antes de `npm publish`	Testes, lint, verificação de build
`postinstall`	Após a instalação de dependências	Builds de add-on nativos (use com moderação)
`preversion` / `postversion`	Em torno de `npm version`	Changelog, push de tag git

Notas de TypeScript

{
  "scripts": {
    "dev": "tsx watch src/index.ts",
    "build": "tsc -p tsconfig.build.json",
    "typecheck": "tsc --noEmit -p tsconfig.json"
  }
}

Mantenha typecheck separado de build para que a CI possa falhar rapidamente sem emitir dist/.
Use tsx para desenvolvimento; envie JS compilado em dist/ para produção node dist/....

Armadilhas

Loops infinitos de prepare - prepare chamando npm install ou reinstalando o gatilho. Correção: compile ou copie apenas arquivos em prepare.
postinstall pesado - Instalações lentas frustram todos os desenvolvedores e trabalhos de CI. Correção: mova a configuração opcional para npm run setup documentado.
Ignorando testes na publicação - npm publish --ignore-scripts ignora prepublishOnly. Correção: force a publicação de CI a partir de commits marcados com verificações de script.
Variáveis de ambiente multiplataforma - NODE_ENV=production cmd falha em shells do Windows. Correção: use cross-env ou flags específicas do framework.
Dependências Git implícitas de prepare - Instalar do GitHub executa prepare, o que pode surpreender os consumidores. Correção: publique artefatos pré-compilados no npm em vez de URLs git para bibliotecas.

Alternativas

Alternativa	Use Quando	Não Use Quando
Makefile / `just`	Repositórios poliglotos, fluxos de trabalho com muitas operações	A equipe espera `npm test` em todos os lugares
Pipeline de tarefas do Turborepo	Monorepos com `build`/`test` em cache	Serviço de API de pacote único
Husky + lint-staged	Apenas formatação pré-commit	Substituir completamente os portões de CI

FAQs

Qual é a diferença entre prepare e prepublishOnly?

prepare é executado em npm install (incluindo dependências git) e antes de empacotar/publicar.
prepublishOnly é executado apenas imediatamente antes de npm publish.
Use prepare para builds que os consumidores precisam; use prepublishOnly para verificações exclusivas de publicação.

Posso executar vários comandos em um único script?

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

Encadeie com && para que as etapas posteriores sejam ignoradas se uma etapa anterior falhar.

Como passo argumentos para um script?

npm test -- --grep "billing"

Argumentos após -- são encaminhados para o comando subjacente.

O start deve executar tsx ou JS compilado?

start de produção deve executar node dist/... após build.
O desenvolvimento usa tsx watch através de um script dev separado.

Por que npm run build é executado em npm install na minha biblioteca?

prepare é executado após a instalação quando o pacote é instalado do git ou de um caminho local. Publique dist/ compilado no npm ou documente a etapa de compilação.

Como silenciar a saída do ciclo de vida na CI?

Use --ignore-scripts apenas quando você controla totalmente o que é ignorado. Prefira npm run build explícito na CI em vez de depender de efeitos colaterais.

Scripts podem chamar outros scripts de pacote?

Sim: "check": "npm run lint && npm run test". O npm resolve binários locais automaticamente.

O que é executado antes de npm version?

preversion (opcional), em seguida, o aumento da versão, em seguida, postversion. Use postversion para enviar tags.

Devo usar npx dentro de scripts?

Prefira devDependencies (tsx, eslint) e nomes de comando brutos (tsx, eslint) para que as versões sejam fixadas pelo lockfile.

Como os monorepos organizam scripts?

O package.json raiz delega: "test": "turbo run test". Cada workspace mantém seus próprios scripts build/test.

Relacionado

Lockfiles e Instalações Reproduzíveis - A CI usa o mesmo caminho de instalação
Publicando no npm - Higiene de semver e publicação
Noções Básicas de Gerenciadores de Pacotes - Seleção de gerenciador

Versões da Stack: Esta página foi escrita para Node.js 24.18.0 (Active LTS), npm 10+, TypeScript 5.6+, Express 5, Fastify 5 e NestJS 11.

Scripts do package.json

Buscar na documentação

Scripts do package.json