feat!: yargs is now ESM first by bcoe · Pull Request #2451 · yargs/yargs

bcoe · 2025-02-18T01:06:06Z

See: https://joyeecheung.github.io/blog/2024/03/18/require-esm-in-node-js/ for what's motivating this work.

Yargs build step to be dual-mode ESM / CJS had created a fragile build process that has been hard to upgrade over the years. I'm quite excited to remove it.

Known Breaking Changes:

command names are now only derived if you're using commandDir. If you are providing a module directly, a command property must be set.
Supported Node.js versions are now ^20.19.0 || ^22.12.0 || >=23 (there were fixes to issues with require ESM in patch releases of 20.x and 22.x which is why the complicated version range is necessary).
yargs no longer works as a singleton, breaking usage like yargs.parse(), yargs.argv.
I'm sure I've broken some other things with this major overhaul, we'll keep this in beta for a healthy length of time.

TODO:

Look into adding back command name detection for commandDir.
rewrite all docs to not use yargs as singleton (this is no longer a thing in CJS compatibility mode).
- advanced.md
- readme.md
- api.md
- examples.md

Notes

I left the integration tests in CJS so that the behaviour of requiring yargs in a CJS environment can be tested -- this requires Node 23.
- Note: Node 22 still seems to be having issues on Windows.
~~cliui doesn't wrap properly because it's using an old version of wrap-ansi. TODO, unravel this problem.~~ fixed thanks @shadowspawn.
removed which-module functionality (TODO: dig into what the heck I was thinking when I wrote this).
- figured it out, see: inferring module name from path.
1000 lbs 🦍 in the room, should we figure out a replacement for commandDir, perhaps using createRequire? could this be a follow up PR to reduce the scope of this work? (CC: @shadowspawn thoughts). Figured out how to make commandDir work, including inferring name of command from directory.
Coverage is working again and readable \o/ glad to have rollup out of the mix 🥳

BEGIN_COMMIT_OVERRIDE
feat!: yargs is now ESM first
refactor!: command names are not derived from modules passed to command.
refactor!: singleton usage of yargs yargs.foo, yargs().argv, has been removed.
build!: minimum node.js versions now ^20.19.0 || ^22.12.0 || >=23.
END_COMMIT_OVERRIDE

refactor!: commandDir removed (due to not working with ESM)

bcoe · 2025-02-18T01:06:31Z

@shadowspawn this is a work in progress, but porting over tests is going pretty smoothly so far.

shadowspawn · 2025-02-18T01:13:06Z

Oh ho, exciting!

package.json

bcoe · 2025-03-16T16:03:02Z

Probably running ahead of your work in progress. I was trying the branch and found that using require from CJS and experimental-require-module did not get the function with a default import. Tested with node v22 and v23.

@shadowspawn switched to using export {foo as 'module.exports'}; for both cliui and this PR, it seems to work well.

Some cliui PRs open to add wrapping in ESM by working around dependency complications, but perhaps instead moving cliui to ESM-only and use latest dependencies would be in line with this PR?

