How to publish a package that's compatible with projects using "moduleResolution": "nodenext"

[jedwards1211]

Bug Report

I'm trying to use antlr4 in a project. I have this import:

import { CharStream, CommonTokenStream }  from 'antlr4';

If I use "moduleResolution": "nodenext" it says "Module '"antlr4"' has no exported member 'CommonTokenStream'."
This is using TS 5.0.3.

I'd like to make a PR to antlr4 to fix this, but I'm not sure what the correct solution is. There's no obvious best-practice package authoring guidance in the TS docs.

What should be changed in antlr4's package.json? It has "type": "module", "main" and "types" fields. It doesn't seem like the docs are of any help here except that they say "types" is a "Fall-back for older versions of TypeScript". Does this mean "nodenext" completely ignores "types" and the only option would be for antlr4 to provide an export map, or what?

[ritschwumm]

does this answer anything? https://arethetypeswrong.github.io/?p=antlr4%404.12.0

[jedwards1211]

@ritschwumm no it shows node16 (from ESM) | ✅ (ESM) even though the package doesn't work with nodenext.

I think that illustrates that there isn't enough established guidance and knowledge how to make packages support nodenext yet.

In my issue on arethetypeswrong, they confirmed that it doesn't do full checking that would catch issues like this.

[jedwards1211]

Okay the issue is that antlr4's index.d.ts file has export from statements without file extensions.

Because tsc --init very unfortunately sets "skipLibCheck": true I wasn't getting these errors. When I disable it, it tells me exactly what the problem is:

node_modules/antlr4/src/antlr4/index.d.ts:19:15 - error TS2834: Relative import paths need explicit file extensions in EcmaScript imports when '--moduleResolution' is 'node16' or 'nodenext'. Consider adding an extension to the import path.

19 export * from './error';
                 ~~~~~~~~~

[jedwards1211]

Should the docs recommend all pure ESM packages to use "moduleResolution": "nodenext" at build time now?

I see a lot of painful dev confusion ahead as the ecosystem moves toward pure ESM. That confusion can only be prevented through better guidance.

[MartinJohns]

That confusion can only be prevented through better guidance.

That's why #52593 exists.

[fatcerberus]

Okay the issue is that antlr4's index.d.ts file has export from statements without file extensions.

I'm a little confused how this package even works at runtime if this is the case - Node itself won't even resolve ESM imports without a file extension.

[jedwards1211]

@fatcerberus it has ESM .js files that are correct and manually written .d.ts files that lack import extensions

[jedwards1211]

@MartinJohns thanks, I hadn't come across that issue, i can close this then