"commonjs"<\/code>.<\/p>\n{<\/span>\r\n <\/span>"name"<\/span>: <\/span>"my-package"<\/span>,<\/span>\r\n <\/span>"type"<\/span>: <\/span>"module"<\/span>,<\/span>\r\n\r\n <\/span>"\/\/"<\/span>: <\/span>"..."<\/span>,<\/span>\r\n <\/span>"dependencies"<\/span>: {<\/span>\r\n }<\/span>\r\n}<\/span>\r\n<\/code><\/pre>\nThis setting controls whether .js<\/code> files are interpreted as ES modules or CommonJS modules, and defaults to CommonJS when not set.\nWhen a file is considered an ES module, a few different rules come into play compared to CommonJS:<\/p>\n\nimport<\/code>\/export<\/code> statements (and top-level await<\/code> in nodenext<\/code>) can be used.<\/li>\n- Relative import paths need full extensions (we have to write
import ".\/foo.js"<\/code> instead of import ".\/foo"<\/code>).<\/li>\n- Imports might resolve differently from dependencies in
node_modules<\/code>.<\/li>\n- Certain global-like values like
require()<\/code> and process<\/code> cannot be used directly.<\/li>\n- CommonJS modules get imported under certain special rules.<\/li>\n<\/ul>\n
We’ll come back to some of these.<\/p>\n
To overlay the way TypeScript works in this system, .ts<\/code> and .tsx<\/code> files now work the same way.\nWhen TypeScript finds a .ts<\/code>, .tsx<\/code>, .js<\/code>, or .jsx<\/code> file, it will walk up looking for a package.json<\/code> to see whether that file is an ES module, and use that to determine:<\/p>\n\n- how to find other modules which that file imports<\/li>\n
- and how to transform that file if producing outputs<\/li>\n<\/ul>\n
When a .ts<\/code> file is compiled as an ES module, ECMAScript import<\/code>\/export<\/code> statements are left alone in the .js<\/code> output;\nwhen it’s compiled as a CommonJS module, it will produce the same output you get today under --module commonjs<\/code>.<\/p>\nThis also means paths resolve differently between .ts<\/code> files that are ES modules and ones that are CJS modules.\nFor example, let’s say you have the following code today:<\/p>\n\/\/ .\/foo.ts<\/span>\r\nexport<\/span> <\/span>function<\/span> <\/span>helper<\/span>() {<\/span>\r\n <\/span>\/\/ ...<\/span>\r\n}<\/span>\r\n\r\n\/\/ .\/bar.ts<\/span>\r\nimport<\/span> { <\/span>helper<\/span> } <\/span>from<\/span> <\/span>".\/foo"<\/span>; <\/span>\/\/ only works in CJS<\/span>\r\n\r\nhelper<\/span>();<\/span>\r\n<\/code><\/pre>\nThis code works in CommonJS modules, but will fail in ES modules because relative import paths need to use extensions.\nAs a result, it will have to be rewritten to use the extension of the output<\/em> of foo.ts<\/code> – so bar.ts<\/code> will instead have to import from .\/foo.js<\/code>.<\/p>\n\/\/ .\/bar.ts<\/span>\r\nimport<\/span> { <\/span>helper<\/span> } <\/span>from<\/span> <\/span>".\/foo.js"<\/span>; <\/span>\/\/ works in ESM & CJS<\/span>\r\n\r\nhelper<\/span>();<\/span>\r\n<\/code><\/pre>\nThis might feel a bit cumbersome at first, but TypeScript tooling like auto-imports and path completion will typically just do this for you.<\/p>\n
One other thing to mention is the fact that this applies to .d.ts<\/code> files too.\nWhen TypeScript finds a .d.ts<\/code> file in package, it is interpreted based on the containing package.<\/p>\nNew File Extensions<\/h3>\n
The type<\/code> field in package.json<\/code> is nice because it allows us to continue using the .ts<\/code> and .js<\/code> file extensions which can be convenient;\nhowever, you will occasionally need to write a file that differs from what type<\/code> specifies.\nYou might also just prefer to always be explicit.<\/p>\nNode.js supports two extensions to help with this: .mjs<\/code> and .cjs<\/code>.\n.mjs<\/code> files are always ES modules, and .cjs<\/code> files are always CommonJS modules, and there’s no way to override these.<\/p>\nIn turn, TypeScript supports two new source file extensions: .mts<\/code> and .cts<\/code>.\nWhen TypeScript emits these to JavaScript files, it will emit them to .mjs<\/code> and .cjs<\/code> respectively.<\/p>\nFurthermore, TypeScript also supports two new declaration file extensions: .d.mts<\/code> and .d.cts<\/code>.\nWhen TypeScript generates declaration files for .mts<\/code> and .cts<\/code>, their corresponding extensions will be .d.mts<\/code> and .d.cts<\/code>.<\/p>\nUsing these extensions is entirely optional, but will often be useful even if you choose not to use them as part of your primary workflow.<\/p>\n
CommonJS Interop<\/h3>\n
Node.js allows ES modules to import CommonJS modules as if they were ES modules with a default export.<\/p>\n
\/\/ .\/foo.cts<\/span>\r\nexport<\/span> <\/span>function<\/span> <\/span>helper<\/span>() {<\/span>\r\n <\/span>console<\/span>.<\/span>log<\/span>(<\/span>"hello world!"<\/span>);<\/span>\r\n}<\/span>\r\n\r\n\/\/ .\/bar.mts<\/span>\r\nimport<\/span> <\/span>foo<\/span> <\/span>from<\/span> <\/span>".\/foo.cjs"<\/span>;<\/span>\r\n\r\n\/\/ prints "hello world!"<\/span>\r\nfoo<\/span>.<\/span>helper<\/span>();<\/span>\r\n<\/code><\/pre>\nIn some cases, Node.js also synthesizes named exports from CommonJS modules, which can be more convenient.\nIn these cases, ES modules can use a "namespace-style" import (i.e. import * as foo from "..."<\/code>), or named imports (i.e. import { helper } from "..."<\/code>).<\/p>\n\/\/ .\/foo.cts<\/span>\r\nexport<\/span> <\/span>function<\/span> <\/span>helper<\/span>() {<\/span>\r\n <\/span>console<\/span>.<\/span>log<\/span>(<\/span>"hello world!"<\/span>);<\/span>\r\n}<\/span>\r\n\r\n\/\/ .\/bar.mts<\/span>\r\nimport<\/span> { <\/span>helper<\/span> } <\/span>from<\/span>