Package exports

The exports field in a package's package.json declares which module should be used for module requests such as import "package" or import "package/sub/path". It replaces the default behavior, which returns the main field (or index.js) for "package" and performs a filesystem lookup for "package/sub/path".

Once the exports field is specified, only the requests it lists are available. Any other request results in a ModuleNotFound error.

In general, the exports field should be an object whose properties each describe a subpath of the module request. For the examples above, you could use "." for import "package" and "./sub/path" for import "package/sub/path".

Properties ending with / forward requests with that prefix to the old filesystem lookup algorithm. For properties ending with *, the * can take any value, and any * in the property value is replaced with that captured value.

For example:

{
  "exports": {
    ".": "./main.js",
    "./sub/path": "./secondary.js",
    "./prefix/": "./directory/",
    "./prefix/deep/": "./other-directory/",
    "./other-prefix/*": "./yet-another/*/*.js"
  }
}

Instead of a single result, the package author may provide a list of results. The list is tried in order, and the first valid result is used.

Note: only the first valid result is used, not all valid results.

For example:

{
  "exports": {
    "./things/": ["./good-things/", "./bad-things/"]
  }
}

Here, package/things/apple might be found in .../package/good-things/apple or in .../package/bad-things/apple.

[!WARNING] As of version 5.94.0, webpack's behavior has been updated to align with Node.js. It now selects the first valid path without attempting further resolutions, and throws an error if the path cannot be resolved.

For example, given this configuration:

{
  "exports": {
    ".": ["-bad-specifier-", "./non-existent.js", "./existent.js"]
  }
}

webpack 5.94.0 and later throws an error because non-existent.js is not found, whereas the previous behavior would have resolved to existent.js.

Rather than providing results directly in the exports field, the package author may let the module system choose one based on conditions about the environment.

To do this, use an object that maps conditions to results. Conditions are evaluated in object order, conditions whose results are invalid are skipped, and conditions may be nested to express a logical AND. The last condition in the object may be the special "default" condition, which always matches.

For example:

{
  "exports": {
    ".": {
      "red": "./stop.js",
      "yellow": "./stop.js",
      "green": {
        "free": "./drive.js",
        "default": "./wait.js"
      },
      "default": "./drive-carefully.js"
    }
  }
}

This translates to something like:

if (red && valid('./stop.js')) return './stop.js';
if (yellow && valid('./stop.js')) return './stop.js';
if (green) {
  if (free && valid('./drive.js')) return './drive.js';
  if (valid('./wait.js')) return './wait.js';
}
if (valid('./drive-carefully.js')) return './drive-carefully.js';
throw new ModuleNotFoundError();

The available conditions vary depending on the module system and tool used.

When only a single entry (".") into the package is needed, you can omit the { ".": ... } object nesting:

{
  "exports": "./index.mjs"
}

In an object whose keys are conditions, the order of properties matters. Conditions are handled in the order they're specified.

For example, { "red": "./stop.js", "green": "./drive.js" } is not equivalent to { "green": "./drive.js", "red": "./stop.js" }. When both the red and green conditions are set, the first property wins.

In an object whose keys are subpaths, the order of properties is not significant. More specific paths are preferred over less specific ones.

For example, { "./a/": "./x/", "./a/b/": "./y/", "./a/b/c": "./z" } is equivalent to { "./a/b/c": "./z", "./a/b/": "./y/", "./a/": "./x/" }. The order is always ./a/b/c > ./a/b/ > ./a/.

The exports field takes precedence over other package entry fields such as main, module, browser, or custom ones.

(1) Removed in Node.js 17. Use * instead.

(2) "./" is intentionally ignored as a key.

(3) The property value is ignored and the property key is used as the target. This effectively only allows mappings where the key and value are identical.

(4) The syntax is supported, but the first entry is always used, which makes it unusable for any practical case.

(5) Fallback to alternative sibling parent conditions is handled incorrectly.

(6) For the require condition, object order is handled incorrectly. This is intentional, as wmr does not distinguish between referencing syntaxes.

(7) When using the "exports": "./file.js" abbreviation, any request (for example, package/not-existing) resolves to that file. Without the abbreviation, direct file access (for example, package/file.js) will not lead to an error.

One of these conditions is set depending on the syntax used to reference the module:

These conditions may also be set additionally:

(1) import and require are both set independently of the referencing syntax. require always has lower priority.

The following syntax sets the import condition:

• ESM import declarations in ESM
• JS import() expressions
• HTML <script type="module">
• HTML <link rel="preload/prefetch">
• JS new Worker(..., { type: "module" })
• WASM import section
• ESM HMR (webpack) import.hot.accept/decline([...])
• JS Worklet.addModule
• Using JavaScript as an entrypoint

