Skip to content

Rethinking module for the present and the future #55221

Open
@andrewbranch

Description

@andrewbranch

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?

  1. The output module syntax you want to be emitted
  2. 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

  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. Make module control impliedNodeFormat and moduleResolution control just module resolution #54788 swaps the trigger, and that change can go unnoticed since we already made moduleResolution: nodenext and module: nodenext inseparable at Require module/moduleResolution to match when either is node16/nodenext #54567.

Metadata

Metadata

Assignees

Labels

In DiscussionNot yet reached consensusNeeds ProposalThis issue needs a plan that clarifies the finer details of how it could be implemented.SuggestionAn idea for TypeScript

Type

No type

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions