Scripts de package.json

Q: ¿Cuál es la diferencia entre prepare y prepublishOnly?

prepare se ejecuta en npm install (incluidas las dependencias de git) y antes de empaquetar/publicar. prepublishOnly se ejecuta solo inmediatamente antes de npm publish. Usa prepare para las construcciones que los consumidores necesitan; usa prepublishOnly para las comprobaciones solo de publicación.

Q: ¿Puedo ejecutar varios comandos en un solo script?

Encadena con && para que los pasos posteriores se salten si un paso anterior falla.

Q: ¿Cómo paso argumentos a un script?

Los argumentos después de -- se reenvían al comando subyacente.

Q: ¿Debería start ejecutar tsx o JS compilado?

start de producción debe ejecutar node dist/... después de build. El desarrollo usa tsx watch a través de un script dev separado.

Q: ¿Por qué npm ejecuta build en npm install en mi biblioteca?

prepare se ejecuta después de la instalación cuando el paquete se instala desde git o una ruta local. Publica dist/ compilado en npm o documenta el paso de compilación.

Q: ¿Cómo silencio la salida del ciclo de vida en CI?

Usa --ignore-scripts solo cuando controles completamente lo que se omite. Prefiere npm run build explícito en CI en lugar de depender de efectos secundarios.

Q: ¿Pueden los scripts llamar a otros scripts del paquete?

Sí: "check": "npm run lint && npm run test". npm resuelve los binarios locales automáticamente.

Q: ¿Qué se ejecuta antes de npm version?

preversion (opcional), luego el incremento de versión, luego postversion. Usa postversion para empujar etiquetas.

Q: ¿Debo usar npx dentro de los scripts?

Prefiere las devDependencies (tsx, eslint) y los nombres de comandos simples (tsx, eslint) para que las versiones estén fijadas en el lockfile.

Q: ¿Cómo organizan los monorepos los scripts?

El package.json raíz delega: "test": "turbo run test". Cada espacio de trabajo mantiene sus propios scripts build/test.

Los scripts de ciclo de vida de npm automatizan los pasos de construcción, prueba y publicación. Son el contrato entre desarrolladores, CI y pipelines de despliegue.

Receta

Tarjeta de receta de referencia rápida - lista para copiar y pegar.

{
  "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"
  }
}

Cuándo usarlo:

Necesitas un comando (npm test) que funcione localmente y en CI.
Las instalaciones de Git o npm publish deben compilar TypeScript antes de que los consumidores importen el paquete.
Quieres barreras de seguridad que bloqueen publicaciones rotas sin tener que recordar pasos manuales.

Ejemplo de trabajo

{
  "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"
  }
}

# Desarrollo local
npm run dev
 
# Pipeline de CI (mismos puntos de entrada)
npm ci
npm run lint
npm run typecheck
npm test
npm run build

Lo que esto demuestra:

dev usa tsx watch para una rápida iteración de TypeScript sin un paso de compilación separado.
prepare se construye en npm install cuando el paquete se instala desde git o un tarball empaquetado.
prepublishOnly se ejecuta solo antes de npm publish, detectando regresiones antes de que lleguen al registro.
postversion automatiza los pushes de etiquetas después de npm version patch.

Análisis profundo

Cómo funciona

npm ejecuta scripts por nombre: npm run <script> o npm test para el alias test.
Los hooks de ciclo de vida (prepare, prepublishOnly, postinstall) se disparan automáticamente en momentos definidos.
Los scripts heredan PATH con node_modules/.bin antepuesto, por lo que los CLIs locales se resuelven sin npx.
npm run establece npm_lifecycle_event para que los scripts puedan ramificarse en el hook que los activó.

Hooks de ciclo de vida comunes

Hook	Cuándo se ejecuta	Uso típico
`prepare`	Después de `npm install` (local y empaquetado)	Compilar TypeScript, generar tipos
`prepublishOnly`	Antes de `npm publish`	Pruebas, lint, verificación de construcción
`postinstall`	Después de la instalación de dependencias	Construcciones de complementos nativos (usar con moderación)
`preversion` / `postversion`	Alrededor de `npm version`	Changelog, push de etiquetas git

Notas de TypeScript

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

Mantén typecheck separado de build para que CI pueda fallar rápidamente sin emitir dist/.
Usa tsx para el desarrollo; envía JS compilado en dist/ para producción node dist/....

Errores comunes

