iTranslated by AI

The content below is an AI-generated translation. This is an experimental feature, and may contain errors. View original article
⚱️

TypeScript's module Option: Developer Struggles and the Story of CJS and ESM

に公開

Hello everyone. To jump right in, are you familiar with TypeScript's module option? The module option supports values such as the following:

  • commonjs
  • umd
  • es2015
  • esnext
  • node16
  • nodenext

Can you explain in a single sentence what the module option is actually for?

In fact, even for TypeScript experts, it should be difficult to explain the module option in a single sentence. This is because the module option itself is being used in several different senses, and it has reached a point where it can no longer be explained simply.

In this article, I will explain the situation surrounding the module option based on the following GitHub issue written by a TypeScript maintainer.

https://github.com/microsoft/TypeScript/issues/55221

What is the meaning of the module option?

In the past, the meaning of the module option was clear. By "the past," I mean the time when the candidates for the module option were around commonjs, amd, system, umd, and es2015. In those days, the module option was an option to specify the format of the modules output by TypeScript.

In other words, you defined modules using import and export in your TypeScript source code, and the TypeScript compiler converted them into the format specified by the module option. If module was commonjs, import was converted to require, and export was converted to module.exports. If module was es2015, import remained import and export remained export.

Things started to get a bit complicated when module: es2022 was added. One of the new features in ES2022 is top-level await. This is a feature that allows you to write await at the top level of a module (outside of other functions). To use top-level await in TypeScript code, you need to set the module option to es2022 (you can also set it to something like node16 since Node.js also supports top-level await).

If you use top-level await with settings like module: es2015, a compilation error will occur. This is because top-level await cannot be translated into module systems like ES2015 or CommonJS.

At this point, the module option was no longer just about specifying the target module format for translation. In addition, it took on the role of controlling what you can write in your TypeScript code.

That said, at this stage, the module option could still be understood simply. If something cannot be translated even when requested, there is no choice but to make it a compilation error.

The arrival of node16-series options

The situation changed significantly when module: node16 and module: nodenext were added.

The characteristic of Node.js is that it supports both CommonJS and ES Modules. When module: node16 or similar is specified, TypeScript behaves accordingly.

  • .cts files are transpiled to .cjs files. Writing a .cts file with ES Modules syntax converts it to CommonJS.
  • .mts files are transpiled to .mjs files. Writing a .mts file with ES Modules syntax keeps it as ES Modules.
  • .ts files are transpiled to .js files, but which module system is used depends on the type field in package.json.

Unlike conventional module options that specified a particular module system, the node16-series options have a more abstract meaning: "compliant with Node.js." In reality, this involves complex requirements such as checking extensions and looking up package.json as needed.

The aforementioned issue expresses this new definition of the module option as follows:

A declarative description of the module system that will process your emitted code at bundle-time or runtime

(Rough translation) Something that declares the module system that will process the code at runtime (or bundle-time)

In other words, for node16, what you are telling the TypeScript compiler is "this code will run on Node.js," and TypeScript performs checks and transpilation accordingly.

On the other hand, this new explanation does not match conventional options (especially es2022, etc.). Conventional options merely specify syntax and do not specify the runtime on which the code will run. Therefore, even for a value like es2022 that clearly points to ES Modules, it does not mean "run on a runtime that supports only ES Modules." Traditionally, code with module: es2022 could be for Node.js, for browsers, or for consumption by a bundler. Thus, module: es2022 does not express "on what kind of system the code will run."

Here, the module option came to be used in two meanings that are similar yet different.

Problems with CJS and ESM revealed by module: node16

module: node16 is a system that supports both CJS and ESM at the same time. In fact, previously, it wasn't necessary to handle the differences between the two so seriously. Since esModuleInterop was implemented in TypeScript some time ago, the differences between CommonJS and ES Modules have been mostly absorbed, so things generally worked out without having to think about the details. On the runtime side as well, bundlers like webpack handled it well, so there wasn't much need to be conscious of the differences between CommonJS and ES Modules. However, to accurately support the Node.js module system, such a loose approach is no longer acceptable.

For example, in Node.js, you cannot require ES Modules from a CommonJS module. TypeScript also supports this check. If you try to import an .mts file from a .cts file, you will get the following compilation error:

The current file is a CommonJS module whose imports will produce 'require' calls; however, the referenced file is an ECMAScript module and cannot be imported with 'require'. Consider writing a dynamic 'import("./mts.mjs")' call instead.

Conversely, you can import a CommonJS module from ES Modules. In this case, module.exports on the CommonJS side is considered the default export[1].