The following syntax sets the require condition:

• CommonJS require(...)
• AMD define()
• AMD require([...])
• CommonJS require.resolve()
• CommonJS (webpack) require.ensure([...])
• CommonJS (webpack) require.context
• CommonJS HMR (webpack) module.hot.accept/decline([...])
• HTML <script src="...">

The following syntax sets the style condition:

• CSS @import
• HTML <link rel="stylesheet">

The following syntax sets the asset condition:

• CSS url()
• ESM new URL(..., import.meta.url)
• HTML <img src="...">

The following syntax sets the script condition:

• HTML <script src="...">

The script condition should be set only when no module system is supported. When the script is preprocessed by a system that supports CommonJS, it should set require instead.

Use this condition when looking for a JavaScript file that can be injected as a script tag into an HTML page without additional preprocessing.

The following conditions are set for various optimizations:

Note: since production and development are not supported everywhere, make no assumptions when neither is set.

The following conditions are set depending on the target environment:

(1) electron, worker, and worklet come combined with either node or browser, depending on the context.

(2) This is set for the browser target environment.

Since there are multiple versions of each environment, the following guidelines apply:

• node: See the engines field for compatibility.
• browser: Compatible with the current spec and stage 4 proposals at the time the package is published. Polyfilling or transpiling must be handled on the consumer side.
  • Features that cannot be polyfilled or transpiled should be used carefully, as they limit possible usage.
• deno: TBD
• react-native: TBD

The following conditions are set depending on which tool preprocesses the source code:

Unfortunately, there is no node-js condition for Node.js as a runtime. Such a condition would simplify creating exceptions for Node.js.

The following tools support custom conditions:

For custom conditions, the following naming scheme is recommended:

<company-name>:<condition-name>

Examples: example-corp:beta, google:internal.

All patterns below are explained with a single "." entry into the package, but they can be extended to multiple entries by repeating the pattern for each one.

Treat these patterns as a guide, not a strict ruleset. Adapt them to each package as needed.

These patterns are based on the following goals and assumptions:

• Packages rot.
  • We assume that at some point packages are no longer maintained but continue to be used.
  • exports should be written with fallbacks for unknown future cases. The default condition is well suited for this.
  • Because the future is unknown, we assume an environment similar to browsers and a module system similar to ESM.
• Not all conditions are supported by every tool.
  • Fallbacks should handle these cases.
  • We assume the following fallbacks generally make sense:
    • ESM > CommonJS
    • Production > Development
    • Browser > Node.js

Depending on a package's intent, something else may make sense, in which case the patterns should be adapted. For example, for a command-line tool, a browser-like future and fallback doesn't make much sense; Node.js-like environments and fallbacks should be used instead.

For complex cases, multiple patterns must be combined by nesting these conditions.

These patterns make sense for packages that do not use environment-specific APIs.

{
  "type": "module",
  "exports": "./index.js"
}

Note: providing only ESM comes with restrictions for Node.js. Such a package only works in Node.js >= 14 and only when using import. It won't work with require().

{
  "type": "module",
  "exports": {
    "node": {
      "module": "./index.js",
      "require": "./index.cjs"
    },
    "default": "./index.js"
  }
}

Most tools get the ESM version. Node.js is the exception: it gets a CommonJS version when using require(). This leads to two instances of the package when it is referenced with both require() and import, but that's harmless because the package has no state.

The module condition is used as an optimization when preprocessing Node-targeted code with a tool that supports ESM for require() (such as a bundler that bundles for Node.js). For such a tool, the exception is skipped. This is technically optional, but bundlers would otherwise include the package source code twice.

You can also use the stateless pattern if you isolate your package state in JSON files. JSON is consumable from both CommonJS and ESM without polluting the graph with the other module system.

Note that "stateless" here also means class instances are not tested with instanceof, since there can be two different classes because of the double module instantiation.

{
  "type": "module",
  "exports": {
    "node": {
      "module": "./index.js",
      "import": "./wrapper.js",
      "require": "./index.cjs"
    },
    "default": "./index.js"
  }
}

In a stateful package, we must ensure the package is never instantiated twice. This isn't a problem for most tools, but Node.js is again the exception. For Node.js, we always use the CommonJS version and expose named exports in ESM through an ESM wrapper.

We use the module condition as an optimization here as well.

{
  "type": "commonjs",
  "exports": "./index.js"
}

Specifying "type": "commonjs" helps tools statically detect CommonJS files.

