Skip to content
Tutorials Center
My learning

Topics

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.

JSON
{
  "name": "my-lib",
  "type": "module",
  "exports": {
    ".": { "types": "./dist/index.d.ts", "default": "./dist/index.js" },
    "./feature": "./dist/feature.js"
  }
}

Try it

TypeScript Conditions pick different files

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.

TypeScript Choosing the first matching condition

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

JSON
{
  "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 exports is blocked, even if the file exists. Node throws ERR_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", exports is ignored; the older main, types and typesVersions fields are used instead.
  • A single .d.ts cannot describe both ESM and CommonJS output correctly when the formats differ, so a dual package ships two declaration files (.d.mts and .d.cts) with matching conditions.

Usage notes

  • Put types first inside every condition block. Nested blocks work: { "import": { "types": "./a.d.mts", "default": "./a.mjs" } }.
  • Adding exports to 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 customConditions in tsconfig.json.
  • Check what consumers see with a tool such as @arethetypeswrong/cli before publishing.