What Does --module Mean?

#55221

// src/index.ts
import dep from "./dep";

console.log(dep);
console.log(dep.toUpperCase());

// src/dep.js
Object.defineProperty(exports, "__esModule", { value: true });
exports.default = "my default export!";

// tsconfig.json
{
    "compilerOptions": {
        "module": "esnext",
        "moduleResolution": "bundler"
    }
}

• Tends to work with most bundlers, TypeScript thinks this is fine.
• Change to index.mts, TypeScript is still fine with this; but most bundlers will change their behavior and you'll get a runtime error.

  • console.log(import_dep.default.toUpperCase())
                                   ^
    TypeError: import_dep.default.toUpperCase is not a function
    

• --module esnext is not adequate to describe behaviors.
• So what does the module flag mean? Two competing definitions:
  1. Purely, what output syntax do you want?
  2. How is this module going to get understood by a runtime or bundler?
• Does --verbatimModuleSyntax true guide us at all?
  • Not exactly.
• moduleResolution affecting module format is a big part of the issue here.
• We are simultaneously not robust enough to model every environment, but also too robust to model every behavior.
• Could we ship those advanced options as well-known target environments?
  • Some of these runtimes and bundlers ship so often that...can we?
• What is a "web" environment? Tie it to a year?
  • Isn't that --module esnext?
    • No, no way to disallow CJS and the like.
• Related to "how do these old modes understand new file extensions?" and the like.
  • Design Meeting Notes, 1/13/2023 #52229
• Could imagine a change where in all modes we start respecting the module format a lot more strictly.
  • Something that resolves to ESM from CJS should error under the node10 mode.
• If we had a world where ESM files would stop emitting to CJS - do we have an appetite for that? Without waiting until 6.0 or something like that?
  • Well today what happens if you punt all projects from node10 to node16?
  • A bunch of issues with incorrect resolutions. 🎭
    • Oh right.