\n
{<\/span>\r\n \"name\"<\/span>: \"my-package\"<\/span>,<\/span>\r\n \"type\"<\/span>: \"module\"<\/span>,<\/span>\r\n\r\n \"\/\/\"<\/span>: \"...\"<\/span>,<\/span>\r\n \"dependencies\"<\/span>: {<\/span>\r\n }<\/span>\r\n}<\/span><\/pre>\n<\/div>\nThis setting controls whether\u00a0.js<\/code>\u00a0files are interpreted as ES modules or CommonJS modules, and defaults to CommonJS when not set. When a file is considered an ES module, a few different rules come into play compared to CommonJS:<\/p>\n\nimport<\/code>\/export<\/code>\u00a0statements (and top-level\u00a0await<\/code>\u00a0in\u00a0nodenext<\/code>) can be used<\/li>\n- relative import paths need full extensions (we have to write\u00a0
import \".\/foo.js\"<\/code>\u00a0instead of\u00a0import \".\/foo\"<\/code>)<\/li>\n- imports might resolve differently from dependencies in\u00a0
node_modules<\/code><\/li>\n- certain global-like values like\u00a0
require()<\/code>\u00a0and\u00a0process<\/code>\u00a0cannot 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,\u00a0.ts<\/code>\u00a0and\u00a0.tsx<\/code>\u00a0files now work the same way. When TypeScript finds a\u00a0.ts<\/code>,\u00a0.tsx<\/code>,\u00a0.js<\/code>, or\u00a0.jsx<\/code>\u00a0file, it will walk up looking for a\u00a0package.json<\/code>\u00a0to 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\u00a0.ts<\/code>\u00a0file is compiled as an ES module, ECMAScript\u00a0import<\/code>\/export<\/code>\u00a0syntax is left alone in the\u00a0.js<\/code>\u00a0output; when it’s compiled as a CommonJS module, it will produce the same output you get today under\u00a0--module commonjs<\/code>.<\/p>\nWhat this also means is that resolving paths works differently in .ts<\/code> files that are ES modules than they do in ES modules. For example, let’s say you have the following code today:<\/p>\n\n
\/\/ .\/foo.ts<\/span>\r\nexport<\/span> function<\/span> helper<\/span>(<\/span>)<\/span> {<\/span>\r\n \/\/ ...<\/span>\r\n}<\/span>\r\n\r\n\/\/ .\/bar.ts<\/span>\r\nimport<\/span> {<\/span> helper<\/span> }<\/span> from<\/span> \".\/foo\"<\/span>;<\/span> \/\/ only works in CJS<\/span>\r\n\r\nhelper<\/span>(<\/span>)<\/span>;<\/span><\/pre>\n<\/div>\nThis code works in CommonJS modules, but will fail in ES modules because relative import paths need to use extensions. As a result, it will have to be rewritten to use the extension of the\u00a0output<\/em>\u00a0of\u00a0foo.ts<\/code>\u00a0– so\u00a0bar.ts<\/code>\u00a0will instead have to import from\u00a0.\/foo.js<\/code>.<\/p>\n\n
\/\/ .\/bar.ts<\/span>\r\nimport<\/span> {<\/span> helper<\/span> }<\/span> from<\/span> \".\/foo.js\"<\/span>;<\/span> \/\/ works in ESM & CJS<\/span>\r\n\r\nhelper<\/span>(<\/span>)<\/span>;<\/span><\/pre>\n<\/div>\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\u00a0.d.ts<\/code>\u00a0files too. When TypeScript finds a\u00a0.d.ts<\/code>\u00a0file in package, it is interpreted based on the containing package.<\/p>\nNew File Extensions<\/h3>\n
The\u00a0type<\/code>\u00a0field in\u00a0package.json<\/code>\u00a0is nice because it allows us to continue using the\u00a0.ts<\/code>\u00a0and\u00a0.js<\/code>\u00a0file extensions which can be convenient; however, you will occasionally need to write a file that differs from what\u00a0type<\/code>\u00a0specifies. You might also just prefer to always be explicit.<\/p>\nNode.js supports two extensions to help with this:\u00a0.mjs<\/code>\u00a0and\u00a0.cjs<\/code>.\u00a0.mjs<\/code>\u00a0files are always ES modules, and\u00a0.cjs<\/code>\u00a0files are always CommonJS modules, and there’s no way to override these.<\/p>\nIn turn, TypeScript supports two new source file extensions:\u00a0.mts<\/code>\u00a0and\u00a0.cts<\/code>. When TypeScript emits these to JavaScript files, it will emit them to\u00a0.mjs<\/code>\u00a0and\u00a0.cjs<\/code>\u00a0respectively.<\/p>\nFurthermore, TypeScript also supports two new declaration file extensions:\u00a0.d.mts<\/code>\u00a0and\u00a0.d.cts<\/code>. When TypeScript generates declaration files for\u00a0.mts<\/code>\u00a0and\u00a0.cts<\/code>, their corresponding extensions will be\u00a0.d.mts<\/code>\u00a0and\u00a0.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
\n
\/\/ .\/foo.cts<\/span>\r\nexport<\/span> function<\/span> helper<\/span>(<\/span>)<\/span> {<\/span>\r\n console<\/span>.<\/span>log<\/span>(<\/span>\"hello world!\"<\/span>)<\/span>;<\/span>\r\n}<\/span>\r\n\r\n\/\/ .\/bar.mts<\/span>\r\nimport<\/span> foo<\/span> from<\/span> \".\/foo.cjs\"<\/span>;<\/span>\r\n\r\n\/\/ prints \"hello world!\"<\/span>\r\nfoo<\/span>.<\/span>helper<\/span>(<\/span>)<\/span>;<\/span><\/pre>\n<\/div>\nIn some cases, Node.js also synthesizes named exports from CommonJS modules, which can be more convenient. In these cases, ES modules can use a “namespace-style” import (i.e.\u00a0import * as foo from \"...\"<\/code>), or named imports (i.e.\u00a0import { helper } from \"...\"<\/code>).<\/p>\n\n
\/\/ .\/foo.cts<\/span>\r\nexport<\/span> function<\/span> helper<\/span>(<\/span>)<\/span> {<\/span>\r\n console<\/span>.<\/span>log<\/span>(<\/span>\"hello world!\"<\/span>)<\/span>;<\/span>\r\n}<\/span>\r\n\r\n\/\/ .\/bar.mts<\/span>\r\nimport<\/span> {<\/span> helper<\/span> }<\/span> from<\/span> \".\/foo.cjs\"<\/span>;<\/span>\r\n\r\n\/\/ prints \"hello world!\"<\/span>\r\nfoo<\/span>.<\/span>helper<\/span>(<\/span>)<\/span>;<\/span><\/pre>\n<\/div>\nThere isn’t always a way for TypeScript to know whether these named imports will be synthesized, but TypeScript will err on being permissive and use some heuristics when importing from a file that is definitely a CommonJS module.<\/p>\n
One TypeScript-specific note about interop is the following syntax:<\/p>\n
\n
import<\/span> foo<\/span>