Erroneous recommendation for types exports

[Conaclos]

Hi!

Linting my project with publint raises a warning: the linter recommend adding a types exports.

However, if I follow this recommendation, this creates an issue according to a linter of TypeScript team member: "Types are ESM, but implementation is CJS.". The only way to correctly export types when dual publishing cjs and esm is to remove the types exports and adding .d.cts / .d.ts / .d.mts along with corresponding files.

I understand the reasoning behind requiring types exports.
publint could detect dual publishing and then, in this particular case, recommend removing types exports.

[Conaclos]

Another solution could be requiring two types exports:

  "exports": {
      "require": {
        "types": "./dist/index.d.cts",
        "default": "./dist/index.cjs"
      },
      "types": "./dist/index.d.ts",
      "default": "./dist/index.js"
  },

[bluwy]

Hmm, yeah I think I missed checking for the adjacent .d.ts, .d.cts, .d.mts when checking the lint rule.

Doing the opposite is an interesting idea. I don't particularly like that TypeScript wants people to publish .d.ts, .d.cts, .d.mts files separately, as if publishing types couldn't be harder. But anyways if anyone wants to contribute that, I wouldn't oppose it 🥲

[nvie]

Yeah, this is something that many packages are doing wrong, and it gets worse because most packages just cargo cult off of what other (popular) packages are doing.

I think it would hugely help if what @Conaclos is proposing were the recommended approach.

Basically, if you have a require and an import, then I believe it's always a bug if you have a types condition at the same level, too. It would be nice to add a lint rule that forbids this.

Reasoning:

• require and import cannot use the same file extension (because, if they did then CJS would be masquerading as ESM, or vice versa)
• Because require and import have different file extensions, their type definitions must also have different type files

The solution, which would be nice to recommend as a best practice:

{
  "exports": {
    ".": {
      "require": {
        "types": "./dist/index.d.ts",
        "default": "./dist/index.js",
      },
      "import": {
        "types": "./dist/index.d.mts",
        "default": "./dist/index.mjs",
      },
    }
  }
}

[bluwy]

Yeah being able to detect those cases would be good. I had a small debate with Andrew and it's largely the reason why I didn't really push this. But at this point, I'm willing to have some sort of fix since it's what TS has set in stone.

I'm still somewhat on the side that having types, import, and require on the same level isn't always a bug though. A library could decide to only provide types for ESM or CJS. In this case, we can add information instead that the types will only work in ESM or CJS.

In the original issue, we can update our message more if the library exports both ESM and CJS. And also omit the warning if the the file has adjacent dts file (Maybe still good to recommend an explicit types condition instead? Just fix the recommendation to insert in the right condition nested)

[Conaclos]

Basically, if you have a require and an import, then I believe it's always a bug if you have a types condition at the same level, too. It would be nice to add a lint rule that forbids this.

Not necessarily: order is important. I am currently using the following approach:

  "exports": {
    "./package.json": "./package.json",
    ".": {
      "require": {
        "types": "./dist/index.d.cts",
        "default": "./dist/index.cjs"
      },
      "types": "./dist/index.d.ts",
      "module": "./dist/index.js",
      "default": "./dist/index.js"
    }
  },

[nvie]

I'm still somewhat on the side that having types, import, and require on the same level isn't always a bug though. A library could decide to only provide types for ESM or CJS. In this case, we can add information instead that the types will only work in ESM or CJS.

That's true. I agree, and providing a hint that the types won't work in one or the other would be nice to make it clear (because perhaps that's not the author's intention).

In the original issue, we can update our message more if the library exports both ESM and CJS. And also omit the warning if the the file has adjacent dts file (Maybe still good to recommend an explicit types condition instead? Just fix the recommendation to insert in the right condition nested)

Agreed!

Not necessarily: order is important. I am currently using the following approach:

A-ha, I see @Conaclos! Are you not getting the "types must come first" error? I was operating under the assumption that "types" would have to be defined before "require" according to the existing publint rule. If this setup doesn't lead to a linting error, then I agree this is also an option and it's indeed not always a bug.

[nvie]

