82 curated breaking changes across major versions of yargs. Use this as a migration checklist before bumping dependencies.
command names are not derived from modules passed to `command`.
yargs is now ESM first
minimum node.js versions now `^20.19.0 || ^22.12.0 || >=23`.
singleton usage of yargs yargs.foo, yargs().argv, has been removed.
implicitly private methods are now actually private
**node:** drop Node 10 (#1919)
.positional() now allowed at root level of yargs.
**yargs-factory:** refactor yargs-factory to use class (#1895)
deprecated reset() method is now private (call yargs() instead).
**usage:** single character aliases are now shown first in help output
tweaks to ESM/Deno API surface: now exports yargs function by default; getProcessArgvWithoutBin becomes hideBin; types now exported for Deno.
drop support for EOL Node 8 (#1686)
rebase helper is no longer provided on yargs instance.
find-up replaced with escalade; export map added (limits importable files in Node >= 12); [email protected] (new decamelize/camelcase implementation).
parse() now behaves as an alias for .argv, unless a parseCallback is provided.
version() and help() are now enabled by default, and show up in help output; the implicit help command can no longer be enabled/disabled independently from the help command itself (which can now be disabled).
the first argument to strict() is now used to enable/disable its functionality, rather than controlling whether or not it is global.
Node 4+ is now required; this will allow us to start updating our dependencies.
extends functionality now always loads the JSON provided, rather than reading from a specific key
the arguments passed to functions are now validated, there's a good chance this will throw exceptions for a few folks who are using the API in an unexpected way.
context now takes precedence over argv and defaults
by default options, and many of yargs' parsing helpers will now default to being applied globally; such that they are no-longer reset before being passed into commands.
yargs will no longer aggressively suppress errors, allowing errors that are not generated internally to bubble.
`extends` key in config file is now used for extending other config files
environment variables now take precedence over config files.
coerce is now applied as a final step after other parsing is complete
we now default to an empty builder function when command is executed with no builder.
introduces a default `help` command which outputs help, as an alternative to a help flag.
yargs-parser now better handles negative integer values, at the cost of handling numeric option names, e.g., -1 hello
fail is now applied globally.
interpret demand() numbers as relative to executing command ([#582](https://github.com/yargs/yargs/issues/582)) ([927810c](https://github.com/yargs/yargs/commit/927810c))
default: removed undocumented `defaults` alias for `default`.
[#376](https://github.com/bcoe/yargs/pull/376) **breaking change**, make help() method signature
[#330](https://github.com/bcoe/yargs/pull/330) **breaking change**, fix inconsistencies with `.version()` API. (@maxrimue).
[#368](https://github.com/bcoe/yargs/pull/368) **breaking change**, overhaul to command handling API:
[#382](https://github.com/bcoe/yargs/pull/382) pass error as extra parameter to fail (@gajus)
[#357](https://github.com/bcoe/yargs/pull/357) .strict() now requires that a valid command is provided (@lrlna)
[#378](https://github.com/bcoe/yargs/pull/378) introduces the pkgConf feature, which tells
[#384](https://github.com/bcoe/yargs/pull/384) add new number type to yargs (@lrlna, @maxrimue)
[#356](https://github.com/bcoe/yargs/pull/356) pull the parsing bits of yargs into the separate module yargs-parser. Various parsing options can now be turned on and off using configuration (@bcoe).
[#364](https://github.com/bcoe/yargs/pull/364) add the slick new yargs website to the package.json (@iarna).
minimum node.js versions now `^20.19.0 || ^22.12.0 || >=23`.
yargs is now ESM first
command names are not derived from modules passed to `command`.
singleton usage of yargs yargs.foo, yargs().argv, has been removed.
#1823 contains the following breaking API changes:
.positional() now allowed at root level of yargs.
getCompletion now invokes callback with err and `completions, returns promise of completions.
now returns a promise if handler is async.
**middleware:** global middleware now applied when no command is configured.
**async:** yargs now returns a promise if async or check are asynchronous.
**coerce:** coerce is now applied before validation.
**yargs-factory:** refactor yargs-factory to use class (#1895)
implicitly private methods are now actually private
**node:** drop Node 10 (#1919)
deprecated reset() method is now private (call yargs() instead).
onFinishCommand removed, in favor of being able to await promise.
tweaks to ESM/Deno API surface: now exports yargs function by default; getProcessArgvWithoutBin becomes hideBin; types now exported for Deno.
drop support for EOL Node 8 (#1686)
rebase helper is no longer provided on yargs instance.
find-up replaced with escalade; export map added (limits importable files in Node >= 12); [email protected] (new decamelize/camelcase implementation).
**usage:** single character aliases are now shown first in help output
**deps:** [email protected] no longer implicitly creates arrays out of boolean
**deps:** yargs-parser now throws on invalid combinations of config (#1470)
[email protected] drops support for Node 6
drop Node 6 support (#1461)
remove package.json-based parserConfiguration (#1460)
we now only officially support yargs.$0 parameter and discourage direct access to yargs.parsed
previously to this fix methods like `yargs.getOptions()` contained the state of the last command to execute.
do not allow additional positionals in strict mode
options with leading '+' or '0' now parse as strings
we now warn if the yargs stanza package.json is used.
see [[email protected] CHANGELOG](https://github.com/yargs/yargs-parser/blob/main/CHANGELOG.md#breaking-changes)
dropping Node 6 which hits end of life in April 2019
Options absent from `argv` (not set via CLI argument) are now absent from the parsed result object rather than being set with `undefined`
drop Node 4 from testing matrix, such that we'll gradually start drifting away from supporting Node 4.
yargs-parser does not populate 'false' when boolean flag is not passed
tests that assert against help output will need to be updated
requiresArg now has significantly different error output, matching nargs.
.usage() no longer accepts an options object as the second argument. It can instead be used as an alias for configuring a default command.
previously hidden options were simply implied using a falsy description
help command now only executes if it's the last positional in argv._
Get this data programmatically \u2014 free, no authentication.
curl https://depscope.dev/api/breaking/npm/yargs