TypeScript Reference ยท Modules and Declaration Files
package.json exports and TypeScript
How the package.json exports map works with TypeScript: subpaths, conditions like import, require and types, ordering rules, blocked paths and dual packages.
The exports field of a package.json is the modern way to declare a package's public entry points. It lists which subpaths consumers may import and maps each to a file, optionally choosing a different file per condition: import for ES modules, require for CommonJS, types for TypeScript, default as a fallback, and others such as node or browser.
Two things matter for TypeScript. First, with moduleResolution set to node16, nodenext or bundler, the compiler reads exports and picks the file for its conditions, so the types you see match the runtime file you get. Second, the types condition must come before import, require and default in each block, because conditions are matched in object order and the first match wins.
{ "name": "my-lib", "type": "module", "exports": { ".": { "types": "./dist/index.d.ts", "default": "./dist/index.js" }, "./feature": "./dist/feature.js" } }
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or readFileSync(0)), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or readFileSync(0)), it gets the next line from this box.
Syntax
{ "exports": "./index.js", "exports": { ".": "./index.js", "./sub/*": "./lib/*.js" }, "exports": { ".": { "types": "...", "import": "...", "require": "...", "default": "..." } }, "imports": { "#internal": "./src/internal.js" } }
| Key | Description |
|---|---|
"." |
The package root, used for import "pkg". |
"./name" |
A subpath. Only listed subpaths can be imported. |
"./dir/*" |
A pattern; the * is substituted into the target. |
types, import, require, node, browser, default |
Conditions, matched top to bottom. default should be last. |
imports |
Private # aliases that only the package itself can use. |
Errors and edge cases:
- A path not listed in
exportsis blocked, even if the file exists. Node throwsERR_PACKAGE_PATH_NOT_EXPORTED, as the first example shows, and TypeScript reports that it cannot find the module. - A string target must start with
./. - Under
moduleResolution: "node10",exportsis ignored; the oldermain,typesandtypesVersionsfields are used instead. - A single
.d.tscannot describe both ESM and CommonJS output correctly when the formats differ, so a dual package ships two declaration files (.d.mtsand.d.cts) with matching conditions.
Usage notes
- Put
typesfirst inside every condition block. Nested blocks work:{ "import": { "types": "./a.d.mts", "default": "./a.mjs" } }. - Adding
exportsto an existing package can break consumers who deep-import files, so treat it as a major version change. - Publishing a dual package invites the dual-package hazard, where both copies load and state is duplicated. Many libraries now ship ES modules only.
- You can add custom conditions on the consumer side with
customConditionsintsconfig.json. - Check what consumers see with a tool such as
@arethetypeswrong/clibefore publishing.