What happens when importing .cts from .mts?

.cts files allow you to write in ES Modules syntax as TypeScript code, but they become CommonJS after transpilation, behaving like module: commonjs on a per-file basis. Let's look at an example of transpilation.

// a.cts
export const foo = 3;
export default 123;
// ↓↓↓ Transpilation ↓↓↓
// a.cjs
"use strict";
Object.defineProperty(exports, "__esModule", { value: true });
exports.foo = void 0;
exports.foo = 3;
exports.default = 123;

Focusing on the default export, you can see that it is exported as exports.default. This is reasonable behavior considering that ES Modules' default export is essentially equivalent to a named export with the name default.

Now, let's import this from an .mts file.

// b.mts
import a from "./a.cts";

console.log(a);

What will be displayed when you run this? Actually, it is not 123. The following result is shown:

{ foo: 3, default: 123 }

This complies with the Node.js behavior mentioned earlier. In other words, the exports object of the .cjs file is treated as the default export of the CommonJS module. While it is strange that what was export default in .cts does not directly correspond to the default import in .mts, this behavior is unavoidable if we assume compliance with Node.js specifications.

What happens if you load .cts from .cts?

By the way, the behavior when loading .cts from .cts in a module: node16 environment is the same as in module: commonjs.

// a.cts
export const foo = 3;
export default 123;
// b.cts
import a from "./a.cts";
console.log(a);

In this case, as expected, a becomes 123. The transpilation result of b.cts looks like the following, where you can see code derived from esModuleInterop.

// b.cjs
"use strict";
var __importDefault = (this && this.__importDefault) || function (mod) {
    return (mod && mod.__esModule) ? mod : { "default": mod };
};
Object.defineProperty(exports, "__esModule", { value: true });
const a_cjs_1 = __importDefault(require("./a.cjs"));
console.log(a_cjs_1.default);

CJS, ESM, and Type Definition Files

TypeScript features type definition files. Especially when distributing a library via npm, you often distribute transpiled .js files and their corresponding type definitions (like .d.ts).

First, let's look at what kind of type definition file is generated from .cts in module: node16.

// a.cts
export const foo = 3;
export default 123;
// ↓↓↓ Type Definition Generation ↓↓↓
// a.d.cts
export declare const foo = 3;
declare const _default: 123;
export default _default;

Let's consider importing this as a type definition for a separate package. For example, let's declare it as an ambient module like this:

declare module "cjs-module" {
  export const foo = 3;
  const _default: 123;
  export default _default;
}

Now, let's try to import this from .mts.

// user.mts
import a from "cjs-module";
console.log(a);
//          ^ a: 123

As you can see, the type of a is 123. This means that even though they have exactly the same type definitions, the interpretation differs between importing a .cts file within the project and importing a module defined as an ambient module.

The fundamental problem here is that even for a TypeScript program transpiled to CommonJS, its corresponding type definition remains written in ES Modules syntax, making it impossible to distinguish which module system the runtime uses just by looking at the type definition. The aforementioned issue contains the following lament:

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.)

(Rough translation) 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 it didn't happen that way.)

To support the behavior when loading CommonJS from ESM in Node.js, a determination of "whether CommonJS was loaded" is required, and that information is currently not included in the type definition itself.

When a package.json is properly present

So, do problems not occur when loading type definitions from another library? In fact, it's fine if you properly prepare a package.json.

// node_modules/cjs-module/package.json
{
  "name": "cjs-module",
  "types": "./index.d.cts"
}
// node_modules/cjs-module/index.d.cts
export declare const foo = 3;
declare const _default: 123;
export default _default;

By preparing a cjs-module installed in node_modules like this and specifying a .cts file as the type definition file, let's try to import it from .mts (you need moduleResolution: node16 to load modules from node_modules).

// user.mts
import a from "cjs-module";
console.log(a);

In this case, the type of a becomes { foo: 3; default: 123; } instead of 123. In other words, it behaves the same as when loading .cts from .mts.

Essentially, if module: node16 is specified, TypeScript will determine whether the runtime is CommonJS or ES Modules based on whether the type definition file is .cts or .mts (or the type field in package.json), even for modules within node_modules.

Relationship with Bundlers?

An even more headache-inducing problem is the recently added moduleResolution: bundler. This is an option that recreates the module resolution performed by bundlers. Roughly speaking, while it supports package.json features (like exports) similar to Node.js, it differs from Node.js in that it allows omitting file extensions.

