In Node.js conditional exports, how does the resolver choose between `import`, `require`, `node` and `default`, and why does key order in the object matter?
answer
- active set depends on how it is loaded
- walk keys in object order
- first active key wins
- default always matches
- nested objects fall through
basics
~20 sNode walks the condition object's keys in their written order and takes the first whose name is active or is default. import is active for import and import(), require for require(), node always; so a default key written first wins for everyone.
solid answer
~40 sEach load has a set of **active conditions**. In Node 24 an `import` or `import()` activates `node` and `import`; a `require()` activates `node` and `require`. Both also activate `module-sync` (because `require()` of ES modules is on by default) and `node-addons` unless `--no-addons` is set, plus anything passed with `--conditions`/`-C`. The resolver then reads the condition object **in key order** and picks the first key that is active or is `default`; the order of the active set is irrelevant. So `{"default": "./index.cjs", "import": "./index.mjs"}` sends every consumer to the CommonJS file, and a map with only `"import"` makes `require()` fail with `ERR_PACKAGE_PATH_NOT_EXPORTED`. Write specific keys first and `default` last. Unknown keys like `types` or `browser` are skipped unless enabled.
code
json · 7 lines{
"name": "some-package",
"exports": {
"default": "./index.cjs",
"import": "./index.mjs"
}
}go deeper
Recall the core condition names, import for import, require for require(), node for any Node, default as the fallback, and that default goes last.
Explain the matching rule: Node walks keys in written order and takes the first active one or default, recursing into nested objects and falling through when they match nothing.
Diagnose misordered maps from symptoms: everyone getting the CommonJS build, require() failing with No exports main defined, and use -C and both resolve functions to confirm.
Decide which conditions a team's internal packages may use, whether development builds are switched by -C, and how CI checks both loaders resolve each entry.
## Conditions are switches, not a priority list **Conditional exports** let one exports entry point at different files depending on how and where the package is loaded. A condition is just a key in a nested object: ```json { "exports": { ".": { "node": { "import": "./dist/node.mjs", "require": "./dist/node.cjs" }, "default": "./dist/universal.mjs" } } } ``` Resolving that entry takes two inputs: the **set of active conditions** for this load, and the object above. Node walks the object's keys **in the order they are written**. For each key it asks one question: is this key `default`, or is it in the active set? The first yes wins, and its value is resolved (recursing into nested objects). The set itself has no order, so it is the package's key order, not anything on Node's side, that decides precedence. ## Which conditions are active in Node 24 | Loaded via | Active conditions | |---|---| | `import` declaration, `import()`, `import.meta.resolve()` | `node`, `import`, `module-sync`, `node-addons` | | `require()`, `require.resolve()` | `node`, `require`, `module-sync`, `node-addons` | | Either, with `node -C development` | the above plus `development` | A few details matter: - **`import` and `require` describe the caller, not the file.** `import` matches when the ES module loader resolves the package, even if the target is CommonJS; `require` matches for `require()` even if the target is an ES module. They are always mutually exclusive. - **`module-sync`** is active for both loaders because loading ES modules with `require()` is enabled by default; `--no-require-module` removes it. It lets one ES module file serve both callers, provided its graph has no top-level `await`. - **`node-addons`** drops out under `--no-addons`. - **`default`** is not in the set at all; it matches unconditionally, which is why it belongs last. - **Community conditions** such as `types`, `browser`, `development` and `production` are ignored by Node unless named with `--conditions`. ## Order mistakes and what they cause 1. **`default` first.** `{"default": "./index.cjs", "import": "./index.mjs"}` resolves to `./index.cjs` for every caller, because `default` matches before `import` is ever read. 2. **No fallback.** `{"import": "./index.mjs"}` with no `require` or `default` key leaves `require('pkg')` with nothing to match, and Node throws `ERR_PACKAGE_PATH_NOT_EXPORTED` with `No "exports" main defined in .../package.json`. 3. **`node` before `import`/`require` at the same level.** `{"node": "./index.cjs", "import": "./index.mjs"}` gives Node's `import` callers the CommonJS file, because `node` is active for every Node load. 4. **Nested objects that fall through.** If a nested object such as `node: { "import": ... }` has no matching key, Node continues with the parent's remaining keys, like a nested `if` with no `else`. In the map at the top of this page, a `require()` caller gets `./dist/node.cjs`; if the `node` branch held only an `import` key, that caller would fall through to `default` and get `./dist/universal.mjs`. Loading the package through both `import` and `require` targets in one process can create two module instances, which the JavaScript lesson on the dual-package hazard covers; here the point is only which file each call gets. ## Custom conditions `node --conditions=development app.js` (short form `-C development`) adds a user condition to both loaders. Repeat the flag for more. Condition names must not start with `.`, contain `,`, or be integer-like keys such as `"10"`. User conditions are a clean way to swap a development build in without editing code, and the same flag applies to the `"imports"` field. ## A safe shape for a map A predictable condition object follows the order Node's packages documentation recommends, most specific to least specific: - `types` first if present, for type checkers (Node skips it); - `node-addons`, then `node`, if the package has a Node-only build; - `import` and `require`, or `module-sync`, to split by caller; - `default` last, always present, so unknown environments and unexpected callers still resolve. Nested objects follow the same rule at each level, and an inner object that matches nothing simply hands control back to its parent's next key. ## Checking the decision `import.meta.resolve('pkg')` and `require.resolve('pkg')` show the file each loader picks, so running both in one script makes an order mistake visible immediately. Run them with the same flags the service uses, since `-C` and `--no-addons` change the active set.
- A Node.js package's exports lists only an `import` condition; what does a CommonJS caller see?`require('pkg')` activates `require`, `node`, `module-sync` and `node-addons`, none of which is `import`, and there is no `default`. Nothing matches, so Node throws `ERR_PACKAGE_PATH_NOT_EXPORTED` with `No "exports" main defined`. Adding `default` or `module-sync` pointing at the ES module file lets `require()` load it in Node 24, as long as that graph has no top-level `await`.
- Why does putting `types` first in an exports condition object not affect Node.js?`types` is a community condition Node does not activate, so the resolver skips it and carries on to the next key. It is read by type checkers, which expect it first. Order only changes Node's result among keys Node actually treats as active, plus `default`.
- Does the `import` condition mean the target file must be an ES module?No. `import` matches whenever the ES module loader resolves the package, regardless of the target's format, and `require` likewise matches for `require()` even when the target is an ES module. The file's format is decided separately by its extension and the nearest `"type"`.
- Node picks the most specific matching condition no matter where it is written
- default is only used when no other key exists in the object
- The import condition requires the target file to be an ES module
- Node 24 resolves the browser and types conditions by default
- If a nested condition object has no match, resolution fails at once
- A missing require key makes Node fall back to the main field
Assumes Node.js 24: require() of ES modules is on by default (since 22.12 and 23.0), which also activates the module-sync condition; --conditions has been non-experimental since 22.9.