René's URL Explorer Experiment

{"@context":"https://schema.org","@type":"DiscussionForumPosting","headline":"Rethinking `module` for the present and the future","articleBody":"# What does `--module` actually mean?\r\n\r\nWhich of these is a better definition for the flag as it exists today? Which is a better fit for the future?\r\n\r\n1. The output module syntax you want to be emitted\r\n2. A declarative description of the module system that will process your emitted code at bundle-time or runtime\r\n\r\nWhen 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.\r\n\r\nThe 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.\r\n\r\n## All the values except `node16`/`nodenext` are kind of weird\r\n\r\nSome of the important characteristics of the module system described by `--module nodenext` are:\r\n\r\n- Multiple module formats are supported (CJS/ESM)\r\n- The module format of each file is determined via some algorithm\r\n- Modules of different formats interact with each other in specific ways\r\n\r\nIf 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.\r\n\r\nNone 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:\r\n\r\n```ts\r\n// @module: esnext\r\n// @esModuleInterop: true\r\n\r\n// @Filename: /esm.d.ts\r\nexport const x: string;\r\n\r\n// @Filename: /main.ts\r\nimport esm from \"./esm\";\r\nesm.x; // string, no error, what??\r\n```\r\n\r\nThis 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.)\r\n\r\nEven 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.\r\n\r\n## Supporting bundlers\r\n\r\nWebpack and esbuild [vary their handling of ESM→CJS imports](https://andrewbranch.github.io/interop-test/#synthesizing-default-exports-for-cjs-modules) 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.\r\n\r\nOther 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](https://github.com/microsoft/TypeScript/issues/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](https://github.com/microsoft/TypeScript/issues/50647), [#54573](https://github.com/microsoft/TypeScript/issues/54573))\r\n\r\n## Options\r\n\r\nDecisions I think are on the table:\r\n\r\n- Should we make at least one new `module` value for bundlers?\r\n- 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?\r\n- Should we add module format detection heuristics to the old `module` values to fix [#54752](https://github.com/microsoft/TypeScript/issues/54752), [#50647](https://github.com/microsoft/TypeScript/issues/50647), and [#54573](https://github.com/microsoft/TypeScript/issues/54573), or deprecate them in favor of new ones?\r\n- If we deprecate old `module` values, what new ones do we actually need?\r\n- 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?\r\n\r\nMy proposed minimal change:\r\n\r\n- 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.\r\n\r\nWhy I’d rather rethink `module` as a whole than do the minimal change:\r\n\r\n- I want to be able to give a single coherent explanation of what `module` means for documentation purposes.\r\n- Emitting conflicting syntax into `.mjs` and `.cjs` files is a pretty bad behavior, and we should fix or deprecate every mode that does it.\r\n- [#54752](https://github.com/microsoft/TypeScript/issues/54752)\r\n- 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.\r\n\r\n[^1]: Today, the module format detection (the setting of `impliedNodeFormat`) is actually triggered by `moduleResolution`, not `module`, but I think this doesn‘t make sense. #54788 swaps the trigger, and that change can go unnoticed since we already made `moduleResolution: nodenext` and `module: nodenext` inseparable at #54567.","author":{"url":"https://github.com/andrewbranch","@type":"Person","name":"andrewbranch"},"datePublished":"2023-07-31T22:23:39.000Z","interactionStatistic":{"@type":"InteractionCounter","interactionType":"https://schema.org/CommentAction","userInteractionCount":3},"url":"https://github.com/55221/TypeScript/issues/55221"}