package.json Scripts

npm lifecycle scripts automate build, test, and publish steps. They are the contract between developers, CI, and deployment pipelines.

Recipe

Quick-reference recipe card - copy-paste ready.

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

When to reach for this:

• You need one command (npm test) that works locally and in CI.
• Git installs or npm publish must compile TypeScript before consumers import the package.
• You want guardrails that block broken publishes without remembering manual steps.

Working Example

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

# Local development
npm run dev
 
# CI pipeline (same entry points)
npm ci
npm run lint
npm run typecheck
npm test
npm run build

What this demonstrates:

• dev uses tsx watch for fast TypeScript iteration without a separate compile step.
• prepare builds on npm install when the package is installed from git or packed tarball.
• prepublishOnly runs only before npm publish, catching regressions before they hit the registry.
• postversion automates tag pushes after npm version patch.

Deep Dive

How It Works

• npm runs scripts by name: npm run <script> or npm test for the test alias.
• Lifecycle hooks (prepare, prepublishOnly, postinstall) fire automatically at defined moments.
• Scripts inherit PATH with node_modules/.bin prepended, so local CLIs resolve without npx.
• npm run sets npm_lifecycle_event so scripts can branch on the triggering hook.

Common Lifecycle Hooks

TypeScript Notes

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

• Keep typecheck separate from build so CI can fail fast without emitting dist/.
• Use tsx for dev; ship compiled JS in dist/ for production node dist/....

Gotchas

• Infinite prepare loops - prepare calling npm install or reinstalling triggers itself. Fix: only compile or copy files in prepare.
• Heavy postinstall - Slow installs frustrate every developer and CI job. Fix: move optional setup to documented npm run setup.
• Skipping tests on publish - npm publish --ignore-scripts bypasses prepublishOnly. Fix: enforce CI publish from tagged commits with script checks.
• Cross-platform env vars - NODE_ENV=production cmd fails on Windows shells. Fix: use cross-env or framework-specific flags.
• Implicit prepare on git deps - Installing from GitHub runs prepare, which can surprise consumers. Fix: publish prebuilt artifacts to npm instead of git URLs for libraries.

Alternatives

FAQs

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

npm test -- --grep "billing"

Related

• Lockfiles & Reproducible Installs - CI uses the same install path
• Publishing to npm - semver and publish hygiene
• Package Managers Basics - manager selection

Stack versions: This page was written for Node.js 24.18.0 (Active LTS), npm 10+, TypeScript 5.6+, Express 5, Fastify 5, and NestJS 11.