Resolving multiple package.json "main" fields

[jamiebuilds]

TL;DR: A new compiler option mainFields for selecting multiple fields in package.json instead of just package.json#main.

---

There are lots of related issues to this one (which I link to below), but I want to focus on just this specific proposal.

---

Packages often look like this:

{
  "name": "my-package",
  "main": "dist/cjs/index.js",
  "module": "dist/esm/index.js"
  "source": "src/index.ts"
}

Notice how we have multiple fields which specify multiple entry points. These entry points all refer to the same code, just in different compile states and configurations.

Many tools use these fields in order to find the entry point that they care about. For example, tools like Webpack and Rollup will use package.json#module in order to find ES modules. Other tools will use fields like package.json#source (or src) for local package development.

While these fields aren't part of the official Node module resolution algorithm. They are a community convention which has proven to be useful in lots of scenarios.

For TypeScript, one such scenario that this would be useful for is with multi-package repos or "monorepos". These are repositories where the code for multiple npm packages exist and are symlinked together locally.

/project/
  package.json
  /packages/
    /package-one/
      package.json
      /node_modules/
        /package-two/ -> ../../package-two (symlink)
    /package-two/
      package.json

Inside each package, you'll generally have a src/ directory that gets compiled to dist/

/package-two/
  package.json
  /src/
    index.ts
  /dist/
    index.js
    index.d.ts

Right now it is really painful to use TypeScript with one of these repos. This is because TypeScript will use the package.json#main to resolve to the packages dist folders. The problem with this is that the dist folders might not exist and if they do exist they might not be compiled from the most recent version of src.

To work around this today you can add a index.ts file in the root of each of your packages to point to the right location and make sure that the root index.ts file does not get shipped to npm.

/package-two/
  index.ts
  /src/index.ts

// package-two/index.ts
export * from './src/index'

It sucks that you need this file, and if you ever forget to create it in a new package, you'll revert back to really crap behavior.

If, instead of all that, TypeScript supported a new compiler option mainFields which looked like:

{
  "compilerOptions": {
    "mainFields": ["source", "main"]
  }
}

Note: Webpack has this same configuration option

You could add package.json#source (in addition to package.json#main) and resolve it to the right location locally.

The algorithm would look like this:

For each mainField:

1. Check if the package.json has a field with that name
2. If the package.json does not have the field, continue to next mainField
3. If it field exists, check for a file at that location.
4. If no file at that location exists, continue to the next mainField
5. If the file exists, use that file as the resolved module and stop looking

I think this is the relevant code:

https://github.com/Microsoft/TypeScript/blob/b363f4f9cd6ef98f9451ccdcc7321d151195200b/src/compiler/moduleNameResolver.ts#L987-L1014

Related Issues:

• Path mapping in yarn workspaces #21137 "Path mapping in yarn workspaces"
• Module resolution for sub-packages picks d.ts file when .ts file is available #20248 "Module resolution for sub-packages picks d.ts file when .ts file is available"
• Support .mjs output #18442 "Support .mjs output"

[DanielRosenwasser]

I think the monorepo scenario you have in mind is covered by #3469, but I think there's still room to discuss a package.json resolution strategy.

The problem is that for every dependency that relies on that, the end consumer needs to cover each mainField. It's not a huge problem, but it's the same sort of mental overhead of figuring out that you need to install @types/node for your dependencies to type-check correctly.

[jamiebuilds]

That's not going to work for many monorepos unless you can deal with circular dependencies somehow. It'd also mean that we'd have to duplicate the work of adding dependencies in our package.json and the tsconfig.json files. I'm also not sure how it'd work with our multiple build targets

[aluanhaddad]

For providing intellisense, when no declarations are available, wouldn't it always be better to resolve to the source, if available, than to the compiled output and would that be true irrespective of the source being written in TypeScript?

Even with --allowJs the compiled output is usually resolved when there are no type declarations. This does not only affect developers working with monorepos, it affects anyone consuming packages without declarations.

Of course, it depends on the package, but when using say, "Go to Definition", it is very common to be taken to a UMD bundle and that is probably the least desirable result.

Having said that, there are too many of these damn fields!

Here is a totally non-exhaustive list of main fields that should be considered applicable

"main"
"browser"
"types"
"module"
"jsnext:main"
"es2015"
"unpkg"
"typings"

[lski]

I have been hitting this issue in my Typescript/Webpack/Babel/React app (yes its a mix lol). Using the resolve.mainFields setting in webpack worked great with tree-shaking when writing a none-typescript app, as more and more libraries on NPM (including each of my own) are moving towards supporting the different entry points. I then moved back to Typescript I realised I lost all the benefits as I was stuck importing the full compiled library.

I know the whole main/browser/module has been in flux for a while, especially with jsnext:main/es2015, but it seems to be solidifying around main/browser/module, with things such as unpkg being used for something very specific.

Just my two pence obviously, to show there is a desire for this recommendation. This took 2 days of research just to find out I couldnt do the type of tree-shaking I can do relatively out of the box with webpack and JavaScript, meaning the mental energy used was actually working out the different behaviour in Typescript, rather than knowing about main fields.

[mhegazy]

We have recently added support for building sourceMaps for declaration files, see #22658. We have also added support for tools to go through these declaration files and land on original sources. The net result here is you open a project, hit F12 on an imported declaration, and land in the source code for the referenced module.
We are also working on a rationalized system of project-to-project references in #3469.

There are two main implications of loading of loading .ts files from source instead of .d.ts files, namely 1. configuration has to be the same between the referencing project and the referenced project, since you are basically including the code from one into the other, and 2. the sizes of the state that an IDE (tsserver) needs to keep in memory for these projects can be large, and merging them together increases that and does not give the tools a way to split some of that and unload it for instance.

With the proposed solutions in #22658 and #3469, .d.ts files are still the main interface between projects, allowing for separate compilations and separate configurations. it also allows the tools to build logical boundaries between projects, and can independently jettison some of their state as needed to manage resource consumption.

That said, this whole effort is just starting, we need to support other language service operations like find-all-references and rename on the mapped .d.ts files, we also need to find a way to keep these .d.ts files updated when the .ts files are updated to give the ideal experience.

[jamiebuilds]

.d.ts files won't ever be able to solve this use case because they require building before usage, when you have circular graphs that need to be run sequentially, that is impossible

[cellvia]

please add support for mainFields ... im trying to have vscode resolve to module src files instead of main, because i need to get proper intellisense from external modules jsdoc annotations. i cant use main / dist because that is precompiled by babel which mangles everything. please please 🙏 this doesnt seem like it should be too hard... just need the option to alter the property to look up in package.json for resolving !

[typeofweb]

Has there been any progress on this issue?

[gluons]

Oh! module field resolving sound great! I really want separate CommonJS and ES module to each single file.

For now, I'm hacking. 😅

export default MyExport;
module.exports = exports.default;