More aggressive require(esm)

[mtharrison]

What is the problem this feature will solve?

Currently if you require(esm) from a CJS module it will only load conditionals in esm package exports: require, node, node-addons, module-sync. So if you e.g. const { delay } = require("unicorn-magic"); this will not work because exports from that package are:

{
  "node": {
    "types": "./node.d.ts",
    "import": "./node.js"
  },
  "default": {
    "types": "./default.d.ts",
    "import": "./default.js"
  }
}

The package wasn't designed with require(esm) in mind however it does work if you copy require conditions to be the same as the import conditions here.

What is the feature you are proposing to solve the problem?

For packages like the one in the example below could we also test import branches as in many case the module will load fine.

What alternatives have you considered?

No response

[ljharb]

If the package doesn’t have the same access patterns between the CJS and ESM entry points, that’s a pretty bad bug regardless of not being “designed for require(ESM)”.

iow, that package should presumably have both a named export and a module.exports property, named delay.

[Hritikk999]

Already pointed out the same reference in last week but the iow package is not cleared in the pipeline system, and due to that further codeline is blocked by system.

1. Clear the codeline blockage in pipeline.
2. Release the EOW Package.
3. Outsource pending in regulations by the node team.

[mtharrison]

The package in question is https://www.npmjs.com/package/unicorn-magic. ~19m weekly downloads and not accepting PRs.

Can you please explain a bit more what you meant by:

If the package doesn’t have the same access patterns between the CJS and ESM entry points, that’s a pretty bad bug regardless of not being “designed for require(ESM)”.

The unicorn-magic package is pure esm.

[targos]

The import condition is specifically for packages loaded with import. To be compatible with require, the package should instead use the default nested condition.

[mtharrison]

Yes that is how it should work. In reality there may be many popular packages out there with next to zero chance of being updated to follow this. I'm not questioning the best practices.

I'm just curious if we can make require(esm) more useful here by allowing it to follow other conditions (as it's already loading other code that was using import during its walk of the module graph).

[mtharrison]

Would be interested to hear @joyeecheung thoughts on this. require(esm) has been a very welcome addition and has greatly reduced friction to modernise codebases. If we can make it even more useful, for example, by allowing require(esm) to fall back to import conditions when no require branch is defined, it could significantly improve compatibility with unmaintained ESM-only packages while keeping behaviour scoped to explicit require(esm) contexts.

If there are no major technical or design concerns with this approach, I’d be happy to draft a PR implementing it behind a feature flag.

[mtharrison]

I think my issue can be tracked back to using tsx actually, as a different set of conditions are passed down to using node. Sorry about that, closing.

[darcyrush]

The import condition is specifically for packages loaded with import. To be compatible with require, the package should instead use the default nested condition.

Just for my own learning, are you saying that having only require and import is not enough for libraries? That default is also required at the same exports level for require(esm) to work?

Currently I have dual package libraries setup with the following;

  "exports": {
    ".": {
      "require": {
        "types": "./lib/cjs/index.d.cts",
        "default": "./lib/cjs/index.cjs"
      },
      "import": {
        "types": "./lib/esm/index.d.mts",
        "default": "./lib/esm/index.mjs"
      }
    }
  },
  "types": "./lib/cjs/index.d.cts",
  "main": "./lib/cjs/index.cjs",

I'm rereading the documentation but this point is not particularly clear.

[joyeecheung]

require(esm) is supported so that people can forget about the madness of the export conditions and e.g. just do

{
  "types": "./default.d.ts",
  "default": "./default.js"
}

There is no need to distinguish require and import, because both can load ESM just fine. If you still have to support older Node.js versions (which are already EOL, because active LTS ^20.19.0 || >= 22.12.0 already support it by default), you can use module-sync export condition to supply it to both require and import when the Node.js version supports it, and fall back to older export conditions on old Node.js versions, but that's supposed to be temporary and should go away when you no longer support these EOL Node.js versions.

{
  "node": {
    "types": "./node.d.ts",
    "module-sync":  "./node.js",  // recognized by ^20.19.0 || >= 22.12.0 for both require and import
     // recognized by Node.js < 20.19.0 that you will want to stop supporting at some point
    "import": "./node.js",
    "require": "..."
  },
  "default": {
    "types": "./default.d.ts",
    "import": "./default.js"
  }
}

And when you drop support for these already EOL Node.js versions (<20.19.0), or if you just don't care about them in the first place, delete those discrepancies with an engines field

"exports": {
  "types": "./default.d.ts",
  "default": "./default.js"
},
"engines": {
  // where ESM is supported for both require and import and no need to differentiate 
  "node": "^20.19.0 || >= 22.12.0"
}