Btw, @Conaclos – I just contributed a rule last weekend that will fail on your "module" line. In this setup, I would recommend changing to:

{
  "exports": {
    "./package.json": "./package.json",
    ".": {
      "require": {
        "types": "./dist/index.d.cts",
        "module": "./dist/index.js",  // 👈 Move it to here, maybe?
        "default": "./dist/index.cjs"
      },
      "types": "./dist/index.d.ts",
      "default": "./dist/index.js"
    }
  },
}

[Hebilicious]

Fix that is possibly related landed here #47

[bluwy]

Yeah, the "types must come first" with import and require conditions is fixed at #47 (if require or import has it's own types nested). I think this issue is more specific to the recommendation detection, where:

1. It has pkg.types
2. But doesn't have pkg.exports.types

Since "moduleResolution": "bundler" would ignore pkg.types altogether. So we recommend some hints so bundler works, in this case the hints aren't perfect for dual publishing.

[Conaclos]

Btw, @Conaclos – I just #49 that will fail on your "module" line. In this setup, I would recommend changing to:

module is bundler-specific condition (supported by webpack, esbuild, and others). It should not be in require.
By the way, I am not sure if module must be placed before require.
module makes sense only for ESM? In this case the bundlers skip require?

So hard to get right...

Otherwise this could be as follows:

  "exports": {
    "./package.json": "./package.json",
    ".": {
      "module": "./dist/index.js",
      "require": {
        "types": "./dist/index.d.cts",
        "default": "./dist/index.cjs"
      },
      "types": "./dist/index.d.ts",
      "default": "./dist/index.js"
    }
  },

[nvie]

So hard to get right...

You can say that again! 🥵

module is bundler-specific condition (supported by webpack, esbuild, and others). It should not be in require. By the way, I am not sure if module must be placed before require. module makes sense only for ESM? In this case the bundlers skip require?

Not sure if that's true! Maybe it is? Now I don't know anymore 🥴

My understanding is that bundlers activate the module condition as well as import and require (depending on which construct is used to include the referenced module). So if a bundler encounters a require('xxx') call, they will normally resolve to index.cjs (through the require condition that they activated). Similarly, if they encounter an import "xxx" statement, they will normally resolve to index.mjs (through the import condition that they activated).

But bundlers also activate the module condition, so that you have the opportunity to influence and let them use the ESM module instead of the CJS module they would normally resolve to.

So assume that you have this:

{
  "exports": {
    ".": {
      "require": {
        "types": "./dist/index.d.cts",
        "module": "./dist/index.js",
        "default": "./dist/index.cjs"
      },
      "types": "./dist/index.d.ts",
      "default": "./dist/index.js"
    }
  },
}

And your bundler processes this source code:

const x = require('xxx');

1. Bundler sets require condition and module condition
2. Scanning top-to-bottom finds first match at pkg.exports.require.module → resolves to ./dist/index.js (an ESM module!)
3. This is fine in a bundler context only, because bundlers possess the special power to require() an ESM module (unlike Node)

Similarly, if your bundler processes this source code:

import * as x from 'xxx';

1. Bundler sets import condition and module condition
2. Top-to-bottom scanning happens.
3. Skips over pkg.exports.require, because require condition isn't met
4. Skips over pkg.exports.types, because types condition isn't met
5. Finds pkg.exports.default → resolves to ./dist/index.js (also an ESM module!)

---

Maybe I'm wrong, but this is how I thought it works.

[nvie]

Btw, I'm mostly basing my understanding of this from the "How conditions work" section in the esbuild documentation. These parts in particular:

[bluwy]

I've fixed this in 28f1ec3 and 325b59f. I've walked back a bit on this:

I'm still somewhat on the side that having types, import, and require on the same level isn't always a bug though.

publint will now warn (for the root export only), if import and require both exist. Better to avoid bias wherever possible 😬

You can start testing this out in https://publint.dev now. The site is updated but the package isn't published yet. Since this might affect many projects using publint --strict, I'm holding off the release a bit until tonight to write a better release note.

Closing this as fixed.

[bluwy]

This is now published in v0.2.0