Better error message for using outdated moduleResolution: node(10)

[JoshuaKGoldberg]

Suggestion

🔍 Search Terms

moduleResolution node node10 eol esm commonjs cannot find types

✅ Viability Checklist

My suggestion meets these guidelines:

• This wouldn't be a breaking change in existing TypeScript/JavaScript code
• This wouldn't change the runtime behavior of existing JavaScript code
• This could be implemented without emitting different JS based on the types of the expressions
• This isn't a runtime feature (e.g. library functionality, non-ECMAScript syntax with JavaScript output, new syntax sugar for JS, etc.)
• This feature would agree with the rest of TypeScript's Design Goals.

⭐ Suggestion

When a TSConfig is using "moduleResolution": "node" or "node10" and an import resolves to an npm package whose types declarations that doesn't support Node < 16, the error message in tsc is very general:

Cannot find module '...' or its corresponding type declarations.

Same in VS Code:

Could we please have a secondary message added suggesting that the project be switched to using a more modern "moduleResolution"?

This message needs bikeshedding, but a starting proposal:

Cannot find module '...' or its corresponding type declarations.
    Consider upgrading your "moduleResolution" compiler option. See aka.ms/tsconfig#moduleResolution for details.

📃 Motivating Example

This has been a point of confusion in at least typescript-eslint/typescript-eslint#7284. We've gotten a few duplicate reports.

💻 Use Cases

Same as ☝️, I think. I can't think of anything more specific.

[RyanCavanaugh]

People are going to come here and complain if we issue that message and it turns out that the module really isn't there under any setting, and I don't really see a way we could determinatively detect which (if any) other resolution settings would work.

[JoshuaKGoldberg]

Hmm. Maybe it can just link to aka.ms/tsconfig#moduleResolution then?

detect which (if any) other resolution settings would work

Also, I'm realizing now I meant to suggest in the OP that this message should only be there if any other resolution setting would work. 😬

[RyanCavanaugh]

Under different module resolution settings, we could even have entirely different source files under analysis, rendering the original import moot. It's not tractable in the general case IMO

[DanielRosenwasser]

Could we just have node10 do the same thing node16 does and specially handle the error where they would have diverged?

[DanielRosenwasser]

Or something more naive where we keep track of whether exports was specified anywhere where we checked.

[blakeembrey]

@DanielRosenwasser is it possible to use ambiguous language in the presence of “exports”? For example, “This package may be resolvable using (…) because we found type module and exports declared in the package”?

I’ve only converted a few packages I maintain to be ESM so far, but every time I do I get issues like blakeembrey/change-case#304. The current message isn’t adequate to show the issue is in user configuration and not the package.

[DanielRosenwasser]

We use "may" a lot of the time, so I'm okay with that.

[bradzacher]

Coming back to this - this is a pretty persistent pain-point for users of @typescript-eslint.

We've found that a lot of users don't know that:

• moduleResolution: node actually means node10
• node16 exists
• node10 is different to node16
• they're using a module resolution that doesn't match their runtime (our minimum supported node version is 16).

We've had to keep this pinned issue up and open to give people docs on how to fix the unclear error message, or else they file an issue with us saying our package is broken.

I'm sure there are a lot of packages out there who continue to include a types field in their package.json solely to stave-off the support burden of users who are still (usually erroneously) using node10 resolution.
We could do this also - but it does seem "smelly" that we would consider changing our config to avoid support burden from an unclear TS error message.

I 110% get that we can't make the error message say something so absolute like "you're using node10 but this package doesn't have a types field declared, but it has an exports field, you must use node16 instead" because, well, it's a different module resolution and that advice may not even be correct!
But as @blakeembrey suggested maybe there's a way we can help nudge the user in the right direction for this specific case? Or at least suggest something that might help them try something else and self-service fix their problem, rather than having to reach for stackoverflow / github issues / discord messages in order to even learn about the 2 character config change that could fix their problem.

For example, would this rough logic be acceptable?
"if TS finds a package that has no types field but has an exports field with a nested types field, then append This package may be resolvable using (…) because we found typed exports declared in the package. to the error message"

[RyanCavanaugh]

@andrewbranch does the above sound like something we can do?

[andrewbranch]

Yes 👍