Package exports and conditions: the public API contract

exports overrides main and seals the package

The classic main field names one entry point and leaves the rest of the package wide open: any consumer can require("pkg/src/internal/helper.js") because resolution just walks the filesystem. The exports field inverts that. The moment a package declares exports, three rules take effect at once:

• It overrides main. Node consults exports first; main is only the fallback for packages without exports.
• It is an allow-list, not a hint. Any subpath not listed becomes unreachable — ERR_PACKAGE_PATH_NOT_EXPORTED — even if the file physically exists. This is encapsulation: the package author decides the public surface, and internals can be refactored freely because no one could legally import them.
• You must export package.json explicitly if consumers (or tooling) read it: "./package.json": "./package.json".

Together, these three rules flip the package from open-by-default to sealed-by-contract. Without the third rule, tooling silently breaks; without the second, you have no true API boundary — any deep require("pkg/dist/internal") that worked will keep working, and you cannot safely refactor internals.

{
  "name": "mylib",
  "exports": {
    ".": "./dist/index.js",
    "./package.json": "./package.json"
  }
}

With this, import "mylib" resolves to dist/index.js, and import "mylib/dist/anything-else.js" throws — the deep-import door is shut. That is the senior reason to add exports deliberately: it is the only mechanism Node gives you to draw a real API boundary around a package, turning “every file is public” into “only what I publish is public.”

Subpath exports and patterns

The . key is the package root; additional keys define subpath exports — named entry points consumers reach as pkg/<subpath>:

{
  "exports": {
    ".": "./dist/index.js",
    "./parser": "./dist/parser.js",
    "./utils/format": "./dist/utils/format.js"
  }
}

import "mylib/parser" now maps to dist/parser.js — note the public name (/parser) is decoupled from the physical path (dist/parser.js), so you can move files internally without breaking consumers as long as the map stays stable. For many subpaths, patterns with * avoid listing each by hand. The * is a non-greedy wildcard captured on the left and substituted on the right:

{
  "exports": {
    ".": "./dist/index.js",
    "./features/*": "./dist/features/*.js"
  }
}

Here import "mylib/features/auth" resolves to dist/features/auth.js. Patterns expose a whole directory through one rule, so use them when you genuinely want that subtree public — and remember the encapsulation tradeoff: a broad ./* pattern re-opens the package almost as wide as having no exports at all.

Conditional exports: one specifier, many targets

A subpath’s value can be a conditions object instead of a string: Node walks its keys in order and picks the first whose condition matches the current environment. This is how one package serves ESM to import and CommonJS to require:

{
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "import": "./dist/index.mjs",
      "require": "./dist/index.cjs",
      "default": "./dist/index.mjs"
    }
  }
}

Order is significant — first match wins, not most-specific — so the conventional ordering is types first (tooling reads it before anything runs), then the runtime conditions, then default last as the catch-all. The common conditions:

The imports field: private internal specifiers

Where exports defines the outward API, the sibling imports field defines inward aliases — private specifiers, always prefixed with #, visible only inside the package itself:

{
  "imports": {
    "#db": {
      "node": "./src/db/postgres.js",
      "default": "./src/db/memory.js"
    },
    "#internal/*": "./src/internal/*.js"
  }
}

Inside the package you write import db from "#db" and Node resolves it through the map — with full condition support, so #db can point at a real database on Node and an in-memory stub elsewhere. Unlike a relative path, a # specifier is stable no matter how deep the importing file is nested, and unlike a bare specifier it never escapes to node_modules. It is the clean way to do internal aliasing without a bundler or tsconfig path hackery.

The dual-package hazard

Conditional exports make it easy to ship both an ESM and a CJS build. The trap: if both builds carry state, an application can load both — ESM code reaches the import target, CJS code reaches the require target — and now two separate module instances of your package coexist, each with its own copy of every variable, registry, and instanceof identity. Singletons silently double; an object created by one half fails an instanceof check in the other. This is the dual-package hazard.

// Application accidentally loading both halves:
import { registry } from "mylib";        // → dist/index.mjs instance A
const { registry: r2 } = require("mylib"); // → dist/index.cjs instance B
// registry !== r2  — two states, the hazard

The robust avoidances, in order of preference: (1) ship ESM only and let CJS consumers reach you via dynamic import(), so there is exactly one instance; or (2) keep all stateful logic in a single CJS (or single ESM) core and make the other condition a thin wrapper that re-exports the same instance rather than a second copy. The anti-pattern is two independent full builds that each own state — that is the configuration that bites.