Split TS declaration files are not compatible with nodenext module resolution

[ssangervasi]

TLDR: Microbundle should output a single .d.ts per output module file, or nodenext is too unstable to target at all.

Background

This issue is a funky mixture of a few other issues:

1. The ongoing changes to TS's module resolution, where nodenext (aka node16) uses modules: A Proposal For Module Resolution microsoft/TypeScript#50152
2. Microbundle's basic documentation of nodenext compat: Guidance around exports.types config when authoring in TS #990
3. And the fact microbundle generates multiple .d.ts files for a single .*js output: [Typescript] Typings files not concatenated? #239

Reproducing

I forked the code from #239 and updated it to highlight the problem with nodenext: https://github.com/ssangervasi/microbundle-typings.
In this example, you can see:

1. ✔️ The "library" package is built with microbundle
2. ✔️ The library package has exports.types pointing to the module's types, dist/index.d.ts, as suggested by microbundle's readme.
3. 😐 That declaration file has a relative dependency on another file produced by microbundle.
4. ✔️ The dependent package is built with tsc 4.9.4 with nodenext. (This is the thing I want the users of my package to be able to do.)
5. ✔️ The dependent package can resolve the library package's root declaration.
6. 😞 TypeScript can't resolve the relative dependency produced by microbundle.

Proposed solution

My instinct is that generating multiple .d.ts files for a single output module is going to cause problems in general. In this case, if the build process could merge them (the same way it merges the JS into a single file), the TS resolution problem would go away. Basically reopening #239.

On the other hand, TS's moduleResolution is madenning*, and it's possible this relative lookup will go away in later versions. Microbundle's readme could be updated to note this incompatibility for now. As far as I can tell, there isn't a way to get these split .d.ts files to work, except maybe package.json redirects which I'm not willing to try or publish.

* On par with how complex JS's dependency system is.

[rschristian]

There's an easy fix:

// src/index.ts
-export * from "./foo";
+export * from "./foo.js";

Longer answer: This really isn't a Microbundle issue, but a TS issue. You'll run into this same behavior using tsc directly. See microsoft/TypeScript#16577, microsoft/TypeScript#49083

The TS team have drawn a line in the sand and refuse to rewrite module specifiers as there's no TS features there; instead, you're supposed to use .js to refer to .ts and .tsx files. There have been dozens of issues opened up on the TS repo for this, but it's the way they've decided to go. We're (more or less) using tsc here, so our behavior matches the official compiler.

While merging declaration files could be nice, it's not without it's own complexities and it would be a move away from tsc which increases the maintenance burden. Outputting multiple .d.ts files for a single output is default tsc behavior, it's not a choice we made or anything.

[ssangervasi]

Holy moly, I read about that but still couldn't understand the fix applied to this situation.

TypeScript will impose Node’s much stricter ESM resolution algorithm on those files, disabling index-file resolution and extensionless lookups—in fact, the extension the user has to write is .js, which will be nonsensical for the context, where the runtime module resolver (the bundler) only ever sees .ts files.

Thanks for explaining!

[rschristian]

No problem, it's certainly a weird one. Using foo.js to refer to foo.d.ts file is quite the odd design choice to most users I think.