Skip to content
Tutorials Center
My learning

Topics

Node.js Reference ยท Module Systems

Conditional exports in package.json

How conditional exports in package.json choose a file by condition in Node.js: import, require, node, default, custom conditions, ordering and dual packages.

A conditional export is an entry in the exports field of package.json whose value is an object of conditions instead of a single path. Node walks the object from top to bottom and uses the first condition that is active for the current import. This lets one package name point at different files for import and require, for production and development, or for Node and other runtimes.

Conditions are plain keys such as "import", "require", "node" and "default". Which ones are active depends on how the package is loaded and on the flags you started Node with. Order matters, and "default" should always come last as the fallback.

NODE
// package.json of a package
// {
//   "exports": {
//     ".": { "import": "./esm/index.js", "require": "./cjs/index.cjs", "default": "./esm/index.js" }
//   }
// }

Try it

Node.js import versus require picks 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 process.stdin), it gets the next line from this box.

Node.js Nested conditions, order and fallbacks

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

NODE
// Each key under "." (or a subpath) is a condition; first match wins
{
  "exports": {
    ".": {
      "<condition>": "./path.js" | { /* nested conditions */ } | null,
      "default": "./path.js"
    }
  }
}
Condition Description
"import" Active when the package is loaded with import or import().
"require" Active when the package is loaded with require().
"module-sync" Active for both import and require() when the target is an ES module with no top-level await. Lets a package ship a single ES build for both.
"node" Active in Node.js; other runtimes and bundlers usually skip it.
"node-addons" Active in Node.js unless --no-addons is used; guards native addon entries.
"default" Always matches. Put it last.
"types" Not used by Node; TypeScript reads it, and it must come before the others.
custom Any other string. Active only when you start Node with --conditions=name (or -C name).

Returns: a resolved file path inside the package. Errors: ERR_PACKAGE_PATH_NOT_EXPORTED when no condition matches (or the value is null) and ERR_INVALID_PACKAGE_CONFIG for malformed exports.

Usage notes

  • Order is significant. Keys are tried in the order they appear in the object. A "default" placed first would hide every condition after it.
  • Conditions nest. A matching condition may itself hold an object of conditions, evaluated the same way. If nothing inside matches, resolution continues with the next sibling of the outer condition.
  • import and require describe the loader, not the file. The file chosen for "import" must still have an extension and type that Node treats as ES module (.mjs, or .js in a "type": "module" package). See File extensions.
  • Dual packages can load twice. A program that both imports and requires the same package gets two separate copies with separate state. Keep state in a CommonJS file that both builds wrap, or use a single ES build with "module-sync".
  • Custom conditions are useful for development builds: node --conditions=development app.mjs activates a "development" key. This flag cannot be shown in the live examples above.
  • Subpaths are conditional too. "./feature" can have its own condition object, and a pattern such as "./utils/*" can map to a folder.
  • Self-reference. Inside a package that has exports and a name, files can import the package by its own name and go through these same conditions.
  • Bundlers add their own conditions (browser, worker, production). Node ignores those unless you enable them.