@shadowspawn thanks for the PR on cliui, I think this is mostly addressed (although I expect we'll have some follow up PRs on that repo).

I was able to stop skipping all the tests related to string wrapping 👍

test/integration.mjs

test/yargs.mjs

shadowspawn · 2025-04-05T02:44:05Z

I have done a pass through whole PR and made some minor comments and questions, nothing blocking.

I plan to do a little user testing on old and new commandDir next.

shadowspawn · 2025-04-05T03:42:47Z

The documentation for .commandDir describes the include and exclude options for require-directory which haven't been implemented.

yargs/docs/advanced.md

Lines 272 to 278 in ef28c98

    
           - `include`: RegExp or function 
        
               Allow list certain modules. See [`require-directory`](https://www.npmjs.com/package/require-directory) for details. 
        
           - `exclude`: RegExp or function 
        
               Block list certain modules. See [`require-directory`](https://www.npmjs.com/package/require-directory) for details.

The previous code was passing through user supplied options object so the user could also supply other require-directory options like renamer, but that behaviour was not documented as such.

shadowspawn

I'm sure I've broken some other things with this major overhaul, we'll keep this in beta for a healthy length of time.

Qualified approval. I think .commandDir() still a work in progress with include/exclude to implement or deprecate. But overall and notwithstanding .commandDir(), up to at least beta quality with what I saw and tried.

Nice work!

Co-authored-by: John Gee <john@ruru.gen.nz>

bcoe · 2025-04-08T21:11:58Z

Regarding:

The documentation for .commandDir describes the include and exclude options for require-directory which haven't been implemented.

@shadowspawn I've added back support for include / exclude, based on how I think it should work. The documentation for require-directory seemed off to me, with it documenting the same behaviour for include / exclude.

The previous code was passing through user supplied options object so the user could also supply other require-directory options like renamer, but that behaviour was not documented as such.

Given that this behaviour isn't documented in yargs, I think it's not a breaking change to remove it.

vipzhicheng · 2025-04-21T16:54:02Z

lib/command.ts

-    // disable recursion to support nested directories of subcommands
-    if (typeof opts.recurse !== 'boolean') opts.recurse = false;
+    this.requireCache.add(callerFile);
+    const fullDirPath = join(dirname(callerFile), dir);


Hey, I found that commandDir has been changed to be relative from here on. I just want to know the reason. Is it related to security concerns? Because in my case, I use the commandDir feature extensively to load commands from various locations (v17.7.2), not just from a single project directory. For example, I combine project commands, home directory commands, and global directory commands. With this change, my approach has become completely unfeasible. So I'd like to know if there's an option that allows the directory to be an absolute directory.

Except for the above case, there is another scenario that would also fail. Put yargs in the @org/core package, and export an API to launch CLI tools. Then, add commands from another package that imports @org/core and passes the directory via the API.

The intent is that the directory passed into .commandDir() can be absolute, and it is probably an oversight (bug) if an absolute path passed into .commandDir() does not work.

Have you confirmed this problem at runtime, or is this feedback from code inspection?

(I won't have time to try reproducing and look carefully until later.)

I prepared a demo repo for this issue. It can be reproduced. When you have time, you can give it a shot.

https://github.com/vipzhicheng/test-yargs-next

Logically, fullDirPath is callerFile dir + passed in dir, I hope it is just passed in dir, like before.

Thanks for the example repo, and I reproduced the issue as described.

High level, I suspect replacing path.join with path.resolve at some level is appropriate.

I checked original package for comparison and it does use path.resolve in implementation: https://github.com/troygoode/node-require-directory/blob/d1fd7dc2eaf02832de94dbe1af0c52271697050e/index.js#L56C1-L57C1

@vipzhicheng Would you like to make a new issue, or even a PR, or shall I open one based on this info?

Thanks for taking a look at the pre-release and reporting the issue. Much appreciated.

I have made a PR #2465, Please take a look.

Just like you suggested, it works in my test repo and also still passes all npm run test after the change.

feat!: yargs is now ESM only

727bd1e

refactor!: commandDir removed (due to not working with ESM)

bcoe added 2 commits February 17, 2025 21:04

test: port completion tests to esm

deb8cc8

test: finished porting integration

9e2f680

This comment was marked as resolved.

Sign in to view

shadowspawn reviewed Feb 20, 2025

View reviewed changes

package.json Show resolved Hide resolved

shadowspawn reviewed Feb 20, 2025

View reviewed changes

package.json Outdated Show resolved Hide resolved

This comment was marked as resolved.

Sign in to view

shadowspawn mentioned this pull request Mar 8, 2025

feat!: cliui is now ESM only yargs/cliui#165

Merged

2 tasks

bcoe added 9 commits March 15, 2025 19:04

test: continuing to migrate tests

07e9577

actually remove commandDir

ea68275

build: fiddling with build settings

f427f56

buid: fiddling with build settings

7526a76

build: fixing up build

85a5529

fix: make require() more intuitive for CJS update cliui

4cec686

chore: pull in new string wrapping logic

8fbcf0b

chore: add back . import

253e804

chore: addressing review

6d86df5

bcoe added 5 commits March 16, 2025 12:07

experiment with actions

147871c

try spawn rather than cross-spawn

5246892

I was being siilly and clobbering env

4800996

chore: increase max timeout

05d6b3d

chore: use v23 on windows too

3bf0280

bcoe marked this pull request as ready for review March 16, 2025 16:35

bcoe added 3 commits March 16, 2025 22:49

chore: add test for helpers.mjs

6df6442

chore: add test for helpers.mjs

1900cd1

boom, test coverage back up to 100%.

3d2b7e0

shadowspawn reviewed Apr 4, 2025

View reviewed changes

test/integration.mjs Outdated Show resolved Hide resolved

shadowspawn reviewed Apr 5, 2025

View reviewed changes

test/yargs.mjs Show resolved Hide resolved

shadowspawn reviewed Apr 5, 2025

View reviewed changes

test/yargs.mjs Outdated Show resolved Hide resolved

shadowspawn approved these changes Apr 5, 2025

View reviewed changes

bcoe and others added 15 commits April 5, 2025 21:34

docs: update advanced.md to show esm usage

b339422

docs: remove out of date bundling docs

c26ac81

Update package.json

95bcf4f

Co-authored-by: John Gee <john@ruru.gen.nz>

build: addressing build review

68d060e

build: use LTS node version

4d65b06

build: windows still having issues on 22

5624cca

deps: remove now unused deps

03ed80a

docs: remove a couple references to require I missed

bb26f7f

docs: recombined CHANGELOGs

07b0e33

docs: update examples.md to use esm

81ca1c7

docs: update typescript.md

ded61ef

test: --experimental-require-module no longer required

d685d25

test: remove unnecessary getInternalMethods()

adc6522

test: remove unused log line

56c15f4

feat: add back support for include / exclude

9e920df

bcoe merged commit d90af45 into main Apr 9, 2025
6 checks passed

This was referenced Apr 13, 2025

feat!: yargs is now ESM first yargs/yargs-parser#503

Merged

Yargs 18 is ESM, prerelease available now #2460

Closed

vipzhicheng reviewed Apr 21, 2025

View reviewed changes

shadowspawn mentioned this pull request Jun 14, 2025

feat!: y18n is now ESM first yargs/y18n#173

Open

colincasey mentioned this pull request Aug 6, 2025

Update tough-cookie@6.x jsdom/jsdom#3876

Merged

ej-toita mentioned this pull request Oct 1, 2025

import.meta.resolve gives compile-time warning when bundling with webpack #2489

Open

shadowspawn mentioned this pull request Feb 14, 2026

Switching to esm-only tj/commander.js#2464

Merged

10 tasks

Conversation

bcoe commented Feb 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Notes

Uh oh!

bcoe commented Feb 18, 2025

Uh oh!

shadowspawn commented Feb 18, 2025

Uh oh!

This comment was marked as resolved.

Uh oh!

Uh oh!

This comment was marked as resolved.

This comment was marked as resolved.

bcoe commented Mar 16, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

shadowspawn commented Apr 5, 2025

Uh oh!

shadowspawn commented Apr 5, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

shadowspawn left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bcoe commented Apr 8, 2025

Uh oh!

Uh oh!

vipzhicheng Apr 21, 2025

Choose a reason for hiding this comment

Uh oh!

vipzhicheng Apr 21, 2025

Choose a reason for hiding this comment

Uh oh!

shadowspawn Apr 21, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

vipzhicheng Apr 22, 2025

Choose a reason for hiding this comment

Uh oh!

shadowspawn Apr 23, 2025

Choose a reason for hiding this comment

Uh oh!

shadowspawn Apr 23, 2025

Choose a reason for hiding this comment

Uh oh!

vipzhicheng Apr 23, 2025

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

bcoe commented Feb 18, 2025 •

edited

Loading

shadowspawn commented Apr 5, 2025 •

edited

Loading

shadowspawn left a comment •

edited

Loading

shadowspawn Apr 21, 2025 •

edited

Loading