Automate Tasks With npm Scripts

In npm, scripts are a set of built-in and custom commands used to automate the execution of repetitive project-related tasks, such as starting the web server, bundling the application, linting the code, running automated tests, and so on.

Define and execute scripts

Define a script

Scripts are defined under the scripts property of the package.json file using the following syntax:

{
  "scripts": {
    "<name>": "<command>"
  }
}

Where:

• <name> is the name of the script (e.g. build, lint).
• <command> is the shell command to be executed when invoking the script.

Execute a script

To run an arbitrary script, you can use the npm run command:

$ npm run <script>

Where <script> is the name of a script defined in the package.json file.

Notes:

• To pass flags and arguments to the command executed by the script, you can use this syntax:

  $ npm run <script> - [<flag> ...] [<argument> ...]
  

• By default, npm scripts are always run with the effective UID and GID of the working directory owner.

Example

Let's consider this script named dev that is typically used to start a Node server in development mode:

{
  "scripts": {
    "dev": "NODE_ENV=development node index.js"
  }
}

To execute it, you can run this npm run command:

$ npm run dev

Pre and post scripts

In npm, pre and post scripts are a special type of scripts that allow you to define actions that should be automatically executed by npm before and/or after a particular script runs.

These are often used to perform setup or cleanup tasks in your project.

They are defined using the following syntax:

{
  "scripts": {
    "pre<script>": "<command>",
    "<script>": "<command>",
    "post<script>": "<command>"
  }
}

Where:

• <script> is the name of the script.
• <command> is the command to be executed by the script.

Example

Let's consider the following package.json file:

{
  "devDependencies": {
    "jest": "^29.0.3",
  },
  "scripts": {
    "pretest": "./setup_database.sh",
    "test": "jest",
    "posttest": "./cleanup_database.sh"
  }
}

When running the following command:

$ npm run test

npm will in order:

1. Execute the setup_database.sh shell script in charge of inserting dummy records in the database.
2. Execute the jest binary located in the node_modules folder in charge of running the *.test.js files present in the project's directory.
3. Execute the cleanup_database.sh shell script in charge of cleaning up the dummy records from the database.

The execution context

npm scripts executed using the npm run command run in an environment where many pieces of information are made available regarding the setup of npm and the current state of the process.

The PATH environment variable

The node_modules/.bin path is added to the pre-existing shell's PATH environment variable, allowing you to directly invoke any binaries provided by locally-installed dependencies.

Example

For example, the following dev script uses the nodemon binary located in node_modules/.bin/nodemon.

{
  "script": {
    "dev": "nodemon app.js"
  }
}

The package.json file variables

The fields present in the package.json file are added to the environment and accessible through the global process.env object.

These variables are prefixed with the npm_package_ expression.

Example

For example, considering the following package.json file:

{
  "name": "hello-world",
  "version": "1.0.0",
  "scripts": {
    "dev": "node index.js"
  }
}

And the following index.js script:

console.log(`${process.env.npm_package_name} ${process.env.npm_package_version}`);

Running the following command will output the name and version number of the package:

$ npm run dev

> hello world@1.0.0 dev
> node index.js

hello world 1.0.0

Summary

Here's a summary of what you've learned in this lesson:

• Scripts are defined under the scripts property of the package.json file using the following syntax.
• The "<script>": "<command>" syntax is used to define a script.
• The npm run <script> command is used to execute a script defined in the package.json file.
• The pre and post scripts are automatically executed before and/or after a particular script runs.
• Upon script execution, the node_modules/.bin is added to the PATH environment variable.
• Upon script execution, the variables of the package.json files are added to the environment with the npm_package_ prefix.
• A script always runs with the effective UID and GID of the working directory owner.