node-args

library2.1.8jsnpmunverified

node-args is a minimalistic command-line argument parser for Node.js, currently at version 2.1.8. It distinguishes itself by providing a no-configuration, no-options approach to parsing `process.argv`. Unlike more feature-rich alternatives like `commander` or `yargs`, `node-args` automatically processes flags (`-s`, `--long`) and values, returning a simple object without requiring schema definitions or explicit parsing function calls. Its core design principle is simplicity, offering only the bare essentials for argument processing. The library appears to be in a maintenance state, having a stable API that has not changed significantly, and development focuses on stability rather than new features, aligning with its 'minimalistic' promise. It ships with TypeScript types, enhancing developer experience for typed projects.

devops

npm install node-args

github ↗package ↗

INSTALL

IMPORT

SIG · NODE-ARGS

node-args

devopsjavascriptv2.1.8

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

parsedArgs

✓ const parsedArgs = require('node-args');

✗ const args = require('node-args')();

The `node-args` module exports the already-parsed arguments object directly upon `require()`, not a function to be invoked.

parsedArgs

✓ import parsedArgs from 'node-args';

✗ import { parsedArgs } from 'node-args';

For ESM usage, `node-args` is likely a default export (or resolves as such via TypeScript's `esModuleInterop`). Be aware that this behavior (parsing on import/require) means `process.argv` is consumed at module load time.

ArgsObject

✓ import type { ArgsObject } from 'node-args';

While `node-args` ships TypeScript types, the exact type for the parsed object may vary. `ArgsObject` is a common convention, but check the `.d.ts` file for precise type names if issues arise.

Demonstrates importing `node-args` and accessing the automatically parsed command-line arguments. Note how the module directly exports the parsed object rather than a parsing function.

import parsedArgs from 'node-args'; // Or: const parsedArgs = require('node-args'); // To simulate command-line arguments for testing, you might modify process.argv // However, node-args parses process.argv AT THE TIME IT IS REQUIRED/IMPORTED. // To demonstrate, we'll run a script with arguments. // In a file named `my-script.ts` (or `.js`): // console.log(parsedArgs); // To run from the terminal: // npx ts-node my-script.ts -t -ab=2 -c false -p no some additional data 2 --argsis awesome --another=1 // Expected output would be similar to: /* { _: ['node', '/path/to/my-script.ts', 'some', 'additional', 'data', 2], t: true, a: 2, b: 2, c: false, p: 'no', argsis: 'awesome', another: 1 } */ // For a runnable example within the registry format: // We cannot dynamically alter process.argv for a quickstart that runs in a sandbox, // but this code illustrates the usage if run from the command line. // In a standalone script: const actualParsedArgs = require('node-args'); console.log(actualParsedArgs); /* Example of how you would run this: node -r ts-node/register your-script.ts -t -ab=2 -c false -p no some additional data 2 --argsis awesome --another=1 */

Debug

Known issues

gotcha`node-args` parses `process.argv` immediately upon `require()` or `import`. This means that any modifications to `process.argv` after the module is loaded will not be reflected in the parsed arguments. For testing or dynamic argument scenarios, this behavior can be a significant footgun.

fix

Ensure `node-args` is imported/required only after `process.argv` has reached its final state for your application, or use libraries that expose an explicit parsing function, such as `commander` or Node.js's built-in `util.parseArgs` (Node 18.3.0+ for experimental, Node 20+ for stable).

affects: >=1.0.0

gotchaThe library offers no configuration or schema for argument definition, validation, or type enforcement. Argument values are heuristically parsed (e.g., 'false' becomes boolean `false`, '2' becomes number `2`). This can lead to unexpected type conversions or incorrect assumptions about input.

fix

For applications requiring strict argument typing, validation, or complex schemas, consider using libraries like `yargs`, `commander`, or `minimist` which provide these capabilities.

affects: >=1.0.0

gotcha`node-args` is designed for basic flat argument parsing and does not support advanced CLI patterns such as subcommands (e.g., `git commit`), command-specific options, or generating help messages. It provides a simple key-value object of parsed arguments.

fix

If your application requires subcommands, contextual help, or more structured CLI interfaces, libraries like `commander.js` or `yargs` are more appropriate choices.

affects: >=1.0.0

gotchaThe `_` (underscore) property in the parsed object contains an array of non-flag arguments, including the Node.js executable path (`process.argv[0]`) and the script file path (`process.argv[1]`), followed by any additional non-flag arguments. Developers often expect `_` to contain only unparsed application-specific arguments.

fix

Access application-specific non-flag arguments by slicing the `_` array (e.g., `parsedArgs._.slice(2)`). Alternatively, use libraries that automatically omit the first two elements from the `_` array.

affects: >=1.0.0

Errors

Common errors & fixes

SyntaxError: Cannot use import statement outside a module

Attempting to use ES module `import` syntax in a CommonJS module file (e.g., a `.js` file without `"type": "module"` in `package.json`, or an older Node.js environment).

fix

Ensure your project is configured for ESM by adding `"type": "module"` to your `package.json` or explicitly naming your file with a `.mjs` extension. Alternatively, use CommonJS `require()` syntax: `const parsedArgs = require('node-args');`

TypeError: require(...) is not a function

The `node-args` module directly exports the parsed arguments object, not a function to be called. Users often try to invoke it like a function: `require('node-args')()`.

fix

Access the parsed arguments directly without calling it: `const parsedArgs = require('node-args');`

My command-line arguments are not being parsed correctly when I change `process.argv` dynamically.

`node-args` parses `process.argv` at the moment it is loaded (via `require` or `import`), not when explicitly invoked. Any changes to `process.argv` *after* `node-args` has been loaded will be ignored.

fix

Ensure `node-args` is imported/required only after `process.argv` has been fully set up (e.g., in the main script file after `process.argv` is modified). For more flexible parsing, use a library that provides an explicit parsing function like `commander.js` or `yargs`.

Upgrade

Version history

2.1.8latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/christiansandor/args ↗

packagehttps://www.npmjs.com/package/node-args ↗