Things start getting confusing when your npm package wants to support both ECMAScript Modules (ESM) and CommonJS (CJS), which makes it a dual-package.<\/p>\n
Assume we have a package whose file structure looks like this:<\/p>\n
.\/\n\u251c\u2500\u2500 src\/\n\u2502 \u251c\u2500\u2500 shared\/\n\u2502 \u2502 \u2514\u2500\u2500 index.ts\n\u2502 \u251c\u2500\u2500 node\/\n\u2502 \u2502 \u251c\u2500\u2500 cli.ts\n\u2502 \u2502 \u251c\u2500\u2500 index.cts\n\u2502 \u2502 \u2514\u2500\u2500 index.ts\n\u2502 \u2514\u2500\u2500 browser\/\n\u2502 \u251c\u2500\u2500 pangu.ts\n\u2502 \u2514\u2500\u2500 pangu.umd.ts\n\u251c\u2500\u2500 dist\/\n\u2502 \u251c\u2500\u2500 shared\/\n\u2502 \u2502 \u2514\u2500\u2500 index.js\n\u2502 \u251c\u2500\u2500 node\/\n\u2502 \u2502 \u251c\u2500\u2500 cli.js\n\u2502 \u2502 \u251c\u2500\u2500 index.cjs\n\u2502 \u2502 \u2514\u2500\u2500 index.js\n\u2502 \u2514\u2500\u2500 browser\/\n\u2502 \u251c\u2500\u2500 pangu.js\n\u2502 \u2514\u2500\u2500 pangu.umd.js\n\u2514\u2500\u2500 package.json<\/code><\/pre>\nEntry Points<\/h2>\n
Let's start from package.json<\/code>. Here is a simplified one from pangu.js<\/a>:<\/p>\n{\n \"name\": \"pangu\",\n ...\n \"type\": \"module\",\n \"exports\": {\n \".\": {\n \"import\": {\n \"types\": \".\/dist\/node\/index.d.ts\",\n \"default\": \".\/dist\/node\/index.js\"\n },\n \"require\": {\n \"types\": \".\/dist\/node\/index.d.cts\",\n \"default\": \".\/dist\/node\/index.cjs\"\n }\n }\n },\n ...\n}<\/code><\/pre>\nSimply speaking, the entry points of a package are (usually) defined in package.json<\/code>'s exports<\/code> field:<\/p>\n\nimport xxx from "pangu"<\/code> matches the "import"<\/code> branch, which loads .\/dist\/node\/index.js<\/code> => ESM<\/li>\nrequire("pangu")<\/code> matches the "require"<\/code> branch, which loads .\/dist\/node\/index.cjs<\/code> => CommonJS<\/li>\n<\/ul>\nCondition Matching Order<\/h3>\n
In the above package.json<\/code>, you may have noticed that every branch puts "types"<\/code> first. That's not a style choice.<\/p>\nWithin the exports<\/code> object, key order is significant<\/strong>. During condition matching, the resolver (Node.js, TypeScript, or any bundler) walks the object from top to bottom, takes the first key it recognizes, then stops. Everything below the winner is ignored.<\/p>\n\n"types"<\/code> must go first<\/strong>, so that TypeScript always sees your .d.ts<\/code><\/li>\n"default"<\/code> must go last<\/strong>. Anything you list after it is unreachable<\/li>\n<\/ul>\nref:
\nhttps:\/\/nodejs.org\/api\/packages.html#conditional-exports<\/a>
\nhttps:\/\/www.typescriptlang.org\/docs\/handbook\/modules\/reference.html#packagejson-exports<\/a><\/p>\nECMAScript Modules (ESM)<\/h2>\n
ESM is the current standard module system in the JavaScript specification. You should really consider using it if you're not.<\/p>\n
A piece of code is an ECMAScript module if any of the following is true:<\/p>\n
\n- A file ends with
.mjs<\/code> or .mts<\/code><\/li>\n- A file ends with
.js<\/code> or .ts<\/code> AND package.json<\/code> has "type": "module"<\/code>\n\n- When
tsconfig.json<\/code> sets "module": "esnext"<\/code> or "moduleResolution": "bundler"<\/code>, every .ts<\/code> file is treated as ESM no matter what "type"<\/code> says<\/li>\n<\/ul>\n<\/li>\n- Inside a
<script type="module"><\/code> tag<\/li>\n<\/ul>\n\/\/ export\nexport class NodePangu {}\nexport const pangu = new NodePangu();\nexport default pangu;\n\n\/\/ import from a file (inside the same package)\nimport { Pangu } from '..\/shared\/index.js'; \/\/ relative imports need the extension in ESM, and you write .js even though the source file is index.ts\n\n\/\/ import from a package\nimport pangu from 'pangu'; \/\/ it loads .\/dist\/node\/index.js according to package.json[\"exports\"][\".\"][\"import\"][\"default\"]\nimport { pangu, NodePangu } from 'pangu';<\/code><\/pre>\nThe mapping:<\/p>\n
\nexport default pangu;<\/code> => import pangu from 'pangu';<\/code><\/li>\nexport const pangu = new NodePangu();<\/code> => import { pangu } from 'pangu';<\/code><\/li>\nexport class NodePangu {}<\/code> => import { NodePangu } from 'pangu';<\/code><\/li>\n<\/ul>\nref:
\nhttps:\/\/www.typescriptlang.org\/docs\/handbook\/2\/modules.html<\/a>
\nhttps:\/\/nodejs.org\/api\/esm.html<\/a><\/p>\nSubpath Exports<\/h2>\n
You just define an extra key in exports<\/code>, .\/browser<\/code> in our case:<\/p>\n{\n \"name\": \"pangu\",\n ...\n \"type\": \"module\",\n \"exports\": {\n \".\": {\n ...\n },\n \".\/browser\": {\n \"import\": {\n \"types\": \".\/dist\/browser\/pangu.d.ts\",\n \"default\": \".\/dist\/browser\/pangu.js\"\n }\n }\n },\n ...\n}<\/code><\/pre>\nThe export<\/code> part is the same, but you will need to add the subpath<\/strong> (\/browser<\/code>) when importing.<\/p>\n\/\/ export\nexport class BrowserPangu {}\nexport const pangu = new BrowserPangu();\nexport default pangu;\n\n\/\/ import from a package\nimport pangu from 'pangu\/browser'; \/\/ it loads .\/dist\/browser\/pangu.js according to package.json[\"exports\"][\".\/browser\"][\"import\"][\"default\"]\nimport { pangu, BrowserPangu } from 'pangu\/browser';<\/code><\/pre>\nIt's worth noting that in ESM, only relative<\/strong> imports must include the file extension (.js<\/code>, .cjs<\/code>, or .mjs<\/code>), because they are resolved as plain URLs with no extension guessing. Package names like pangu<\/code> and pangu\/browser<\/code> don't need one, since they are resolved through the exports<\/code> field instead of the filesystem.<\/p>\nCommonJS<\/h2>\n
CommonJS is an old but still widely used module system, especially in the Node.js ecosystem.<\/p>\n
A piece of code is a CommonJS module if any of the following is true:<\/p>\n
\n- A file ends with
.cjs<\/code> or .cts<\/code><\/li>\n- A file ends with
.js<\/code> or .ts<\/code> AND package.json<\/code> has "type": "commonjs"<\/code> (or has no "type"<\/code> field)<\/li>\n<\/ul>\nA plain <script><\/code> tag is not on the list. It's a classic script, not a CommonJS module. Browsers have never supported CommonJS natively, so require()<\/code> only works on the web after a bundler rewrites it.<\/p>\nclass NodePangu {}\nconst pangu = new NodePangu();\n\n\/\/ export\nmodule.exports = pangu;\nmodule.exports.NodePangu = NodePangu;\n\n\/\/ import from a file (inside the same package)\nconst { Pangu } = require('..\/shared\/index'); \/\/ the extension is optional in CommonJS\n\n\/\/ import from a package\nconst pangu = require('pangu'); \/\/ it loads .\/dist\/node\/index.cjs according to package.json[\"exports\"][\".\"][\"require\"][\"default\"]\nconst { NodePangu } = require('pangu');<\/code><\/pre>\nThere is also a variable named exports<\/code> in CommonJS, which is basically an alias of module.exports<\/code>. Assigning to exports<\/code> only rebinds that local variable, and what actually gets exported is still whatever module.exports<\/code> points to.<\/p>\n\/\/ You can think of it like this in every CommonJS module\nvar exports = module.exports = {};<\/code><\/pre>\nThe rule of thumb: just use module.exports<\/code>, never use exports<\/code>.<\/p>\nref:
\nhttps:\/\/nodejs.org\/api\/modules.html<\/a>
\nhttps:\/\/developer.mozilla.org\/en-US\/docs\/Web\/JavaScript\/Guide\/Modules<\/a><\/p>\n","protected":false},"excerpt":{"rendered":"Things start getting confusing when your npm package wants to support both ECMAScript Modules (ESM) and CommonJS (CJS), which makes it a dual-package.<\/p>\n","protected":false},"author":1,"featured_media":929,"comment_status":"closed","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[7],"tags":[11,12,140],"class_list":["post-928","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-about-javascript","tag-javascript","tag-node-js","tag-typescript"],"_links":{"self":[{"href":"https:\/\/vinta.ws\/code\/wp-json\/wp\/v2\/posts\/928","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/vinta.ws\/code\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/vinta.ws\/code\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/vinta.ws\/code\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/vinta.ws\/code\/wp-json\/wp\/v2\/comments?post=928"}],"version-history":[{"count":0,"href":"https:\/\/vinta.ws\/code\/wp-json\/wp\/v2\/posts\/928\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/vinta.ws\/code\/wp-json\/wp\/v2\/media\/929"}],"wp:attachment":[{"href":"https:\/\/vinta.ws\/code\/wp-json\/wp\/v2\/media?parent=928"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/vinta.ws\/code\/wp-json\/wp\/v2\/categories?post=928"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/vinta.ws\/code\/wp-json\/wp\/v2\/tags?post=928"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}