Mastering npm Script Arguments: When and Why to Use "--"

How npm scripts work

In a package.json file, the scripts section defines shortcuts for commands. For example, the test script may be configured as:

{
  "scripts": {
    "test": "jest",
    ...
  }
}

Running npm test actually invokes the jest command, while npm run dev runs next dev, and so on.

Two ways to pass arguments to npm scripts

When you want to pass arguments to the underlying script (e.g., a specific test file to jest), you can either place the arguments directly after the npm command or separate them with a double dash ( --). The difference lies in how npm parses the command line.

Without -- : npm’s “guess”

Executing npm test tests/contract/auth-github-callback.test.ts makes npm treat tests/contract/auth-github-callback.test.ts as an extra argument to the test script. npm forwards this argument to jest, which usually interprets it correctly and runs the specified test file.

With -- : explicit delimiter

Running npm test -- tests/contract/auth-github-callback.test.ts tells npm to stop its own argument parsing at the double dash. Everything after -- is passed verbatim to the underlying script, clearly separating npm’s options from the script’s options.

Visualizing the argument‑passing flow

Sequence diagrams illustrate the two scenarios.

Scenario 1: without --

npm receives the argument and forwards it directly to jest.

Scenario 2: with --

The double dash makes npm recognize that my-test.ts belongs to jest, not to npm itself.

Why does it sometimes work without -- ?

Many CLI tools, including jest, are tolerant: when npm encounters an unknown argument, it assumes the argument is intended for the underlying script and passes it along. This “guessing” behavior often succeeds, which is why the command may work even without the explicit delimiter.

When must you use -- ?

If a script’s own options conflict with npm’s options, the double dash becomes essential. For example, a script that accepts -v for version would clash with npm -v, which prints npm’s version.

Without -- : npm run your-script -v is interpreted as npm -v, outputting npm’s version instead of passing -v to the script.

With -- : npm run your-script -- -v tells npm to ignore -v and forward it unchanged to your-script, allowing the script to receive the intended argument.

Conclusion and best practices

Although omitting -- often works, it is strongly recommended to always include it when passing arguments to npm scripts.

Clarity : The double dash makes the intention explicit, improving readability.

Safety : It prevents accidental conflicts with npm’s own options.

Standards compliance : Using -- follows the POSIX convention for separating command‑line options from positional arguments.

In summary, whenever you need to forward arguments to an npm script, use the double dash ( --) to ensure reliable and predictable behavior.