{"id":12824,"library":"args-parser","title":"Minimalist Node.js Argument Parser","description":"args-parser is a minimalist command-line argument parser designed specifically for Node.js environments. Its current stable version is 1.3.0, and it maintains a relatively slow release cadence, reflecting its stable and focused scope. The library directly processes an array of strings, typically `process.argv`, transforming them into a straightforward JavaScript object. Flags are represented as boolean `true` values, while key-value pairs (e.g., `--key=value`) are parsed into string or numeric values accordingly. Its key differentiators include an extremely small footprint and a simple, direct API, making it an ideal choice for basic script argument handling where the overhead or extensive features of more complex parsers like `yargs` or `commander.js` are not required. It explicitly avoids advanced features such as extensive type coercion, positional arguments, aliases, or integrated help generation, focusing solely on efficient, no-frills flag and option parsing.","status":"maintenance","version":"1.3.0","language":"javascript","source_language":"en","source_url":"https://github.com/eveningkid/args-parser","tags":["javascript","args","parser","args-parser","arguments"],"install":[{"cmd":"npm install args-parser","lang":"bash","label":"npm"},{"cmd":"yarn add args-parser","lang":"bash","label":"yarn"},{"cmd":"pnpm add args-parser","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The package is CommonJS-only and exports the parsing function directly as its default. It expects `process.argv` or a similar string array as its argument.","wrong":"import argsParser from 'args-parser';","symbol":"argsParser","correct":"const argsParser = require('args-parser');\nconst args = argsParser(process.argv);"},{"note":"The module's default export is the parsing function itself. There are no named exports available.","wrong":"const { parseArgs } = require('args-parser');","symbol":"parseArgs","correct":"const parseArgs = require('args-parser');\nconst myArgs = parseArgs(['--config=dev', '-v']);"},{"note":"As of v1.3.0, `args-parser` does not ship with TypeScript type definitions. Users will need to declare types manually or rely on 'any'.","symbol":"Type Definition","correct":"// No specific type definitions are shipped with the package, infer 'any' or define locally."}],"quickstart":{"code":"const argsParser = require('args-parser');\n\n// Simulate command-line arguments\nconst simulatedArgs = [\n  'node',\n  'script.js',\n  '--careful',\n  '-dangerous',\n  '--tomatoes=3',\n  '--tonight',\n  '--key=ek==',\n  '--rate=4.5'\n];\n\n// In a real script, you'd use: const args = argsParser(process.argv);\nconst args = argsParser(simulatedArgs);\n\nconsole.log('Parsed Arguments:');\nconsole.log(args);\n\nif (args.careful) {\n  console.log('Careful flag is set!');\n}\n\nif (args.tomatoes) {\n  console.log(`Number of tomatoes: ${args.tomatoes}`); // Note: args.tomatoes is a string '3'\n}\n\nif (args.rate) {\n    console.log(`Rate value: ${parseFloat(args.rate)}`); // Type coercion often needed\n}\n\n// Example of accessing an argument that might not exist\nif (args.verbose === undefined) {\n  console.log('Verbose flag was not provided.');\n}","lang":"javascript","description":"Demonstrates how to install and use `args-parser` to parse simulated command-line arguments, showing the resulting object structure and basic access patterns for flags and key-value options."},"warnings":[{"fix":"For ESM projects, use `const argsParser = require('args-parser');` within a wrapper that uses `createRequire` from the `module` package, or use a tool like Webpack/Rollup for bundling and CJS-to-ESM conversion.","message":"The package is CommonJS-only and does not natively support ES Modules (`import`/`export`) syntax. Attempting to import it directly in an ESM context will result in a runtime error.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"For applications requiring advanced CLI features, consider alternative libraries like `yargs`, `commander.js`, or `minimist` combined with custom logic for validation and defaults. If sticking with `args-parser`, implement all validation and defaults manually after parsing.","message":"`args-parser` provides a very basic parsing mechanism. It does not include features commonly found in more robust CLI libraries, such as type validation (all values from `--key=value` are strings), default values, aliases, positional arguments, subcommands, or automatic help message generation.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Always check for `if (args.flag)` instead of `if (args.flag === true)`. Implement default values manually using the logical OR operator or nullish coalescing: `const myFlag = args.flag ?? false;`.","message":"Arguments without an equals sign (`--flag`) are always parsed as `true` if present, and `undefined` if absent. There is no direct way to specify `false` for a flag from the command line, and `args-parser` does not provide an option to set default values for missing flags.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Always explicitly convert string values to the desired type after parsing, for example: `const count = parseInt(args.count, 10);` or `const ratio = parseFloat(args.ratio);`.","message":"Values parsed from `--key=value` are always treated as strings. While numbers might appear to parse correctly, they remain string types and require explicit type coercion (e.g., `parseInt`, `parseFloat`) if arithmetic operations or strict type checks are needed.","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":"Call the required module directly with the arguments array: `const args = require('args-parser')(process.argv);`","cause":"The `require('args-parser')` call returns the parsing function directly, but the user is attempting to call a method on it (e.g., `argsParser.parse()`).","error":"TypeError: argsParser is not a function"},{"fix":"If running Node.js v12.20.0+, you can use `const { createRequire } = require('module'); const requireCjs = createRequire(import.meta.url); const argsParser = requireCjs('args-parser');`. Otherwise, convert your file to CommonJS or use a bundler.","cause":"Attempting to use `require()` in a JavaScript file that is being interpreted as an ES Module (e.g., due to `\"type\": \"module\"` in `package.json` or a `.mjs` extension).","error":"ReferenceError: require is not defined in ES module scope"},{"fix":"Always check for the existence of the property or provide a fallback value: `const myFlag = args.myFlag ?? false;` or `if (args.myFlag) { /* ... */ }`.","cause":"The user is attempting to access a property (flag or option) that was not provided in the command-line arguments, and expects it to be `false` or some default, but `args-parser` returns `undefined` for missing arguments.","error":"TypeError: Cannot read properties of undefined (reading 'myFlag')"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null}