Skip to content
Tutorials Center
My learning

Topics

Node.js Reference ยท Module Systems

The package.json exports field

Reference for the exports field in package.json: define a package's public entry points, subpaths and patterns, block deep imports and understand the errors Node.js raises.

The exports field in a package's package.json defines which files other code may load from that package, and under which names. Once it is present, it is the only way in: require('pkg') and import 'pkg/feature' are resolved through the map, and any path that is not listed is refused, even if the file exists on disk.

This gives package authors an encapsulated public API. Internal files can be moved or renamed without breaking users, and users cannot reach into pkg/lib/internal/helper.js by accident. It replaces the older main field, which only named one entry point.

NODE
{
  "name": "my-lib",
  "exports": {
    ".": "./src/index.js",
    "./tools": "./src/tools.js",
    "./package.json": "./package.json"
  }
}

Try it

Node.js Entry points and blocked paths

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 process.stdin), it gets the next line from this box.

Node.js Subpath patterns and self-reference

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 process.stdin), it gets the next line from this box.

Syntax

The value of exports can take three shapes.

NODE
"exports": "./index.js"                      // shorthand for the main entry only

"exports": {                                 // subpath exports
  ".": "./index.js",
  "./feature": "./src/feature.js",
  "./features/*": "./src/features/*.js",     // pattern: * matches any text, including "/"
  "./internal/*": null                       // null blocks a path
}

"exports": {                                 // conditions at the top level: main entry only
  "import": "./index.mjs",
  "require": "./index.cjs"
}
Key or value Meaning
"." The package's main entry, the target of import 'pkg'.
"./name" A subpath. Users write pkg/name. Keys must start with ./.
"./dir/*" A pattern. The matched text replaces every * in the target.
Value starting with ./ A path inside the package. It may not go up with .. or into node_modules.
Value null The path is explicitly not exported; useful to carve exceptions out of a pattern.
Object with condition names Pick a target by environment, see Conditional exports.
Array Fallbacks tried in order; used for different target forms.

Errors: ERR_PACKAGE_PATH_NOT_EXPORTED when the requested subpath is not in the map. ERR_INVALID_PACKAGE_CONFIG or ERR_INVALID_PACKAGE_TARGET when the field itself is malformed (for example a target that does not start with ./). A target that points to a file that does not exist gives ERR_MODULE_NOT_FOUND.

Usage notes

  • Encapsulation is the point. Everything not listed is private to the package, for require() and import alike. It also stops tools from reading pkg/package.json unless you list "./package.json".
  • Exports win over main. Keep main only for very old Node.js versions (before 12.7) and tools that do not understand exports.
  • Adding exports to an existing package is a breaking change, because deep imports that worked before are now refused. Export the old paths you want to keep supporting.
  • Mixing keys. A map cannot mix .-prefixed subpaths with condition names at the same level: either all keys start with . or none do.
  • Patterns replace each * with the same text, can be used on both sides of a mapping, and cannot match a path containing node_modules. The more specific pattern (longest prefix) wins; use null to exclude a subtree.
  • Self-reference. Code inside the package can import the package by its own name, resolved through the same exports map, which is handy in tests and examples.
  • File extensions. If the key is ./tools and the target is ./src/tools.js, users import without extensions in both CommonJS and ESM. That is the trick for extensionless public names in ESM.
  • Other tools. Bundlers and TypeScript (moduleResolution: "node16", "nodenext" or "bundler") read the same field; TypeScript adds a types condition.