NPM scripts

NPM scripts are an indispensable part of Node.js projects. Defined in the scripts field of package.json, they simplify development workflows, automate tasks, and integrate toolchains. Whether it's starting a server, running tests, or building bundles, NPM scripts can accomplish complex operations with concise commands.

Basic Usage of NPM Scripts

In package.json, the scripts field is used to define executable commands. For example:

{
  "scripts": {
    "start": "node app.js",
    "test": "jest"
  }
}

Scripts are executed via npm run <script-name>. For instance, npm run test runs Jest tests. Some scripts (like start and test) support shorthand, allowing direct execution with npm start or npm test.

Script Composition and Hooks

NPM scripts support chaining multiple commands with && or leveraging pre and post hooks to automatically execute pre/post operations:

{
  "scripts": {
    "prebuild": "rimraf dist",
    "build": "webpack --mode production",
    "postbuild": "node notify.js"
  }
}

When running npm run build, prebuild, build, and postbuild are executed sequentially.

Environment Variables and Argument Passing

Scripts can access environment variables via process.env and support passing arguments using --:

{
  "scripts": {
    "serve": "webpack serve --port"
  }
}

Executing npm run serve -- 8080 passes 8080 as an argument to the command.

Cross-Platform Compatibility

Tools like cross-env resolve differences in environment variable settings across operating systems:

{
  "scripts": {
    "start": "cross-env NODE_ENV=production node app.js"
  }
}

Modularizing Complex Scripts

For complex logic, scripts can be split into separate JS files and invoked via node:

{
  "scripts": {
    "deploy": "node scripts/deploy.js"
  }
}

Example deploy.js content:

const { execSync } = require('child_process');
execSync('git push origin master', { stdio: 'inherit' });

Integration with Other Tools

NPM scripts are often combined with build tools (e.g., Webpack) and testing frameworks (e.g., Mocha):

{
  "scripts": {
    "watch": "webpack --watch",
    "coverage": "nyc mocha"
  }
}

Performance Optimization Tips

Use npm-run-all to run scripts in parallel for improved efficiency:

{
  "scripts": {
    "lint:all": "npm-run-all lint:*",
    "lint:js": "eslint .",
    "lint:css": "stylelint '**/*.css'"
  }
}

Debugging and Error Handling

Add --silent to reduce log noise or use nodemon for automatic restarts on file changes:

{
  "scripts": {
    "dev": "nodemon --inspect app.js"
  }
}

Real-World Project Examples

A complete project might include scripts like these:

{
  "scripts": {
    "start": "node server.js",
    "dev": "nodemon server.js",
    "build": "webpack --config webpack.prod.js",
    "test": "jest --coverage",
    "precommit": "lint-staged",
    "docker:build": "docker build -t my-app .",
    "docker:run": "docker run -p 3000:3000 my-app"
  }
}