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.
{
"name": "my-lib",
"exports": {
".": "./src/index.js",
"./tools": "./src/tools.js",
"./package.json": "./package.json"
}
}
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 process.stdin), 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 process.stdin), it gets the next line from this box.
Syntax
The value of exports can take three shapes.
"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()andimportalike. It also stops tools from readingpkg/package.jsonunless you list"./package.json". - Exports win over
main. Keepmainonly for very old Node.js versions (before 12.7) and tools that do not understandexports. - Adding
exportsto 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 containingnode_modules. The more specific pattern (longest prefix) wins; usenullto exclude a subtree. - Self-reference. Code inside the package can import the package by its own
name, resolved through the sameexportsmap, which is handy in tests and examples. - File extensions. If the key is
./toolsand 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 atypescondition.