How to create and run Scripts in NPM

NPM scripts are aliases for terminal command sequences that we can define to run them conveniently ourselves or future collaborators on our project.

Using scripts is very common. In fact, it is quite normal to have several scripts in any project. This way, instead of remembering and executing individual commands, it’s as convenient as using the script.

Additionally, it has the important advantage of ensuring that all team members use the same commands. Or, if it’s open source code, they know how to execute the defined actions.

How to use NPM scripts

Scripts are defined in the package.json file of our project. You can create and customize your own NPM Scripts according to the needs of your project.

Creating a script

To create a custom script in NPM, we must define it in the "scripts" section of our package.json file.

Each script has a unique name and is defined using the format "name": "command". For example:

"scripts": {
  "launch_notepad": "notepad"
}

With this script on Windows, we would launch Notepad (not that it’s particularly useful, but for the example, it makes sense 😃).

Running an NPM Script

Then, simply type the command npm run followed by the name of the script you want to execute:

npm run launch_notepad

In the case of our simple command example, the name would be launch_notepad.

Passing arguments to custom scripts

In some cases, we may need to pass arguments to our scripts. It’s not very common, but it is possible.

You can pass parameters to your NPM Scripts by adding two dashes followed by the arguments after the script name.

npm run notepad -- my_text_file.txt

In our example, the Script would launch Notepad and pass my_text_file.txt as a parameter. Thus, Notepad would open with this file open (which again, is not particularly useful, but serves as an example).

More realistic examples could be, for instance, running the setup script passing a configuration argument like this:

npm run setup -- --config=production

Pre and Post Scripts

NPM offers the possibility to run scripts before and after a specific script. Use the following names for pre and post scripts:

"scripts": {
	"prestart": "echo 'Before starting'",
	"start": "echo 'Start'",
	"poststart": "echo 'After starting'",
}

When running the command npm run start, the scripts prestart, start, and poststart will automatically be executed in that order.

Running scripts in sequence

Sometimes, we may need to run several scripts in sequence (one after the other). To achieve this, we can use the && operator in the command line. For example:

npm run build && npm run test

In the previous command, the script1 will execute and, if it finishes successfully, the script2 will then run.

This is useful, for example, if we want to create commands that launch other tasks in order.

"scripts": {
  "launch": "npm run check && npm run build",
  "check": "echo 'Check'",  
  "build": "echo 'Build'",
}

In this case, the launch Script would execute the check Script and then the Build Script. In the example, these two scripts only display text to the console. But in a real project, they would contain our logic.