{"id":17008,"library":"getopts","title":"Getopts CLI Argument Parser","description":"getopts is a lightweight and performant CLI argument parser for Node.js, currently at stable version 2.3.0. It aims to be a drop-in replacement for `minimist` and similar libraries, distinguishing itself through its small footprint (180 LOC), zero dependencies, and significantly faster parsing speeds, reportedly up to 6 times faster than alternatives. The library follows established utility conventions for argument parsing, providing sane defaults for common CLI patterns. It transitioned to ES modules in version 2.3.0 and has shipped TypeScript types since 2.1.1, facilitating modern JavaScript and TypeScript development workflows. Releases are generally driven by new features, bug fixes, and maintenance, with a recent focus on ESM migration.","status":"active","version":"2.3.0","language":"javascript","source_language":"en","source_url":"https://github.com/jorgebucaran/getopts","tags":["javascript","cli","argv","flags","parse","getopts","minimist","cli-parser","typescript"],"install":[{"cmd":"npm install getopts","lang":"bash","label":"npm"},{"cmd":"yarn add getopts","lang":"bash","label":"yarn"},{"cmd":"pnpm add getopts","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"Since v2.3.0, getopts is an ES module only. CommonJS `require` will fail.","wrong":"const getopts = require('getopts')","symbol":"getopts","correct":"import getopts from 'getopts'"},{"note":"For TypeScript users, import the `Options` interface to type the configuration object.","symbol":"Options","correct":"import type { Options } from 'getopts'"}],"quickstart":{"code":"import getopts from \"getopts\";\n\nconst args = process.argv.slice(2);\nconst options = getopts(args, {\n  alias: {\n    output: [\"o\", \"f\"],\n    type: \"t\",\n  },\n  boolean: [\"verbose\"],\n  string: [\"name\"]\n});\n\nconsole.log(\"Parsed options:\", options);\n// Example usage: node your-script.js --type=module -o main.js *.{js,json} --name=\"My App\" -v\n// Expected output: { _: ['*.{js,json}'], output: 'main.js', type: 'module', o: 'main.js', f: 'main.js', t: 'module', name: 'My App', verbose: true }","lang":"typescript","description":"Demonstrates parsing command-line arguments, including aliases and explicit type definitions for options."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=2.3.0"},{"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.","message":"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.","severity":"breaking","affected_versions":">=2.0.0"},{"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`.","message":"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.","severity":"gotcha","affected_versions":">=2.0.0"},{"fix":"Always explicitly define option types using `opts.boolean: ['a']` or `opts.string: ['a']` to ensure consistent parsing behavior regardless of argument placement.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Change `const getopts = require('getopts')` to `import getopts from 'getopts'` and ensure your project is configured for ESM.","cause":"Attempting to import `getopts` using CommonJS `require()` syntax in an ES module environment after upgrading to v2.3.0.","error":"ReferenceError: require is not defined in ES module scope"},{"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.","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.","error":"TypeError: getopts is not a function"},{"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']`.","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.","error":"My command-line option is being parsed as a boolean (true/false) instead of a string value."},{"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`.","cause":"Prior to v2.0.0, `getopts` might have mutated the `options.default` object. Since v2.0.0, it explicitly does not.","error":"My default options object is being modified after parsing."}],"ecosystem":"npm","meta_description":null}