skip to content

In a web build, how do the `main`, `module` and `browser` package fields pick a file, and what does a `browser` mapping to `false` do?

level: middleimportance: should knowfreq 9%

answer

  1. before exports maps existed
  2. a field priority list
  3. browser builds check browser first
  4. object form replaces modules
  5. false means an empty module

basics

~20 s

Without an exports map, a browser build checks a priority list of fields, typically browser, then module, then main. An object-form browser field replaces modules for that package's imports, and false swaps a module for an empty one.

solid answer

~50 s

These are the **legacy entry fields**, used only when the package has no `exports` map that resolves the import. `main` is the original entry, often CommonJS. `module` is a bundler convention, not a standard, pointing at an ES module build. `browser` as a string names a browser-specific entry. A browser build walks a priority list, usually `browser`, `module`, `main`, and takes the first field present; a server build skips `browser`. In its **object form**, `browser` maps files or module names, for imports made inside that package, to replacements, and mapping one to `false` makes the browser build substitute an **empty module**. That is how a package keeps a server-only SDK out of the browser bundle: imports of it still resolve, but every named value they bind is `undefined`, so the browser code path must never call them.

code

json · 9 lines
json
{
  "name": "@shop/ui",
  "main": "./dist/index.cjs",
  "module": "./dist/index.mjs",
  "browser": {
    "server-sdk": false,
    "./dist/price-feed.mjs": "./dist/price-feed.browser.mjs"
  }
}

go deeper

for a junior

Recall that main is the classic entry, module points at an ES module build and browser at a browser build, and that browser builds usually check browser first.

for a middle

Explain the field priority list, why the exports map overrides it, and what the object form of browser does, including that false produces an empty module.

for a senior

Predict the run-time effect of a false stub, spot a module field that points at server code, and explain why one package resolves differently in two toolchains.

for a principal

Decide when shared packages should stop relying on browser stubs and split server and browser code by explicit conditions or subpaths that every tool resolves the same way.

## Where these fields come from Before the `exports` map existed, a package described its entry with a handful of `package.json` fields. They still matter: plenty of installed packages have no `exports` map, and the fields act as the fallback for any that do not resolve an import through one. A server-side runtime's own resolver, a separate subject, reads `main` and ignores `module` and `browser`. Build tools read all three. ## The three fields | Field | Standard? | Usually points at | Read by | |---|---|---|---| | `main` | the original entry field | a CommonJS or universal build | every resolver | | `module` | a bundler convention | an ES module build | build tools | | `browser` (string) | a community specification | a browser-specific build | browser builds | | `browser` (object) | the same specification | per-file or per-module replacements | browser builds | - **`main`** is what everything understands. A package with only `main` is resolved the same way everywhere. - **`module`** arose so build tools could find an ES module build, whose static `import` and `export` they can analyse, instead of a CommonJS one. Because it is not standardised, packages disagree about what it means: some point it at code that only works on the server. - **`browser`** says "in a browser, use this instead". A browser build checks it; a server build does not. ## The priority list A browser build checks a list of fields in order and takes the **first one the package defines**. The usual default is `browser`, then `module`, then `main`; a build aimed at a server typically drops `browser` from the list. The exact list is configuration and varies between tools, so one package can resolve differently in two toolchains. If none of the fields is present, the resolver falls back to an `index` file in the package folder. Once an `exports` map successfully resolves an import, none of these fields is consulted for it. A package that adds `exports` changes which file its consumers get, even with the legacy fields left untouched. ## The object form, and `false` In object form, `browser` is a replacement table that applies to imports **made from inside the package that declares it**: 1. A key that is a relative file path (`"./dist/price-feed.mjs"`) swaps that file for another one in browser builds. 2. A key that is a module name (`"server-sdk"`) swaps that dependency for a file of the package's choosing. 3. A value of `false` replaces the file or module with an **empty module**. An empty module exports nothing. The import statement still resolves, so the build succeeds, but every name it binds is `undefined`. The pattern suits a dependency that only one code path uses, the server path, when the shared code is also bundled for the browser: - The browser bundle is spared the SDK and anything it would drag in. - Server builds ignore the `browser` field and use the real SDK. - Code that calls the stubbed module in the browser fails at run time with "is not a function" or a property read on `undefined`, so the browser path must never call it. ## Pitfalls - **Silent divergence.** A tool that does not honour the `browser` field, such as a server runtime running the same code, loads the real module, so behaviour differs by tool. - **Mismatched builds.** A `module` field pointing at a server build and a `browser` field pointing at an older script bundle can make the field order decide between two very different files. - **Paths without extensions.** A field may name a folder or omit the extension (`"main": "lib"`); the resolver then applies its usual extension and index-file rules to that path, so the same field can land on different files in different tools. - **Forgotten replacements.** Because the table applies only inside the declaring package, mapping a module to `false` in one package does not stub it for the app's other packages. ## How to check what you got Open the package's `package.json`, note whether `exports` exists, and if not, apply your build's field list in order. The first field present is the entry. Then look up any object-form `browser` entries that apply to the files the package imports.

  • Why can the same package without an `exports` map resolve to different files in two different build tools?
    Each tool has its own default list of entry fields and its own order. One may check `browser` before `module`, another `module` before `main`, and some read older fields as well. A package whose fields point at builds that behave differently will therefore load a different file depending on the toolchain, which an `exports` map with explicit conditions avoids.
  • How would you keep a server-only SDK out of the browser bundle once the package that imports it adopts an `exports` map?
    Make the split explicit in the map: give the entry a `browser` condition that points at a build which never imports the SDK, or expose the server-only code under its own subpath that browser code never imports. Separating the code paths is more robust than stubbing, because a stub only turns a missing module into `undefined` values that fail when called.

  • The `module` field is part of the package standard every runtime reads.
  • A `browser` mapping to `false` makes the import fail the build.
  • The legacy entry fields still apply when the `exports` map resolves the import.
  • Every build tool checks the entry fields in the same fixed order.
  • Stubbing a module with `false` also removes it from server builds.