Support require(esm) in --module nodenext

[andrewbranch]

Fixes #60534

require(esm) is currently unflagged in Node.js v22, but may be in v20 by the time this PR lands for 5.8. We’ll have a discussion about the flag name if it doesn’t happen by 5.8-beta. EDIT: the backport will not come in time for 5.8; we are only changing --module nodenext here, and will aim to make a --module node20 in 5.9.

This PR does not currently attempt to error on require calls of async modules (those with top-level await). We do not emit any special marker in declaration files indicating the presence of TLA, which is a prerequisite. My suspicion is that the sentiment will be that a static check for async modules in the require graph is not worth the pain of making a backward-incompatible declaration file change.

The other change in this PR is that import assertions are now prohibited in --module nodenext, since Node.js v22+ does not parse them. Since there have been a lot of module target changes in fast succession, here’s the summary:

5.6

	target	moduleResolution	import assertions	import attributes	JSON imports	require(esm)
node16	es2022	node16	❌	❌	no restrictions	❌
nodenext	esnext	nodenext	✅	✅	no restrictions	❌

5.7.3

	target	moduleResolution	import assertions	import attributes	JSON imports	require(esm)
node16	es2022	node16	❌	❌	no restrictions	❌
nodenext	esnext	nodenext	✅	✅	needs type "json"	❌

5.8

	target	moduleResolution	import assertions	import attributes	JSON imports	require(esm)
node16	es2022	node16	❌	❌	no restrictions	❌
node18	es2022	node16	✅	✅	needs type "json"	❌
nodenext	esnext	nodenext	❌	✅	needs type "json"	✅

5.9 (planned)

	target	moduleResolution	import assertions	import attributes	JSON imports	require(esm)
node16	es2022	node16	❌	❌	no restrictions	❌
node18	es2022	node16	✅	✅	needs type "json"	❌
node20	es2023	node16	✅	✅	needs type "json"	✅
nodenext	esnext	nodenext	❌	✅	needs type "json"	✅

[typescript-bot]

Thanks for the PR! It looks like you've changed the TSServer protocol in some way. Please ensure that any changes here don't break consumers of the current TSServer API. For some extra review, we'll ping @sheetalkamat, @mjbvz, @zkat, and @joj for you. Feel free to loop in other consumers/maintainers if necessary.

[typescript-bot]

Looks like you're introducing a change to the public API surface area. If this includes breaking changes, please document them on our wiki's API Breaking Changes page.

Also, please make sure @DanielRosenwasser and @RyanCavanaugh are aware of the changes, just as a heads up.

[marco-ippolito]

I will probably release Node v20 (maybe the backport for require(esm)) around half of January 🙂

[andrewbranch]

@marco-ippolito things still look good for backporting?

[marco-ippolito]

@marco-ippolito things still look good for backporting?

It might take a bit longer than expected due to the complexity of the backport, @joyeecheung is actively working on it. Ill keep here updated.

[marco-ippolito]

We won't actually be able to fully backport require(esm) in the next v20 release happening next week, it will go to next one probably (March I think)

[andrewbranch]

Since the backport won’t happen until after 5.8 stable is out, I think the best thing to do might be to put this functionality only in --module nodenext for this release, and hopefully for 5.9 we can snap a --module node20

[jakebailey]

Code LGTM but I know the naming very much depends on Node's scheduling and our own scheduling.

[jakebailey]

Approving a second time, but I do enjoy how "make require(ESM) work" is just a one line change 😄

[joyeecheung]

Hi, as commented by Marco before the backport was more challenging than we thought, though there's still hope to get it out in the March release. See nodejs/node#52697 (comment) and nodejs/node#56730 for more information about the progress.

[andrewbranch]

If the March release contains the backport, that will be on track for TypeScript 5.9. 5.8 stable is scheduled to come out in February.

[rauschma]

Wish: Show the tables (maybe only the one for the most recent version of TypeScript) in the documentation somewhere. I find them very useful.

[zanminkian]

import packageJson from '../package.json' with { type: 'json' };

Code above will cause tsc fail under nodenext without resolveJsonModule field. However, Node v18.20 supported it now.

TS 5.9 should defaultly allow it without resolveJsonModule field.

[andrewbranch]

@rauschma they’re here now: https://www.typescriptlang.org/docs/handbook/modules/reference.html#node16-node18-nodenext

@zanminkian I agree.