npm run pass arguments (with & without --) – Complete Guide + Examples

Struggling to pass arguments to npm scripts correctly?

This guide shows exactly how to use npm run with and without --, including real examples, common mistakes, and how arguments are handled inside Node.js. Quickly find the right approach using the cheat sheet below.

If you're new to Node.js scripting, you can also check get started with Node.js

Quick Cheat Sheet: npm run pass arguments

When to use -- vs without --

• Use -- when passing arguments to npm scripts (recommended)
• Use environment variables when configuring runtime settings
• Avoid mixing both unless required

How arguments are received inside Node.js

• --port=3000 → available as process.env.npm_config_port
• CLI args → available via process.argv
• Environment variables → available via process.env.PORT

1. npm run pass arguments using --

The most common way to pass arguments to npm scripts is using the double dash (--). This ensures arguments are forwarded correctly to your Node.js script.

npm run dev -- --port=3000

You can also pass multiple arguments:

npm run dev -- --env=prod --debug=true

Common mistakes to avoid:

• Forgetting the second -- → arguments won't reach your script
• Writing npm run dev --port=3000 → npm treats it as its own argument
• Mixing CLI args and environment variables incorrectly

2. npm run pass arguments without -- (Environment variables)

You can pass arguments without -- using environment variables. This approach is useful for runtime configuration.

PORT=3000 npm run dev

However, this behaves differently across platforms:

• Linux/macOS:

PORT=3000 npm run dev

• Windows (CMD):

set PORT=3000 && npm run dev

This method is better when:

• You want global environment configuration
• You are integrating with CI/CD pipelines
• You are already using environment variables in your app

To understand how Node.js reads environment variables, refer to read environment variables in Node.js

3. Access npm script arguments inside Node.js

Once arguments are passed, the next step is accessing them correctly inside your script.

When using --port=3000, npm exposes it as:

process.env.npm_config_port

Example:

const port = process.env.npm_config_port || 3000;

Alternatively, you can use direct CLI arguments:

process.argv

Which method should you use?

• Use process.env.npm_config_* → when using npm run --
• Use process.argv → when running Node directly
• Use process.env.PORT → when using environment variables

4. package.json script patterns

In real projects, npm script arguments are often combined with dynamic values and reusable patterns inside package.json.

Passing dynamic values:

"scripts": {
  "start": "node index.js"
}

npm run start -- --port=4000

Using placeholders and chaining scripts:

"scripts": {
  "build": "node build.js",
  "start": "node server.js",
  "dev": "npm run build && npm run start"
}

For running multiple scripts with arguments (useful in larger projects):

npm-run-all --parallel start:* -- --env=prod

This is especially useful when managing multiple services or microservices using npm scripts.

5. Advanced use cases

npm run arguments are commonly used in advanced workflows like environment switching, build tools, and shell integration.

Running scripts with different environments:

npm run dev -- --env=development
npm run dev -- --env=production

Passing arguments to build tools (like webpack or vite):

npm run build -- --mode=production

Combining npm scripts with shell commands:

"scripts": {
  "clean": "rm -rf dist",
  "build": "npm run clean && node build.js"
}

You can also combine environment variables and arguments:

PORT=3000 npm run dev -- --debug=true

Common Errors and Fixes

Arguments not working without --:

• Ensure you are using npm run script -- --arg=value
• Without --, npm may not forward arguments to your script

npm ignoring passed values:

• Check if you're using process.env.npm_config_*
• Ensure argument names match exactly

Undefined values inside script:

• Validate using console.log(process.env)
• Use fallback values:

const port = process.env.npm_config_port || 3000;

If you're debugging Node.js scripts, refer to node.js debugging tips

Conclusion

Passing arguments to npm scripts is essential for building flexible and reusable Node.js workflows.

Use -- for standard argument passing, environment variables for configuration, and choose the right method (process.env or process.argv) based on your use case.

Official Documentation

• npm run-script official documentation
• Node.js process object documentation
• npm-run-all documentation