There are various types of bundlers. And naturally, different bundlers behave differently. A particular problem is the "behavior when loading CommonJS from ESM" already explained in this article, where factions are divided based on whether they reproduce Node.js behavior or not.

The current moduleResolution: bundler is aligned with bundlers that do not reproduce Node.js behavior, so it cannot accommodate bundlers that do (specifically, webpack and esbuild). This issue is addressed in the following GitHub issue:

https://github.com/microsoft/TypeScript/issues/54102

As of the time of writing, the milestone is set for TS 5.3, but it seems to be facing difficulties.

Issues with Type Definitions and the Ecosystem

As explained earlier, module: node16 implements behavior that aligns with Node.js when loading CJS from ESM. This raises concerns about the type definitions of the many packages published before module: node16 was introduced.

Actually, if the type definitions were properly generated using TypeScript, it is surprisingly fine. TypeScript strives to maintain compatibility, so packages made before Node.js supported ESM are generally recognized correctly.

The problem is more likely to occur when type definitions are written by hand or when package.json is configured incorrectly. The latter often happens when attempting to create a "dual package." To address such issues, arethetypeswrong was created.

https://github.com/arethetypeswrong/arethetypeswrong.github.io

This tool inspects type definitions published on npm to check for issues. For example, it can detect a problem called Masquerading as CJS. This is a problem where the code is loaded as ESM at runtime via import, but the type definitions are recognized as CommonJS by TypeScript. This mainly happens when the package.json is not written correctly.

Another problem closely related to the topic of this article is Incorrect default export.

In a pure CommonJS module, the result of require() is the module.exports of the loaded module. Therefore, if you want the result of a require to be a function, you would write code like module.exports = function() { ... }.

What if the library was originally written in JavaScript and you want to add hand-written type definitions? The first thing that might come to mind is a type definition that uses export default for the function, like this:

export default function(): void;

Doing it this way is actually a mistake, and this is the "Incorrect default export" problem. This is because export default in a type definition written for a CommonJS file always defines the type of exports.default, not the type of exports itself.

This mistake did not manifest in conventional TypeScript (especially after esModuleInterop was implemented), but it becomes an issue in module: node16, which eliminates the loose handling of CommonJS and ESM. This is a common pattern for why old packages might stop working with module: node16.

By the way, the correct type definition in this case uses the export = syntax to define the type of exports itself.

const _default: () => void;
export = _default;

Handling of .cts and .mts in options other than module: node16

TypeScript introduced .cts and .mts to correspond to Node.js's .cjs and .mjs. This raises the question of how .cts and .mts are handled when the setting is not module: node16.

In fact, they aren't handled very well at the moment. Since the handling that distinguishes between CJS and ESM is specific to module: node16, in other settings, these are just regular TS files that happen to have different extensions.

Therefore, for example, using a .cts file under module: esnext can result in undesirable outcomes like the transpiled .cjs file containing export syntax, or conversely, a .mjs file written with CommonJS syntax being output under module: commonjs.

Summary: The Future of the module Option

To summarize what has been discussed so far, the introduction of module: node16 and module: nodenext has made the meaning of the module option ambiguous. module: node16 means checking that the TypeScript code (and the JS it transpiles to) runs on Node.js, which has a different nuance than the conventional module: commonjs or module: es2022.

With the support for Node.js came the concept of coexistence between CommonJS and ESM, which also introduced several issues. A specific problem is that the degree to which a bundler mimics Node.js varies. To support such bundlers, neither the existing module: node16 nor moduleResolution: bundler fits perfectly.

In other words, it is becoming difficult to sufficiently solve problems with the existing system of options, and a review is necessary.

The issue introduced at the beginning mentions the following as ideal fixes:

  • A single, consistent meaning should be given to the module option.
  • Since module settings other than node16 and nodenext do not handle .cts and .mts well, they should all be deprecated.
  • Enable support for both bundlers that mimic Node.js behavior and those that do not.
  • (In the future, create a module option to represent environments like web browsers that do not support CommonJS at all.)

In short, the direction is shifting toward module representing runtime characteristics, like node16, while rebuilding the module option on the premise that the TypeScript compiler itself recognizes the distinction between CJS and ESM. Conventional choices for module will be deprecated because they do not distinguish between CJS and ESM (i.e., they do not take runtime characteristics into account).

The issue mentions various other possibilities beyond what is written here, and these will likely be discussed in the future. When there are updates to TypeScript, reflecting on the knowledge gained from this article might help deepen your understanding.

脚注
  1. Additionally, if static analysis is successful, it is said that the properties of exports might be treated as named exports. ↩︎

GitHubで編集を提案

Discussion