Improve documentation on Dual Module Packages

[MicahZoltu]

• Version: v14.4.0
• Platform: Windows 10
• Subsystem: Windows

What steps will reproduce the bug?

git clone git@github.com:MicahZoltu/dual-module-package-repro.git
cd dual-module-package-repro/app-package
npm install
node index.mjs
# notice it works
node index.cjs
# notice it does not work

Then remove "type": "module" from library-package/package.json and repeat the process:

npm install
node index.mjs
# notice it doesn't work
node index.cjs
# notice it does work

How often does it reproduce? Is there a required condition?

Always.

What is the expected behavior?

The ability to ship an NPM package that can be used by either CJS users (any version of NodeJS) or ESM users (running NodeJS 14+)

What do you see instead?

I can either define type: module and it will work as an ESM, or I can not define it or set it to CommonJS and it will work as a CJS module, but I cannot define the package.json such that the package works in both environments.

Additional information

The error indicates that NodeJS is correctly following the exports path and locating the right module in each situation, however it proceeds to load the module using a loader picked by the presence of the type property in package.json. My expectation is that if it loads via the exports: { import: ... } entrypoint then that entire call stack from there down should be ESM, and if it loads via exports: { require: ... } then the entire call stack from there down should be CJS.

Error when type: module is not set:

dual-module-package-repro\library-package\index-esm.js:1
export const apple = 'apple'
^^^^^^

SyntaxError: Unexpected token 'export'
    at wrapSafe (internal/modules/cjs/loader.js:1116:16)

Error when type: module is set:

internal/modules/cjs/loader.js:1216
      throw new ERR_REQUIRE_ESM(filename, parentPath, packageJsonPath);
      ^

Error [ERR_REQUIRE_ESM]: Must use import to load ES Module: ...\dual-module-package-repro\library-package\index-cjs.js
require() of ES modules is not supported.
require() of ...\dual-module-package-repro\library-package\index-cjs.js from ...\dual-module-package-repro\app-package\index.cjs is an ES module file as it is a .js file whose nearest parent package.json contains "type": "module" which defines all .js files in that package scope as ES modules.
Instead rename index-cjs.js to end in .cjs, change the requiring code to use import(), or remove "type": "module" from ...\dual-module-package-repro\library-package\package.json.

    at Object.Module._extensions..js (internal/modules/cjs/loader.js:1216:13)

---

The documentation makes it sound like NodeJS 14 supports packages that can be used as either ESM or CJS, but thus far I have not figured out how to actually accomplish this.

I believe this specific problem could be worked around by renaming files to .cjs and .mjs in the library-package. However, in the real world this solution is far less tenable because I'm compiling from TypeScript which does not do import rewrites during emit (and they maintain a very strong position that they have no intent to ever change this policy). This means that I cannot have TypeScript emit files where the import statements have different extensions depending on the module type being targeted. So in order to have everything be mjs in the ESM build output and cjs in the CJS build output I would need to run my code through a transformer that rewrites all import statements (both static and dynamic) and also rename all of the files to have extensions by output folder.

[MicahZoltu]

Note: Even if this is "not a bug", I believe the documentation could use an update to include a working example of a dual module package. Ideally, that example would be one that can be extended to be used in the real world and can work when compiling from TypeScript (i.e., an example that says to just rename all your files and all of your imports isn't particularly useful). It is also worth noting that the library should be native browser compatible as well, which means following the "MJS wrapper around CJS" pattern won't work.

[aduh95]

For reference, the library-package/package.json contains:

{
	"name": "library-package",
	"version": "1.0.0",
	"main": "./index-cjs.js",
	"exports": {
		"import": "./index-esm.js",
		"require": "./index-cjs.js"
	},
	"type": "module"
}

Setting "type": "module" makes Node.js interpret all .js files as ESM, including index-cjs.js. When you remove it, all .js files will be interpreted as CJS, including index-esm.js.
If you want to support both with .js extension, you should create two subfolders:

$ mkdir ./cjs ./esm
$ echo '{"type":"commonjs"}' > cjs/package.json
$ echo '{"type":"module"}' > esm/package.json
$ git mv index-cjs.js cjs/index.js
$ git mv index-esm.js esm/index.js

And then have your package exports point to those subfolders:

{
	"name": "library-package",
	"version": "1.0.0",
	"main": "./cjs/index.js",
	"exports": {
		"import": "./esm/index.js",
		"require": "./cjs/index.js"
	},
	"type": "module"
}

[MicahZoltu]

Are there any side effects to putting a mostly-empty package.json in a subfolder like that? When I do npm publish of the root does everything else work the same, despite the nested package.json files?

[aduh95]

Correct, npm uses only the "root" package.json file IIRC. I've used this on some of my packages, and haven't got any issue from nested package.json files.

[MicahZoltu]

I have updated the title of this to be a documentation improvement that illustrates the above thing with multiple output folders and package.json files.

[kapouer]

@MicahZoltu that's cool and here's another working example (tested with node 12):
https://github.com/miraclx/xbytes/blob/d799f659791f7473263e91732dc153d3b13f705a/package.json#L6-L9
Edit: that's

"exports": {
    "require": "./dist/index.js",
    "import": "./dist/index.mjs"
  },

Note the .mjs extension - a crucial point to make it work.
I have yet to figure out how to expose both "./package.json" along with that config.

[MicahZoltu]

@kapouer #34515 (comment) worked for me back when I tested it after learning. All of my projects now have two tsconfig.json files (since I compile from TS) which write .js files to output-esm and output-cjs folders. Each of those folders has a package.json file with a single line in it (see linked comment).

The reason I strongly prefer this way over .mjs filenames is because I can compile from TS without needing any additional tooling to rename all of my output files. I can load files from output-esm in a browser without any additional tooling, and I can execute output-esm or load it as a library in NodeJS 14+ in an ESM project.

[Venryx]

While the multiple-output-folder approach works, I do consider the OP to be a bug: the exports.import field will always be pointing to a file with ESM exports, so why does NodeJS not use that information as a "hint" to identify that specific file as ESM (ie. type: "module")?

The same sort of "missed opportunity" is true for a module: "./output.esm.js" field; NodeJS "ignores the hint", and treats the target file as commonjs, when it explicitly is not.

Taking these "hints" into account does "complicate" the interpretation process a bit -- but only a bit, and it seems worth it, to avoid the need for people to use separate output folders all the time. (or variant extensions, which has drawbacks for build tools like TypeScript)

[aduh95]

the exports.import field will always be pointing to a file with ESM exports

This was discussed recently in https://github.com/nodejs/node/discussions/38740. The gist of it is the assumption is not correct: you could pass anything to the "import" field: an ES module of course, but also a WASM module, a JSON module, or even a CJS module.

Taking these "hints" into account does "complicate" the interpretation process a bit -- but only a bit, and it seems worth it

It would actually complicate it by a lot 😅 also it brings other questions such as "what happens if those hints lead to a file being both ESM and CJS?", it would have to introduce all sorts of exception which could become tricky to document. See the linked discussion for more details.

That being said I agree we could/should use those hints when printing the error message to help users debug their package.json setup; someone in a recent PR is actually working on improving those error messages: #39175.