Support for package `exports` map

[chriskrycho]

Search Terms

• exports
• TypeScript 4.7
• packages
• ES Module

Problem

Today, if you use exports with TS 4.7 to create a public API that is different from the layout you author in, TypeDoc preserves the authoring API rather than the consuming API.

Consider a structure like this:

my-project/
  src/
    public/
      index.ts
      other-module.ts
    -private/
      internal-only.ts

The tsconfig.json specifies an outDir of dist, resulting in this output:

my-project/
  dist/
    public/
      index.js
      index.d.ts
      other-module.js
      other-module.d.ts
    -private/
      internal-only.js
      internal-only.d.ts

Finally, package.json has this:

{
  "exports": {
    ".": "./dist/public/index.js",
    "./package.json": "./package.json",
    "./*": "./dist/public/*.js"
  },
}

This means that Node consumers (and any tools following its resolution algorithm) can now import not only from the index.js but from other-module as well:

import { something } from 'my-project';
import { somethingElse } from 'my-project/other-module';

The docs generated by TypeDoc, however, render the modules without reference to the exports map in package.json, so you end up with a list of modules like this:

• public
• public/other-module

For a real-world example of this, see True Myth and its docs.

Suggested Solution

The resolved module map should follow the resolution algorithm from exports in package.json the way TS itself does, so that the resolved module name is based on the mapping defined there.

---

Note: I know 4.7 came out literally this week, and that this is likely non-trivial! Just figured I'd write it up to get it here so if folks search they will see that it's open.

[chriskrycho]

Possibly a duplicate of #1934, which I somehow missed despite looking at all open issues, searching, etc.: and it was right in front of my face! 🤦🏼‍♂️ Feel free to close/merge with that one as makes sense! (It doesn't overlap 100%, but it may make sense to track in one spot.)

[wenerme]

How about support entryPoints in package.json first, I can live without exports support (not easy) as long as the generated doc contain the def.

{
  "typedoc": {
    "entryPoints": ["./src/index.ts","./src/server.ts"],
    "readmeFile": "./README.md"
  }
}

https://github.com/wenerme/wode/blob/6c111c343a1e575cef6795be91cffaa6ad9359ec/packages/utils/package.json#L96-L99

[Gerrit0]

So... I've spent probably a dozen hours poking at this over the past few months... and it's ridiculously complicated. I ran into microsoft/TypeScript#50466 today.

How about support entryPoints in package.json first, I can live without exports support (not easy) as long as the generated doc contain the def.

PR welcome

[RichiCoder1]

I'd be willing to take a peek at implmeneting this! Though it appears there's a pending release (0.24?) that I should probably wait for before doing so?

If this takes the exports approach, it'd likely be easier and/or better to follow the new bundler resolution approach introduced in TS 5.0.

[tintinthong]

What is the status of this issue? Is this coming out in 0.24??

[Gerrit0]

Not planned for 0.24. I'm not entirely convinced there's a good way of doing this that'll work for more than 50% of packages, at least without requiring a custom resolution mode to tell TD what to use. The problem is mainly projects which ship esm and cjs, and use the exports map to associate different build outputs which each.

[tintinthong]

Not planned for 0.24. I'm not entirely convinced there's a good way of doing this that'll work for more than 50% of packages, at least without requiring a custom resolution mode to tell TD what to use. The problem is mainly projects which ship esm and cjs, and use the exports map to associate different build outputs which each.

Perhaps then its worth pursuing this pr suggestion. I will work on it if there is no current work ongoing

[RichiCoder1]

without requiring a custom resolution mode to tell TD what to use. The problem is mainly projects which ship esm and cjs, and use the exports map to associate different build outputs which each.

The boring answer might just be to always assume import condition (since a lot of commonjs still use ESM and then downcompile), and then plug it into something like https://github.com/lukeed/resolve.exports to keep the complicated exports logic external. Or no condition and let the cards fall where they may, with maybe a config option to specify the default.