minimist

Minimist is the argument-parsing engine originally extracted from optimist, stripped down to just the core logic for converting an array of command-line arguments into a structured object. It handles the full range of common argv patterns — long flags (--foo=bar), short flags bundled together (-abc), negation (--no-foo), boolean and string coercion, aliases, and defaults — with zero runtime dependencies.

Because it does one job well, minimist has become a foundational parsing layer underneath a large share of the Node.js CLI ecosystem, used directly or wrapped by higher-level libraries. Its small, synchronous API makes it easy to drop into any script that needs to read process.argv without pulling in a full CLI framework.

What You Get

• A single exported function that takes (args, opts) and returns a populated argv object
• Support for long (--foo=bar), short (-f bar), and bundled short flags (-abc)
• Boolean negation via --no-foo and explicit opts.boolean coercion
• Alias resolution so multiple flag names resolve to the same value
• Dotted-key expansion (--foo.bar=x) into nested objects
• Defaults, stopEarly, and -- passthrough handling for everything after a literal --

Common Use Cases

• Parsing options in a small standalone Node.js CLI script
• Acting as the low-level argv tokenizer underneath a higher-level CLI framework
• Accepting flags like --watch or --env=production in internal build/test tooling
• Quick prototyping of one-off Node.js scripts that need argument parsing without ceremony

Under The Hood

Architecture

Minimist is a single-file, monolithic module (index.js, ~270 lines) with no internal layering — one exported function closes over local state (flags, aliases, defaults) and mutates a local argv object while iterating the input array once. There’s no plugin system or injectable strategy; every behavior is configured through the single opts object passed at the one call site, and the dense character-by-character short-flag parsing loop is the single path all bundled -abc-style input flows through, meaning any change to it ripples across every consumer.

Tech Stack

The package has zero runtime dependencies and targets Node >= 0.4, using only plain ES5-style JavaScript ('use strict', var, function declarations) for maximum compatibility. Development tooling includes tape for tests, nyc for coverage, eslint with the @ljharb/eslint-config preset, auto-changelog for release notes, and safe-publish-latest/in-publish guards around the publish lifecycle — all as devDependencies only.

Code Quality

Tests are extensive relative to the module’s size: sixteen dedicated test files under test/ cover short flags, long flags, arrays, booleans, dotted keys, whitespace, unknown-argument callbacks, and prototype-pollution safety (proto.js), all run through tape. Coverage is measured via nyc with configured thresholds (86% lines, 76% branches) though hard enforcement is disabled. Linting runs as a pretest step and CI (GitHub Actions) exercises multiple Node version ranges plus a posttest npm audit. Error handling is implicit rather than explicit — malformed input is coerced rather than throwing — which fits a permissive CLI-parsing utility, and there are no TypeScript types in the repository itself.

API Design The public surface is a single default export, parseArgs(args, opts), returning a plain object — about as low-boilerplate as argument parsing gets: require('minimist')(process.argv.slice(2)) is a complete integration. Configuration is one flat opts object (string, boolean, alias, default, stopEarly, '--'), which keeps the common path simple, though discovering less obvious behaviors like dotted-key nesting or the unknown callback requires reading the README closely, since it’s the only documentation source — there are no in-repo JSDoc or .d.ts annotations.