yargs-parser

yargs-parser is the low-level argument-parsing engine that yargs itself is built on, extracted as a standalone package so other CLI tools can use the same parsing behavior without pulling in yargs’ full command/help/validation framework. Given a string or array of process arguments, it turns flags, aliases, negations, and positional arguments into a plain object, with dozens of configurable behaviors: camel-case expansion, dot-notation nesting, array coercion, number parsing, environment-variable prefixes, and config-file loading.

Its descendance from optimist and minimist, plus over a decade of edge-case bug reports routed through yargs, makes it one of the most battle-tested argument parsers in the npm ecosystem, and it is depended on transitively by an enormous share of Node.js CLI tooling.

What You Get

• A single parser(args, opts) function that turns CLI args (string or array) into a plain key/value object
• A .detailed() variant that also returns inferred aliases, defaulted keys, and any parsing error
• Extensive opts hints: alias, array, boolean, string, number, coerce, narg, default, envPrefix, config/configObjects
• Over 15 toggleable configuration flags (camel-case expansion, dot-notation, boolean-negation, greedy-arrays, halt-at-non-option, and more) for fine-tuning parser behavior
• First-class ESM, CommonJS, browser, and Deno entry points, so it works the same across runtimes
• TypeScript type definitions covering the parser API and its options

Common Use Cases

• Building a custom CLI tool’s argument parsing without adopting yargs’ full command-and-help framework
• Parsing a raw argument string (rather than process.argv) for testing or programmatic invocation
• Loading configuration from both CLI flags and a config file, merging them via opts.config/configObjects
• Fine-tuning edge-case parsing behavior (e.g. disabling camel-case expansion or greedy arrays) for compatibility with an existing CLI’s argument conventions

Under The Hood

Architecture - The package is a small, focused module: lib/index.ts is the public entry point that wraps the core parsing engine in lib/yargs-parser.ts (over 1,100 lines implementing the tokenizer-driven state machine that walks each argument, resolves aliases, applies type coercion, and builds the result object), with lib/tokenize-arg-string.ts handling the string-to-array splitting and lib/string-utils.ts providing camel-case/dash-case helpers. lib/yargs-parser-types.ts centralizes the TypeScript option/type definitions so the public API surface is defined once and shared across the CJS, ESM, and browser builds.

Tech Stack - Written in TypeScript, compiled to a build/ output via tsc, distributed as an ESM package ("type": "module") with a dedicated browser.js entry and a deno.ts entry for Deno support, so the same parsing logic ships across four distinct runtime targets from one source tree. Linting uses Google’s gts, and coverage/testing run through mocha with c8 for coverage reporting rather than a newer test runner like Vitest.

Code Quality - Test coverage is extensive relative to the package’s size: dedicated suites exist for browser behavior, Deno behavior, TypeScript typing correctness, and the core parser itself (test/yargs-parser.mjs), reflecting years of accumulated edge-case regression tests inherited from yargs’ history. The core parser file is large and dense (over 1,100 lines) because argument parsing has a large number of interacting configuration flags, but responsibilities are still split across separate files for tokenizing, string-casing, and type definitions rather than being a single monolith.

API Design - The primary API is a single function call (parser(args, opts)) that returns a plain object, which is about as low-boilerplate as an argument parser can be, and the opts.configuration object exposes fine-grained toggles (documented individually with before/after examples in the README) rather than forcing consumers into one fixed parsing style. The tradeoff is a large number of configuration keys to learn if you need non-default behavior, but the defaults are sensible enough that most consumers never need to touch configuration at all.