node-args

Common errors

• SyntaxError: Cannot use import statement outside a module

  cause 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

  cause 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.

  cause `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`.

Warnings

• 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).
• gotcha The 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.
• 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.
• gotcha The `_` (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.

Install

• npm install node-args npm
• yarn add node-args yarn
• pnpm add node-args pnpm

Imports

• parsedArgs
  wrong:

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

  correct:

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

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

  import { parsedArgs } from 'node-args';

  correct:

  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.

Quickstart

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
*/