Description
What does --module
actually mean?
Which of these is a better definition for the flag as it exists today? Which is a better fit for the future?
- The output module syntax you want to be emitted
- A declarative description of the module system that will process your emitted code at bundle-time or runtime
When the possible values of module
were limited to amd
, umd
, commonjs
, system
, and es2015
, the former definition was perfectly fine. When es2020
and es2022
were added, which added syntax features like import.meta
and top-level await
that couldn’t be transformed into other module emit targets besides system
, it started to feel like module
described not just an output format, but the intrinsic capabilities of some external system. With node16
and nodenext
, the scope of the module
flag suddenly expanded to include a new module format detection algorithm used by the target module system and special interop rules between module formats, while it stopped directly controlling the output format, since the format of every output file would be fully determined by Node.js’s format detection algorithm.
The latter interpretation of module
, one that fully describes the target module system, works well for node16
/nodenext
, but trying to project that definition onto the other, older module
values makes them feel kind of incoherent.
All the values except node16
/nodenext
are kind of weird
Some of the important characteristics of the module system described by --module nodenext
are:
- Multiple module formats are supported (CJS/ESM)
- The module format of each file is determined via some algorithm
- Modules of different formats interact with each other in specific ways
If we try to infer from existing what the other module
values say about these characteristics, the result is confusing. For example, you might expect that --module esnext
means an ESM-only module system that must reject CommonJS/AMD/System modules—after all, you’re not allowed to write import foo = require("./mod")
in that mode. But you are allowed to import a dependency that declares CommonJS constructs like that.
None of these module
modes have any restriction on the kinds of modules that can be imported, nor do they particularly make any effort to detect what kind of module a dependency is. Essentially, type checking between modules proceeds as if everything is CommonJS, even when we’re explicitly emitting esnext
. This can be observed direclty by writing a default import of a .d.ts
file that only declares named exports:
// @module: esnext
// @esModuleInterop: true
// @Filename: /esm.d.ts
export const x: string;
// @Filename: /main.ts
import esm from "./esm";
esm.x; // string, no error, what??
This behavior is enabled by esModuleInterop
/allowSyntheticDefaultImports
, but those settings should only affect how the exports of CommonJS modules appear (and arguably only to imports written other CommonJS modules, since esModuleInterop
is an emit setting that only emits code into CommonJS outputs). There’s no attempt to distinguish between what happens when two ES modules interact, two CJS modules interact, or an ES module imports a CJS module. This is perhaps, historically, because we had no idea what the actual module format of the JS file described by the declaration file is. (It would have been really nice for declaration emit to have always encoded the output module format, but here we are.)
Even if we had perfect information about the module format of every file, the distinction between I want to emit ESM and My module system can only handle ESM is potentially useful, and these old module
modes can only describe the former. Essentially, they all describe the same hypothetical module system, where any module format can be loaded interchangeably.
Supporting bundlers
Webpack and esbuild vary their handling of ESM→CJS imports based on whether the importing file would be recognized as ESM according to Node.js’s module format detection algorithm. According to the node16
/nodenext
prior art, the module
flag is the trigger that should enable this behavior.1 Unlike in Node.js, files in these bundlers’ module systems are not always unambiguously ESM or CJS. When a file has a .ts
/.js
extension, and the ancestor package.json doesn’t have a "type"
field at all, they’re not treated as CJS; they just don’t get the aforementioned special Node.js-compatible import behavior.
Other bundlers don’t implement this Node.js compatibility behavior (at least by default). They’re already fairly well served by --module esnext
, with the exception of the bug described in the previous section (#54752). It seems like we could improve on all the older module
modes by including file extension and package.json "type"
fields as a heuristic for when a default export of should be synthesized, and to avoid emitting syntax into .mjs
or .cjs
files that would be invalid in Node.js. (#50647, #54573)
Options
Decisions I think are on the table:
- Should we make at least one new
module
value for bundlers? - Should we make two new
module
values for bundlers, one for Webpack/esbuild (Node.js-style interop) and one for all others? Or, should the Node.js-style interop behavior be triggered by a separate flag? - Should we add module format detection heuristics to the old
module
values to fix #54752, #50647, and #54573, or deprecate them in favor of new ones? - If we deprecate old
module
values, what new ones do we actually need? - Instead of encoding everything significant into
module
, would it be better to have a more granular set of flags describing what formats are supported, how they interoperate, what output format to emit (when ambiguous via detection), and what ECMAScript spec version is supported?
My proposed minimal change:
- Add (completely bikesheddable names, I hate them)
--module bundler
and--module bundler-node-compatible
, or--module bundler
and another flag enabling Node.js-compatible interop. Ignore everything else.
Why I’d rather rethink module
as a whole than do the minimal change:
- I want to be able to give a single coherent explanation of what
module
means for documentation purposes. - Emitting conflicting syntax into
.mjs
and.cjs
files is a pretty bad behavior, and we should fix or deprecate every mode that does it. - #54752
- In the future, we may want to make a true ESM-only
module
mode to represent the browser or another future runtime, and it’s annoying that--module esnext
is a poor fit for that.
Footnotes
-
Today, the module format detection (the setting of
impliedNodeFormat
) is actually triggered bymoduleResolution
, notmodule
, but I think this doesn‘t make sense. Makemodule
controlimpliedNodeFormat
andmoduleResolution
control just module resolution #54788 swaps the trigger, and that change can go unnoticed since we already mademoduleResolution: nodenext
andmodule: nodenext
inseparable at Require module/moduleResolution to match when either is node16/nodenext #54567. ↩