{"id":15944,"library":"yargs-parser","title":"yargs-parser","description":"yargs-parser is the robust, highly configurable option parser underlying the popular yargs command-line interface library. Currently at stable version 22.0.0, it follows a release cadence tied to yargs itself, with major versions introducing breaking changes like the recent shift to ESM-first. Its key differentiators include comprehensive argument parsing capabilities, extensive configuration options for aliases, types (boolean, number, string, array), defaults, environment variable handling, and support for configuration files. It operates efficiently across various JavaScript environments, including Node.js (requiring Node.js ^20.19.0 || ^22.12.0 || >=23 as of v22), web browsers via specific builds, and Deno, making it a versatile choice for parsing CLI arguments or arbitrary strings.","status":"active","version":"22.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/yargs/yargs-parser","tags":["javascript","argument","parser","yargs","command","cli","parsing","option","args"],"install":[{"cmd":"npm install yargs-parser","lang":"bash","label":"npm"},{"cmd":"yarn add yargs-parser","lang":"bash","label":"yarn"},{"cmd":"pnpm add yargs-parser","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"Since v22.0.0, `yargs-parser` is ESM-first. Using `require()` will fail in native ESM environments or require explicit CJS setup in older Node.js.","wrong":"const parser = require('yargs-parser')","symbol":"default","correct":"import parser from 'yargs-parser'"},{"note":"This import path is specific to Deno environments, available since v19.","symbol":"default","correct":"import parser from 'https://deno.land/x/yargs_parser/deno.ts'"},{"note":"Import types separately for clarity in TypeScript projects. The `Options` interface defines the structure for parser configuration.","symbol":"Options","correct":"import type { Options } from 'yargs-parser'"}],"quickstart":{"code":"import parser from 'yargs-parser';\nimport process from 'node:process';\n\n// Example 1: Parsing process arguments with various options\nconst args = process.argv.slice(2);\nconst argvParsed = parser(args, {\n  string: ['name', 'city'], // Treat these keys as strings\n  boolean: ['verbose', 'help'], // Treat these keys as booleans\n  alias: {\n    name: ['n'], // -n is an alias for --name\n    verbose: ['v'], // -v is an alias for --verbose\n    help: ['h'] // -h is an alias for --help\n  },\n  default: {\n    verbose: false,\n    city: 'Unknown'\n  },\n  // unknown-options-as-args: true // Uncomment to treat unknown options as positional arguments\n});\n\nconsole.log('Parsed process arguments:', argvParsed);\n// To run: node your-script.js --name \"Alice Smith\" -v --city London --project Foo --bar\n\n// Example 2: Parsing a string directly with coercion and array handling\nconst stringArgs = '--count=5 --active --tags one two three --price 10.50';\nconst stringParsed = parser(stringArgs, {\n  count: ['count'], // Interpret multiple occurrences of --count as a counter (e.g., -vvv = {v:3})\n  boolean: ['active'],\n  array: ['tags'], // Collect multiple --tags values into an array\n  number: ['price'],\n  coerce: {\n    // Custom coercion for tags to uppercase\n    tags: (arr) => Array.isArray(arr) ? arr.map(tag => String(tag).toUpperCase()) : [String(arr).toUpperCase()],\n  }\n});\nconsole.log('Parsed string arguments with coercion:', stringParsed);","lang":"typescript","description":"Demonstrates parsing command-line arguments using various configuration options like types, aliases, defaults, and custom coercions."},"warnings":[{"fix":"Migrate your project to use ES Modules `import` syntax. If targeting older Node.js or strictly CommonJS, consider pinning to a version prior to 22.0.0 or configuring a build step (e.g., Babel, TypeScript) for CJS output from ESM source.","message":"yargs-parser became ESM-first in v22.0.0. This means that CommonJS `require()` statements may no longer work as expected in pure ESM Node.js projects or require explicit configuration for interoperability.","severity":"breaking","affected_versions":">=22.0.0"},{"fix":"Upgrade your Node.js runtime to a supported version. Refer to the `engines.node` field in the package.json for exact requirements.","message":"Version 21.0.0 of yargs-parser dropped official support for Node.js 10. The current minimum supported Node.js version for v22.x is ^20.19.0 || ^22.12.0 || >=23.","severity":"breaking","affected_versions":">=21.0.0"},{"fix":"If experiencing slow parsing, especially with many arguments, consider refactoring your CLI to explicitly define options rather than relying heavily on `unknown-options-as-args`. Profile your application to identify bottlenecks.","message":"Performance can degrade significantly when using the `unknown-options-as-args` configuration option, particularly with a large number of arguments or specific patterns. This was noted and addressed in patches, but users should be aware of potential impacts.","severity":"gotcha","affected_versions":">=15.0.0"},{"fix":"Ensure that any array passed to `parser()` is first converted to an array of strings, e.g., `argsArray.map(String)` or `argsArray.join(' ')` if you want to parse a single string.","message":"When providing an array of arguments, `yargs-parser` expects an array of *strings*. Passing a mixed-type array (e.g., `['--foo', 123]`) directly may lead to unexpected parsing behavior or type issues.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Change your import statement to `import parser from 'yargs-parser'`.","cause":"Attempting to use `require('yargs-parser')` in an ES Module context.","error":"ReferenceError: require is not defined"},{"fix":"Ensure your `tsconfig.json`'s `module` and `moduleResolution` settings align with your runtime environment (e.g., `\"module\": \"NodeNext\"`, `\"moduleResolution\": \"NodeNext\"` for modern Node.js ESM projects). Also, explicitly use `import parser from 'yargs-parser'` for ESM.","cause":"This often occurs in TypeScript or transpiled JavaScript when a CommonJS `require` call (which provides a default export as `exports.default`) is consumed by an ESM `import` in a way that expects a named export, or vice-versa, specifically with `yargs-parser`'s ESM-first shift.","error":"TypeError: yargs_parser_1.default is not a function"},{"fix":"Explicitly define the expected types for your arguments using the `string`, `number`, `boolean`, `array`, or `coerce` options in the `parser`'s second argument (`opts`). For example, `{ number: ['port'], string: ['host'] }`.","cause":"yargs-parser's default behavior or misconfiguration of `opts.number`, `opts.boolean`, or `opts.string` leads to incorrect type inference.","error":"Argument value is not the expected type (e.g., number parsed as string)"}],"ecosystem":"npm"}