yargs-parser

library22.0.0jsnpmunverified

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.

devops

npm install yargs-parser

github ↗package ↗

INSTALL

IMPORT

SIG · YARGS-PARSER

yargs-parser

devopsjavascriptv22.0.0

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.

default

✓ import parser from 'yargs-parser'

✗ const parser = require('yargs-parser')

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.

default

✓ import parser from 'https://deno.land/x/yargs_parser/deno.ts'

This import path is specific to Deno environments, available since v19.

Options

✓ import type { Options } from 'yargs-parser'

Import types separately for clarity in TypeScript projects. The `Options` interface defines the structure for parser configuration.

Demonstrates parsing command-line arguments using various configuration options like types, aliases, defaults, and custom coercions.

import parser from 'yargs-parser'; import process from 'node:process'; // Example 1: Parsing process arguments with various options const args = process.argv.slice(2); const argvParsed = parser(args, { string: ['name', 'city'], // Treat these keys as strings boolean: ['verbose', 'help'], // Treat these keys as booleans alias: { name: ['n'], // -n is an alias for --name verbose: ['v'], // -v is an alias for --verbose help: ['h'] // -h is an alias for --help }, default: { verbose: false, city: 'Unknown' }, // unknown-options-as-args: true // Uncomment to treat unknown options as positional arguments }); console.log('Parsed process arguments:', argvParsed); // To run: node your-script.js --name "Alice Smith" -v --city London --project Foo --bar // Example 2: Parsing a string directly with coercion and array handling const stringArgs = '--count=5 --active --tags one two three --price 10.50'; const stringParsed = parser(stringArgs, { count: ['count'], // Interpret multiple occurrences of --count as a counter (e.g., -vvv = {v:3}) boolean: ['active'], array: ['tags'], // Collect multiple --tags values into an array number: ['price'], coerce: { // Custom coercion for tags to uppercase tags: (arr) => Array.isArray(arr) ? arr.map(tag => String(tag).toUpperCase()) : [String(arr).toUpperCase()], } }); console.log('Parsed string arguments with coercion:', stringParsed);

Debug

Known issues

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

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.

affects: >=22.0.0

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

fix

Upgrade your Node.js runtime to a supported version. Refer to the `engines.node` field in the package.json for exact requirements.

affects: >=21.0.0

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

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.

affects: >=15.0.0

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

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.

affects: >=1.0.0

Errors

Common errors & fixes

ReferenceError: require is not defined

Attempting to use `require('yargs-parser')` in an ES Module context.

fix

Change your import statement to `import parser from 'yargs-parser'`.

TypeError: yargs_parser_1.default is not a function

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.

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.

Argument value is not the expected type (e.g., number parsed as string)

yargs-parser's default behavior or misconfiguration of `opts.number`, `opts.boolean`, or `opts.string` leads to incorrect type inference.

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'] }`.

Upgrade

Version history

22.0.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

17 hits · last 30 days

node

Resources

githubhttps://github.com/yargs/yargs-parser ↗

packagehttps://www.npmjs.com/package/yargs-parser ↗