{"id":14728,"library":"node-args","title":"node-args","description":"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.","status":"maintenance","version":"2.1.8","language":"javascript","source_language":"en","source_url":"https://github.com/christiansandor/args","tags":["javascript","node-args","arg","argv","args","argument","arguments","parameter","parameters","typescript"],"install":[{"cmd":"npm install node-args","lang":"bash","label":"npm"},{"cmd":"yarn add node-args","lang":"bash","label":"yarn"},{"cmd":"pnpm add node-args","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The `node-args` module exports the already-parsed arguments object directly upon `require()`, not a function to be invoked.","wrong":"const args = require('node-args')();","symbol":"parsedArgs","correct":"const parsedArgs = require('node-args');"},{"note":"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.","wrong":"import { parsedArgs } from 'node-args';","symbol":"parsedArgs","correct":"import parsedArgs from 'node-args';"},{"note":"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.","symbol":"ArgsObject","correct":"import type { ArgsObject } from 'node-args';"}],"quickstart":{"code":"import parsedArgs from 'node-args'; // Or: const parsedArgs = require('node-args');\n\n// To simulate command-line arguments for testing, you might modify process.argv\n// However, node-args parses process.argv AT THE TIME IT IS REQUIRED/IMPORTED.\n// To demonstrate, we'll run a script with arguments.\n\n// In a file named `my-script.ts` (or `.js`):\n// console.log(parsedArgs);\n\n// To run from the terminal:\n// npx ts-node my-script.ts -t -ab=2 -c false -p no some additional data 2 --argsis awesome --another=1\n\n// Expected output would be similar to:\n/*\n{\n    _: ['node', '/path/to/my-script.ts', 'some', 'additional', 'data', 2],\n    t: true,\n    a: 2,\n    b: 2,\n    c: false,\n    p: 'no',\n    argsis: 'awesome',\n    another: 1\n}\n*/\n\n// For a runnable example within the registry format:\n// We cannot dynamically alter process.argv for a quickstart that runs in a sandbox, \n// but this code illustrates the usage if run from the command line.\n// In a standalone script:\n\nconst actualParsedArgs = require('node-args');\nconsole.log(actualParsedArgs);\n\n/* Example of how you would run this: \n   node -r ts-node/register your-script.ts -t -ab=2 -c false -p no some additional data 2 --argsis awesome --another=1\n*/","lang":"typescript","description":"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."},"warnings":[{"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).","message":"`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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"For applications requiring strict argument typing, validation, or complex schemas, consider using libraries like `yargs`, `commander`, or `minimist` which provide these capabilities.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"If your application requires subcommands, contextual help, or more structured CLI interfaces, libraries like `commander.js` or `yargs` are more appropriate choices.","message":"`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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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');`","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).","error":"SyntaxError: Cannot use import statement outside a module"},{"fix":"Access the parsed arguments directly without calling it: `const parsedArgs = require('node-args');`","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')()`.","error":"TypeError: require(...) is not a function"},{"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`.","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.","error":"My command-line arguments are not being parsed correctly when I change `process.argv` dynamically."}],"ecosystem":"npm"}