Getopts CLI Argument Parser

Common errors

• ReferenceError: require is not defined in ES module scope

  cause Attempting to import `getopts` using CommonJS `require()` syntax in an ES module environment after upgrading to v2.3.0.
  fix Change `const getopts = require('getopts')` to `import getopts from 'getopts'` and ensure your project is configured for ESM.

• TypeError: getopts is not a function

  cause This error can occur if you are trying to use a CommonJS `require()` for an ESM package, or if you are incorrectly trying to destructure a default export in a CommonJS context after v2.3.0.
  fix For ESM, use `import getopts from 'getopts'`. For CommonJS, either stick to v2.2.x or use dynamic import: `(await import('getopts')).default` to access the default export.

• My command-line option is being parsed as a boolean (true/false) instead of a string value.

  cause By default, short options without an immediately adjacent value or the `opts.string` configuration are treated as booleans. Similarly, long options without an `=` sign are boolean.
  fix To force an option to be parsed as a string, use `opts.string: ['optionName']`. To force it as a boolean (and push any subsequent argument into the operand array `_`), use `opts.boolean: ['optionName']`.

• My default options object is being modified after parsing.

  cause Prior to v2.0.0, `getopts` might have mutated the `options.default` object. Since v2.0.0, it explicitly does not.
  fix Ensure you are on `getopts@2.0.0` or newer. If you need to modify the default options based on parsed arguments, create a deep copy of your default options object before passing it to `getopts`.

Warnings

• breaking Version 2.3.0 migrated getopts to be an ES module (ESM) only. Projects using CommonJS `require()` will encounter `ReferenceError: require is not defined` or similar import errors.
  Fix: Migrate your project to use ES modules (`import`) or switch to dynamic `import('getopts')` if staying in CommonJS. Ensure your `package.json` specifies `"type": "module"` or uses `.mjs` file extensions for ESM.
• breaking Version 2.0.0 introduced several behavioral changes, notably parsing a standalone hyphen (`-`) as an operand and explicitly ceasing mutation of the `options.default` object. Code relying on previous behavior for these aspects will break.
  Fix: Review your argument parsing logic for handling of single hyphens (`-`) and ensure `options.default` is not expected to be mutated. Make explicit copies if modification is necessary.
• gotcha Options specified in `opts.string` or `opts.boolean` will be included in the result object with default values (`""` or `false`) even if they are not present in the `argv` array.
  Fix: Always check for the presence of an option's value if `undefined` is expected when the option is not provided. Filter out default values if they are indistinguishable from deliberately provided empty strings or `false`.
• gotcha Short option parsing can be ambiguous: `-a alpha` parses `a` as a string, but `-a` (followed by other options or end of arguments) parses `a` as a boolean. This can lead to unexpected type parsing.
  Fix: Always explicitly define option types using `opts.boolean: ['a']` or `opts.string: ['a']` to ensure consistent parsing behavior regardless of argument placement.
• gotcha If an option is provided multiple times (e.g., `-x A -x B`), its value in the result object will be an array containing all occurrences in order, not just the last one.
  Fix: Anticipate array values for options that can legitimately be repeated. Process these arrays to consolidate or use all values as required by your application logic.

Install

• npm install getopts npm
• yarn add getopts yarn
• pnpm add getopts pnpm

Imports

• getopts
  wrong:

  const getopts = require('getopts')

  correct:

  import getopts from 'getopts'

  Since v2.3.0, getopts is an ES module only. CommonJS `require` will fail.
• Options

  import type { Options } from 'getopts'

  For TypeScript users, import the `Options` interface to type the configuration object.

Quickstart

Demonstrates parsing command-line arguments, including aliases and explicit type definitions for options.

import getopts from "getopts";

const args = process.argv.slice(2);
const options = getopts(args, {
  alias: {
    output: ["o", "f"],
    type: "t",
  },
  boolean: ["verbose"],
  string: ["name"]
});

console.log("Parsed options:", options);
// Example usage: node your-script.js --type=module -o main.js *.{js,json} --name="My App" -v
// Expected output: { _: ['*.{js,json}'], output: 'main.js', type: 'module', o: 'main.js', f: 'main.js', t: 'module', name: 'My App', verbose: true }