docs: add util.parseArgs replacements for CLI argument parsers

[bjnewman]

Summary

Adds migration documentation for replacing CLI argument parsing packages with Node.js built-in util.parseArgs (available in Node 18.3+/16.17+).

Packages covered

• minimist
• mri
• arg
• meow
• yargs-parser
• yargs
• commander
• sade

Changes

• New docs/modules/parseargs.md with migration examples for each package
• Added 8 entries to manifests/preferred.json

Notes

• Examples use nullish coalescing (??) for defaults instead of parseArgs's default option to ensure compatibility with all Node 18.3+ versions
• Includes feature comparison table and caveats about subcommands/auto-help
• Covers advanced patterns like token-based parsing for minimist compatibility

[ljharb]

Also worth suggesting as an alternative is https://npmgraph.js.org/?q=pargs, which is built on top of util.parseArgs, has no deps, is written in ESM, and adds a number of helpful features when migrating from the listed packages.

[43081j]

sorry its taken me a while to get to this

i think we need some 2nd opinions here as this diverges from the usual structure we have

we follow one of two paths so far:

• the document is named after the thing being replaced, and lists migrations to the various options
• the document is named after the primary replacement (e.g. fetch), and lists other options but usually no migrations

in this case, it is listing the things being replaced along with their migrations. which is different to all other docs

@Fuzzyma thoughts?

[Fuzzyma]

hm, so would you rather have x documents that all have one migration "x to fetch" and then in the fetch document link to all migrations? I think that would be cumbersome.

Is there a reason we usually dont have migrations in the "fetch-like" documents?

[bjnewman]

Thanks for the great work on this project and for taking the time to
review! I went with a single doc covering all 8 packages because their
APIs all converge on the same built-in replacement (util.parseArgs),
and I wanted to show the specific before/after for each since they have
pretty different APIs.

I was loosely modeling off of fetch.md, lodash-underscore.md, and
bluebird-q.md, which also group multiple packages into one doc. But I
can see how the per-package migration examples diverge from those.

Happy to restructure to better fit the project — just let me know what
you'd prefer and I'll update.

[43081j]

i more meant that the way fetch.md is structured is fine, but this isn't structured like that

im finding it difficult to find the right words to explain this 😂

the fetch document explains fetch and alternative packages.

this document explains packages being replaced.

i.e. the focus/context in the fetch doc is the alternatives, but the focus in this one is the replaced modules.

EDIT:

like the title of the page is # Replacements for argument parsers, but then we list the packages being replaced (the headings are those of the packages being replaced). everywhere else, we list the replacements (as per the title)

[gameroman]

@bjnewman would you like to continue with this or prefer me to take over?

[43081j]

i think its fine to have one doc here, as we do that for some other packages (e.g. fetch-like packages).

but the headings need to be the things we're replacing these modules with.

currently this PR has this structure:

# Replacements for argument parsers

...

## minimist

...

but that doesn't make sense because minimist isn't a replacement for an argument parser. it is the thing being replaced.

it needs to be a much simpler doc i think, following the same pattern as all other docs:

# Replacements for argument parsers

## `util.parseArgs` (native, Node.js)

...

[gameroman]

I still think we should have a separate doc for each, like we have for glob packages, as some packages have very different behaviours

And for packages that have similar behaviour we can combine into one

[bjnewman]

Sorry for the delay in responding to the feedback. I updated the doc page to follow the patterns from the rest of the pages.

@gameroman if you want to separately open a PR with a single page for each of the targeted replacements please feel free I won't be offended.

[gameroman]

Sorry for the delay in responding to the feedback. I updated the doc page to follow the patterns from the rest of the pages.

No worries, thank you very much for contributing!

[43081j]

I'm not sure sade should be in here.

From what I remember it uses mri under the hood to do arguments parsing. But it exists to provide help text etc on top of that.

In a future pr, we should probably add sade as a replacement itself for some packages in fact

[gameroman]

It does use mri, yes

[43081j]

that's why it shouldn't really be here.

sade exists to provide a CLI args parser and help text generator (the former being provided by mri under the hood).

parseArgs replaces mri, but doesn't replace sade.

[ghostdevv]

did we decide whether we're removing this here, and adding it in the follow up?

[Dustin4444]

Added one comment. Everything else looks fine

[43081j]

i think we need to rework this a bit. these packages parse args and generate help text:

• meow
• sade
• commander
• yargs

this means they can't really be replaced by parseArgs alone as much of their functionality exists for generating help text and what not.

i think we should mark those (minus sade) as replaceable by sade, stricli, and cleye.

[ghostdevv]

i think we should mark those (minus sade) as replaceable by sade, stricli, and cleye.

cac also? what about frameworks that do more, there is that one that I can't remember the name of, but I guess it's a job of communicating what you should use based on what you need...

[43081j]

i'd basically expect we end up with 3 categories/sets of replacements:

• Argument parsers (mri, arg, etc. -> parseArgs)
• CLI builders (meow, commander, yargs, etc. -> sade, cleye, stricli)
• CLI renderers (inquirer, etc. -> clack)

and any that do a bit of everything should really be documented as being replaced by a builder + renderer rather than a catch all package somehow.

[gameroman]

Also getopts

[gameroman]

I will also make a pr 👍

[ghostdevv]

did we decide whether we're removing this here, and adding it in the follow up?