Should ESM-only packages use the import or default condition?

[bluwy]

ESM-only packages could export as

Option 1:

{
  "type": "module",
  "exports": {
    ".": {
      "import": "./index.js"
    }
  }
}

Option 2 (can be sugar-ed, but typed verbose for comparison):

{
  "type": "module",
  "exports": {
    ".": {
      "default": "./index.js"
    }
  }
}

Question: Should option 1 or option 2 be preferred?

---

Background

With option 1, Node.js logs

Error [ERR_PACKAGE_PATH_NOT_EXPORTED]: No "exports" main defined in .../node_modules/dep/package.json

While option 2 logs:

Error [ERR_REQUIRE_ESM]: require() of ES Module /project/node_modules/index.js from /project/index.js not supported.
Instead change the require of node.js in /project/index.js to a dynamic import() which is available in all CommonJS modules.

Option 2 is a lot clear of what to fix, and I'm tempted to do option 2 everywhere too. But currently I'm doing option 1 because other environments can easily know if a package is only import-able (can't require) by resolving the exports object without hitting the fs and evaluating it.

I notice the docs is slightly leaning towards option 2 too, but not exactly as import and require conditions are not environment branches.

When using environment branches, always include a "default" condition where possible. Providing a "default" condition ensures that any unknown JS environments are able to use this universal implementation, which helps avoid these JS environments from having to pretend to be existing environments in order to support packages with conditional exports. For this reason, using "node" and "default" condition branches is usually preferable to using "node" and "browser" condition branches.

---

What to do

If option 1 is preferred, Node.js could improve the error message to check if the import condition resolved path exists when require-ing it (and vice-versa).

If option 2 is preferred, I could update https://publint.dev to check this specific case to move the ecosystem towards it.

[aduh95]

Option 3:

{
  "type": "module",
  "exports": {
    ".":  "./index.js"
  }
}

That would be the one I'd use, it's equivalent to option 2 for the error message and also simpler.

But currently I'm doing option 1 because other environments can easily know if a package is import-able by only resolving the exports object without hitting the fs.

I'm not sure what you mean by that, in Node.js "every" JS files are "importable", as it is possible to import both ESM and CJS. The fact that you list it in the "import" conditions tells nothing to the tool you're using what format the file is (i.e. "import": "./file.cjs" would be a valid export, and file.cjs would be interpreted as a CJS file).

[bluwy]

I'm not sure what you mean by that, in Node.js "every" JS files are "importable", as it is possible to import both ESM and CJS. The fact that you list it in the "import" conditions tells nothing to the tool you're using what format the file is (i.e. "import": "./file.cjs" would be a valid export, and file.cjs would be interpreted as a CJS file).

Ah I mean that it signals consumers that the library can only be import-ed, and not require-d. If I only have the "import" condition, it tells that you can't require() it regardless of the underlying file format, signalling that this library is ESM-only without needing to evaluate the file. (Updated the original post for clarity)

Re "import": "./file.cjs", I think that it communicates the intent still that it's meant to be consumed as ESM only, but also it's rare case that false positives are fine. Re option 3, I think that's what most people do too, but I'm using option 2-style for comparison for now.

[jimmywarting]

i haven't been such a huge fan of package.json lately and tough it have mostly bloated with unnecessary things...
i mean, think how http resolver works. they can't scan package.json to look for what you need... they don't take a peek in package.json

i think it better to just rader be more explicit.
just include a "type": "module" and recommend that ppl import your package like this: import x from '<pkg-name>/lib/index.js'
this makes it easier for anywho is building a bundler or a remote http resolver.

ryan dhal regretted the hole package.json, extension-less and index thing, and so do i. it's unnecessary and bloated and not how cdn works