Passing command line arguments to npm script

In this tutorial, we will see how to pass command line arguments to the npm script.

Passing Arguments to npm Scripts Effectively (npm 2 and newer)

npm, a tool for Node.js, lets you run tasks using scripts in a file called package.json. Since npm v2, you can pass extra instructions, or arguments, to these scripts. This helps customize how they work without changing the code directly, giving you more control over your Node.js projects.

Syntax for Passing Arguments

The syntax for passing arguments to npm scripts follows this structure.

npm run <command> [-- <args>]

The -- separator is crucial. It differentiates between parameters for the npm command and parameters for your script. This is a standard convention across various command-line tools.

Practical Examples

Consider a package.json file with the following scripts.

"scripts": {
    "grunt": "grunt",
    "server": "node server.js"
}

Now, let’s explore how to pass arguments to these scripts.

Passing arguments to grunt.

npm run grunt -- task:target  # Invokes `grunt task:target`

Passing arguments to server.

npm run server -- --port=1337 # Invokes `node server.js --port=1337`

Note on Parameter Prefixes

If your parameter doesn’t start with - or --, the -- separator isn’t necessary, but it’s good practice to include it for clarity.

Example

npm run grunt task:target     # Invokes `grunt task:target`

Also correctly invokes grunt task:target.

Understanding Parameter Behavior

The handling of parameters starting with - or -- is different. These are interpreted as options for npm itself and won’t be passed to your script, leading to potentially unexpected behavior. Here’s how different commands behave.

npm run test foobar      # ['node', 'test.js', 'foobar']
npm run test -foobar     # ['node', 'test.js']
npm run test --foobar    # ['node', 'test.js']
npm run test -- foobar   # ['node', 'test.js', 'foobar']
npm run test -- -foobar  # ['node', 'test.js', '-foobar']
npm run test -- --foobar # ['node', 'test.js', '--foobar']

Special Case with npm Built-in Parameters

Using a parameter that npm itself recognizes can result in different behavior.

Example

This is interpreted as npm --help test.

Passing arguments to npm scripts with dynamic port configuration

Suppose you want to run a Node.js application on a specific port, such as 8080, using npm start. You can achieve this without any modifications to script.js or other configuration files.

Setting Up the package.json

First, modify the "scripts" section in your package.json file as follows.

"scripts": {
    "start": "node ./script.js server $PORT"
}

This setup utilizes an environment variable $PORT in the start script.

Executing the Script with a Custom Port

To run your application on port 8080, use the following command in your terminal (assuming you’re using bash).

$ PORT=8080 npm start

This command sets the PORT environment variable to 8080 just for the duration of the npm start command.

Accessing Custom Environment Variables in npm Scripts

This technique is useful for Node.js developers who need to configure their scripts dynamically via the command line.

Modify package.json

In your package.json file, define a script that points to a JavaScript file.

"scripts": {
    "cool": "./cool.js"
}

Create the JavaScript File

In cool.js, you can access environment variables set through npm. The code might look like below.

console.log({ myVar: process.env.npm_config_myVar });

This script will log an object containing the value of myVar.

Using the Command Line Interface (CLI)

To run the script with a custom variable, use the following command.

npm --myVar=something run-script cool

This command sets the custom environment variable myVar to "something" for the duration of the script execution.