Bucles infinitos de prepare - prepare llamando a npm install o reinstalando se activa a sí mismo. Solución: solo compila o copia archivos en prepare.
Postinstall pesado - Las instalaciones lentas frustran a todos los desarrolladores y trabajos de CI. Solución: mueve la configuración opcional a un npm run setup documentado.
Omitir pruebas en la publicación - npm publish --ignore-scripts omite prepublishOnly. Solución: fuerza la publicación de CI desde commits etiquetados con comprobaciones de scripts.
Variables de entorno multiplataforma - NODE_ENV=production cmd falla en shells de Windows. Solución: usa cross-env o banderas específicas del framework.
Prepare implícito en dependencias de git - La instalación desde GitHub ejecuta prepare, lo que puede sorprender a los consumidores. Solución: publica artefactos precompilados en npm en lugar de URLs de git para bibliotecas.

Alternativas

Alternativa	Usar cuándo	No usar cuándo
Makefile / `just`	Repositorios políglotas, flujos de trabajo pesados en operaciones	El equipo espera `npm test` en todas partes
Pipeline de tareas de Turborepo	Monorepos con `build`/`test` en caché	Servicio API de un solo paquete
Husky + lint-staged	Solo formato pre-commit	Reemplazar completamente las puertas de CI

Preguntas frecuentes

¿Cuál es la diferencia entre prepare y prepublishOnly?

prepare se ejecuta en npm install (incluidas las dependencias de git) y antes de empaquetar/publicar.
prepublishOnly se ejecuta solo inmediatamente antes de npm publish.
Usa prepare para las construcciones que los consumidores necesitan; usa prepublishOnly para las comprobaciones solo de publicación.

¿Puedo ejecutar varios comandos en un solo script?

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

Encadena con && para que los pasos posteriores se salten si un paso anterior falla.

¿Cómo paso argumentos a un script?

npm test -- --grep "billing"

Los argumentos después de -- se reenvían al comando subyacente.

¿Debería start ejecutar tsx o JS compilado?

start de producción debe ejecutar node dist/... después de build.
El desarrollo usa tsx watch a través de un script dev separado.

¿Por qué npm ejecuta build en npm install en mi biblioteca?

prepare se ejecuta después de la instalación cuando el paquete se instala desde git o una ruta local. Publica dist/ compilado en npm o documenta el paso de compilación.

¿Cómo silencio la salida del ciclo de vida en CI?

Usa --ignore-scripts solo cuando controles completamente lo que se omite. Prefiere npm run build explícito en CI en lugar de depender de efectos secundarios.

¿Pueden los scripts llamar a otros scripts del paquete?

Sí: "check": "npm run lint && npm run test". npm resuelve los binarios locales automáticamente.

¿Qué se ejecuta antes de npm version?

preversion (opcional), luego el incremento de versión, luego postversion. Usa postversion para empujar etiquetas.

¿Debo usar npx dentro de los scripts?

Prefiere las devDependencies (tsx, eslint) y los nombres de comandos simples (tsx, eslint) para que las versiones estén fijadas en el lockfile.

¿Cómo organizan los monorepos los scripts?

El package.json raíz delega: "test": "turbo run test". Cada espacio de trabajo mantiene sus propios scripts build/test.

Relacionado

Lockfiles e instalaciones reproducibles - CI usa la misma ruta de instalación
Publicación en npm - semver e higiene de publicación
Conceptos básicos de los gestores de paquetes - selección del gestor

Versiones de la pila: Esta página fue escrita para Node.js 24.18.0 (LTS activa), npm 10+, TypeScript 5.6+, Express 5, Fastify 5 y NestJS 11.

Scripts de package.json

Los scripts de ciclo de vida de npm automatizan los pasos de construcción, prueba y publicación. Son el contrato entre desarrolladores, CI y pipelines de despliegue.

Receta

Tarjeta de receta de referencia rápida - lista para copiar y pegar.

{
  "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"
  }
}

Cuándo usarlo:

Necesitas un comando (npm test) que funcione localmente y en CI.
Las instalaciones de Git o npm publish deben compilar TypeScript antes de que los consumidores importen el paquete.
Quieres barreras de seguridad que bloqueen publicaciones rotas sin tener que recordar pasos manuales.

Ejemplo de trabajo

{
  "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"
  }
}

# Desarrollo local
npm run dev
 
# Pipeline de CI (mismos puntos de entrada)
npm ci
npm run lint
npm run typecheck
npm test
npm run build

Lo que esto demuestra:

dev usa tsx watch para una rápida iteración de TypeScript sin un paso de compilación separado.
prepare se construye en npm install cuando el paquete se instala desde git o un tarball empaquetado.
prepublishOnly se ejecuta solo antes de npm publish, detectando regresiones antes de que lleguen al registro.
postversion automatiza los pushes de etiquetas después de npm version patch.

Análisis profundo

Cómo funciona