{
  "type": "module",
  "exports": {
    "script": "./dist-bundle.js",
    "default": "./index.js"
  }
}

Note that despite "type": "module" and the .js extension on dist-bundle.js, this file is not in ESM format. It should use globals so it can be consumed directly as a script tag.

These patterns make sense when a package ships two versions, one for development and one for production. For example, the development version might include extra code for better error messages or additional warnings.

{
  "type": "module",
  "exports": {
    "development": "./index-with-devtools.js",
    "default": "./index-optimized.js"
  }
}

When the development condition is supported, we use the development-enhanced version. Otherwise, in production or when the mode is unknown, we use the optimized version.

{
  "type": "module",
  "exports": {
    "development": "./index-with-devtools.js",
    "production": "./index-optimized.js",
    "node": "./wrapper-process-env.cjs",
    "default": "./index-optimized.js"
  }
}

We prefer static detection of production/development mode via the production or development condition.

Node.js can detect production/development mode at runtime via process.env.NODE_ENV, so we use that as a fallback in Node.js. Synchronously importing ESM conditionally is not possible, and we don't want to load the package twice, so we use CommonJS for the runtime detection.

When the mode cannot be detected, we fall back to the production version.

Choose a fallback environment that makes sense for the package and supports future environments. In general, assume a browser-like environment.

{
  "type": "module",
  "exports": {
    "node": "./index-node.js",
    "worker": "./index-worker.js",
    "default": "./index.js"
  }
}

{
  "type": "module",
  "exports": {
    "electron": {
      "node": "./index-electron-node.js",
      "default": "./index-electron.js"
    },
    "node": "./index-node.js",
    "default": "./index.js"
  }
}

This is an example of a package that has optimizations for production and development usage with runtime detection for process.env, and that also ships CommonJS and ESM versions:

{
  "type": "module",
  "exports": {
    "node": {
      "development": {
        "module": "./index-with-devtools.js",
        "import": "./wrapper-with-devtools.js",
        "require": "./index-with-devtools.cjs"
      },
      "production": {
        "module": "./index-optimized.js",
        "import": "./wrapper-optimized.js",
        "require": "./index-optimized.cjs"
      },
      "default": "./wrapper-process-env.cjs"
    },
    "development": "./index-with-devtools.js",
    "production": "./index-optimized.js",
    "default": "./index-optimized.js"
  }
}

This is an example of a package that supports Node.js, the browser, and Electron, has optimizations for production and development usage with runtime detection for process.env, and also ships CommonJS and ESM versions:

{
  "type": "module",
  "exports": {
    "electron": {
      "node": {
        "development": {
          "module": "./index-electron-node-with-devtools.js",
          "import": "./wrapper-electron-node-with-devtools.js",
          "require": "./index-electron-node-with-devtools.cjs"
        },
        "production": {
          "module": "./index-electron-node-optimized.js",
          "import": "./wrapper-electron-node-optimized.js",
          "require": "./index-electron-node-optimized.cjs"
        },
        "default": "./wrapper-electron-node-process-env.cjs"
      },
      "development": "./index-electron-with-devtools.js",
      "production": "./index-electron-optimized.js",
      "default": "./index-electron-optimized.js"
    },
    "node": {
      "development": {
        "module": "./index-node-with-devtools.js",
        "import": "./wrapper-node-with-devtools.js",
        "require": "./index-node-with-devtools.cjs"
      },
      "production": {
        "module": "./index-node-optimized.js",
        "import": "./wrapper-node-optimized.js",
        "require": "./index-node-optimized.cjs"
      },
      "default": "./wrapper-node-process-env.cjs"
    },
    "development": "./index-with-devtools.js",
    "production": "./index-optimized.js",
    "default": "./index-optimized.js"
  }
}

It looks complex, yes. We were already able to reduce some complexity thanks to an assumption we can make: only node needs a CommonJS version and can detect production/development with process.env.

• Avoid the default export. It's handled differently across tooling. Use only named exports.
• Never provide different APIs or semantics for different conditions.
• Write your source code as ESM and transpile to CJS with Babel, TypeScript, or a similar tool.
• Use either .cjs or "type": "commonjs" in package.json to clearly mark source code as CommonJS. This makes it statically detectable whether CommonJS or ESM is used, which matters for tools that support only ESM and not CommonJS.
• ESM used in packages supports the following request types:
  • Module requests, pointing to other packages with a package.json.
  • Relative requests, pointing to other files within the package.
    • They must not point to files outside the package.
  • data: URL requests.
  • Other absolute or server-relative requests are not supported by default, though some tools or environments may support them.

• Package entry points in Node.js