Skip to content
Tutorials Center
My learning

Topics

TypeScript Reference ยท tsconfig: Language, Modules and Emit Options

TypeScript customConditions option

Reference for customConditions: adding your own conditions to package.json exports and imports resolution, how matching order works and monorepo uses.

customConditions adds names to the list of conditions that TypeScript recognizes when it reads the exports and imports fields of a package.json. A package can then offer different files for different situations, and you opt in to one by naming the condition.

The common use is a monorepo: each package exports its source under a custom condition such as "source", and the workspace's tsconfig enables that condition, so the editor and tsc read the .ts files directly instead of the built .d.ts files. It works with moduleResolution set to node16, nodenext or bundler.

JSON
{
  "compilerOptions": {
    "moduleResolution": "bundler",
    "customConditions": ["source"]
  }
}

Try it

TypeScript Choosing an entry from an exports map

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 readFileSync(0)), it gets the next line from this box.

TypeScript Order in the file decides, not order in the option

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 readFileSync(0)), it gets the next line from this box.

Syntax

JSON
{ "compilerOptions": { "customConditions": ["<name>", "..."] } }
Part Description
Value Array of strings. Default: not set.
Active conditions Your custom names, plus the built-in ones: types, import or require (depending on the importing file), node for the Node modes, default, and a few others for bundler mode.
Matching The first key in the package's object that is active wins. Keys that are not active are skipped.

Edge cases: the condition must appear in the package's exports or imports to have any effect. Misspelled conditions are silently ignored. The option requires one of the modern resolution modes; it does nothing under node10.

Usage notes

  • Put the custom key first in the package's exports object if it should win over types and import. TypeScript follows file order.
  • Match your tooling. Bundlers and runtimes have their own flags for the same idea (--conditions in Node, resolve.conditions in Vite). Use the same name everywhere or the type checker and runtime will load different files.
  • Not for publishing. Do not leave a source-only condition in packages you release; consumers would not have your src folder.
  • Dev/prod split. Names such as "development" are ordinary conditions; the option lets the type checker follow them.
  • Debugging. Use traceResolution to see which condition matched.