npm ejecuta scripts por nombre: npm run <script> o npm test para el alias test.
Los hooks de ciclo de vida (prepare, prepublishOnly, postinstall) se disparan automáticamente en momentos definidos.
Los scripts heredan PATH con node_modules/.bin antepuesto, por lo que los CLIs locales se resuelven sin npx.
npm run establece npm_lifecycle_event para que los scripts puedan ramificarse en el hook que los activó.

Hooks de ciclo de vida comunes

Hook	Cuándo se ejecuta	Uso típico
`prepare`	Después de `npm install` (local y empaquetado)	Compilar TypeScript, generar tipos
`prepublishOnly`	Antes de `npm publish`	Pruebas, lint, verificación de construcción
`postinstall`	Después de la instalación de dependencias	Construcciones de complementos nativos (usar con moderación)
`preversion` / `postversion`	Alrededor de `npm version`	Changelog, push de etiquetas git

Notas de TypeScript

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

Mantén typecheck separado de build para que CI pueda fallar rápidamente sin emitir dist/.
Usa tsx para el desarrollo; envía JS compilado en dist/ para producción node dist/....

Errores comunes

Bucles infinitos de prepare - prepare llamando a npm install o reinstalando se activa a sí mismo. Solución: solo compila o copia archivos en prepare.
Postinstall pesado - Las instalaciones lentas frustran a todos los desarrolladores y trabajos de CI. Solución: mueve la configuración opcional a un npm run setup documentado.
Omitir pruebas en la publicación - npm publish --ignore-scripts omite prepublishOnly. Solución: fuerza la publicación de CI desde commits etiquetados con comprobaciones de scripts.
Variables de entorno multiplataforma - NODE_ENV=production cmd falla en shells de Windows. Solución: usa cross-env o banderas específicas del framework.
Prepare implícito en dependencias de git - La instalación desde GitHub ejecuta prepare, lo que puede sorprender a los consumidores. Solución: publica artefactos precompilados en npm en lugar de URLs de git para bibliotecas.

Alternativas

Alternativa	Usar cuándo	No usar cuándo
Makefile / `just`	Repositorios políglotas, flujos de trabajo pesados en operaciones	El equipo espera `npm test` en todas partes
Pipeline de tareas de Turborepo	Monorepos con `build`/`test` en caché	Servicio API de un solo paquete
Husky + lint-staged	Solo formato pre-commit	Reemplazar completamente las puertas de CI

Preguntas frecuentes

¿Cuál es la diferencia entre prepare y prepublishOnly?

prepare se ejecuta en npm install (incluidas las dependencias de git) y antes de empaquetar/publicar.
prepublishOnly se ejecuta solo inmediatamente antes de npm publish.
Usa prepare para las construcciones que los consumidores necesitan; usa prepublishOnly para las comprobaciones solo de publicación.

¿Puedo ejecutar varios comandos en un solo script?

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

Encadena con && para que los pasos posteriores se salten si un paso anterior falla.

¿Cómo paso argumentos a un script?

npm test -- --grep "billing"

Los argumentos después de -- se reenvían al comando subyacente.

¿Debería start ejecutar tsx o JS compilado?

start de producción debe ejecutar node dist/... después de build.
El desarrollo usa tsx watch a través de un script dev separado.

¿Por qué npm ejecuta build en npm install en mi biblioteca?

prepare se ejecuta después de la instalación cuando el paquete se instala desde git o una ruta local. Publica dist/ compilado en npm o documenta el paso de compilación.

¿Cómo silencio la salida del ciclo de vida en CI?

Usa --ignore-scripts solo cuando controles completamente lo que se omite. Prefiere npm run build explícito en CI en lugar de depender de efectos secundarios.

¿Pueden los scripts llamar a otros scripts del paquete?

Sí: "check": "npm run lint && npm run test". npm resuelve los binarios locales automáticamente.

¿Qué se ejecuta antes de npm version?

preversion (opcional), luego el incremento de versión, luego postversion. Usa postversion para empujar etiquetas.

¿Debo usar npx dentro de los scripts?

Prefiere las devDependencies (tsx, eslint) y los nombres de comandos simples (tsx, eslint) para que las versiones estén fijadas en el lockfile.

¿Cómo organizan los monorepos los scripts?

El package.json raíz delega: "test": "turbo run test". Cada espacio de trabajo mantiene sus propios scripts build/test.

Relacionado

Lockfiles e instalaciones reproducibles - CI usa la misma ruta de instalación
Publicación en npm - semver e higiene de publicación
Conceptos básicos de los gestores de paquetes - selección del gestor

Versiones de la pila: Esta página fue escrita para Node.js 24.18.0 (LTS activa), npm 10+, TypeScript 5.6+, Express 5, Fastify 5 y NestJS 11.

Scripts de package.json

Buscar en la documentación

Scripts de package.json