package.json `exports` resolution uses fallback conditions, unlike Node

[andrewbranch]

Bug Report

🔎 Search Terms

I’ve never been more confident, without searching, that I’m the first person to notice this

💻 Code

{
  "exports": {
    ".": {
      "import": "./dist/main.mjs",
      "types": "./dist/foo.d.ts"
    }
  }
}

🙁 Actual behavior

Importing this package from an ESM file, in --moduleResolution nodenext, searches for types at these locations:

• ./dist/main.mts
• ./dist/main.d.mts
• ./dist/foo.d.ts

🙂 Expected behavior

It should not search the types condition, because import already matched, and contained a valid target ./dist/main.mjs. Resolution here should fail for consistency with Node, which would throw a resolution error if it matched a condition but then failed to find the file specified in it.

Fixing this bug may cause more harm than good. I noticed it because I claimed that a popular library would be broken under certain conditions due to misconfigured exports, but was proven wrong in reality. I figured this may be worth documenting, but likely not worth fixing. But if someone can make a good case for why it matters, I would reconsider.

[frehner]

Thanks for reporting this! I think I ran into this while testing the types for a library I had created, but honestly thought it was more something I was doing wrong than something TS would be doing wrong.

Here's an additional library I've found that has types at the end instead of at the start:

headless-ui/react and headless-ui/vue

There's probably more out there as well.

[frehner]

As far as whether to fix it or not:

The pro of fixing it now is that it prevents the ecosystem from continuing this behavior, and thus allowing it to be entrenched.

Maybe at the least there could be a warning saying "this works now, but it's incorrect and may not work in the future" or something? 🤷

[andrewbranch]

Maybe at the least there could be a warning saying "this works now, but it's incorrect and may not work in the future" or something?

We don’t have a way to do warnings on the CLI, but #46861 is related.

[Andarist]

package.json

{
  "exports": {
    ".": {
      "require": "./dist/main.js",
      "types": "./dist/foo.d.ts"
    }
  }
}

pkg layout

dist/main.js
dist/main.d.ts
dist/foo.d.ts
package.json

Which .d.ts should be loaded? Should it be dist/main.d.ts or dist/foo.d.ts? Is a sibling .d.ts lookup still a thing when dealing with exports?

[andrewbranch]

Yes, sibling .d.ts lookup is always a thing, and it’s always the way I recommend people to structure packages when possible. In your example, main.d.ts would be looked up if the import was CJS-format; foo.d.ts would be looked up if the import was ESM-format.

[Andarist]

Yes, sibling .d.ts lookup is always a thing, and it’s always the way I recommend people to structure packages when possible.

Interesting. What's the argument for that? I usually assume that an explicit "types" might be better as it's more discoverable without the additional FS check/crawl (for instance npm is labeling packages with the TS label, I didn't check how they do it exactly but I wouldn't be surprised if they would only check the package.json content).

As to the original issue, IMHO this should be fixed on a correctness basis - to match the node's algorithm. Other tools are implementing their algorithm so having this bug~ here might cause people hard-to-debug issues when types will be found by TS itself but won't be found by other tools.

[andrewbranch]

I don’t mind if people want to explicitly list their types, but I dislike separating all the types into a different folder because it’s just so easy to mess up in subtle ways. Putting your .d.ts files next to your .js files is foolproof. Unfortunately it seems library authors by and large dislike this for some reason, and it causes all kinds of problems. So I recommend putting .d.ts files with their partners, for the sake of simplicity and explainability, and then if you want to add (strictly unnecessary) types keys to your package.json too, go for it.

[frehner]

One reason that library authors do it is because it is very easy to create conflicts between esm and cjs files and their types. I kind of alluded to that in the comment here, and especially since, as you mentioned above, the types for esm and cjs aren't always interchangeable.

Another pro of separating them out, though, is that the build output can also include other types of bundles - a "production" and "development" bundle, for example, where the types are the exact same but internally there's additional logging or other tools. Creating a matrix of esm | cjs | umd with development | production bundle outputs, all with the same types, just seems nicer to have a single types output folder to reduce the number of types that need to be generated, and prevent conflicts between them.

[Andarist]

Yeah, that's the main use case that comes to my mind. It's somewhat easy~ to create a sibling file for your package.json#main but once you start adding more "conditions" etc then we usually need a way to redirect them to that single set of .d.ts files (where other conditions in the past were just not observed by TS, so it wasn't as much of an issue).

But when parallelizing bundling and type generation, I would usually be wary of writing to the same directory at once. Writing to separate ones and using package.json#types seems to be a safer/more straightforward way.

But anyway... this all was quite offtopic. Thank you for sharing your thoughts though!

[hayes]

Here is another repro, was just trying to debug this for pothos

https://github.com/hayes/ts-esm-cjs-nodenext

So far the only workaround I have found is creating separate definition files for each build directory. Currently we publish a lib directory with cjs, an esm directory with esm, and a dts directory with definitions. To make this work, I would have to remove "types" from pacakge.json, and publish definitions in both the lib and esm directories, as well as continuing to publish in dts for backwards compatability. Would be awesome if there was a better option that didn't require publishing 3 identical definition files for every source file

[frehner]

Here is another repro, was just trying to debug this for pothos

https://github.com/hayes/ts-esm-cjs-nodenext

So far the only workaround I have found is creating separate definition files for each build directory. Currently we publish a lib directory with cjs, an esm directory with esm, and a dts directory with definitions. To make this work, I would have to remove "types" from pacakge.json, and publish definitions in both the lib and esm directories, as well as continuing to publish in dts for backwards compatability. Would be awesome if there was a better option that didn't require publishing 3 identical definition files for every source file

If it helps, I hacked it so that my build step makes a copy of my index.d.ts, renames the copy to index.d.cts, and then my package exports for "require"'s "types" points to that file. Everything works, and the only extra copy I have is a index.d.cts. 😬

I'm sure there's probably going to be issues with it, but it seems better than the alternatives at the moment.