Skip to content
Tutorials Center
My learning

Topics

TypeScript Reference ยท tsconfig: Projects, Files and Watch Options

TypeScript libReplacement option

Reference for the TypeScript libReplacement option: how built-in lib files can be replaced by installed @typescript/lib-* packages, and how to switch it off.

The lib option selects which built-in declaration files describe the runtime (es2024, dom, and so on). libReplacement controls an extra step: whether, for each selected name, the compiler first looks in node_modules for a package called @typescript/lib-<name> and uses it instead of the file bundled with TypeScript.

This lets a project substitute a customized or patched version of a library declaration (for example a stricter dom) without changing TypeScript itself. The option was added in TypeScript 5.8. The compiler checks for replacements only when the option is enabled, and newer releases changed its default to off to save lookup time, so set it explicitly if you rely on replacement.

JSON
{
  "compilerOptions": {
    "lib": ["es2024", "dom"],
    "libReplacement": true
  }
}

Try it

Replacement needs a package on disk, so these examples model the lookup.

TypeScript Choosing the lib source

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 Naming the replacement package

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": { "libReplacement": false } }
Value Description
true Look for @typescript/lib-* packages before using the built-in lib files.
false Never look; always use the files shipped with TypeScript.

Package names mirror the lib names, with dots in a name written as hyphens (so es2015.promise maps to @typescript/lib-es2015-promise in the example above; check the package you install for the exact name it publishes).

Usage notes

  • Rarely needed. Most projects never install such packages. Leaving the option off avoids extra file-system lookups on every build.
  • Reproducibility. A replacement package becomes part of your dependency tree, so pin it like any other.
  • Not a polyfill. It changes the types the compiler believes exist, not what the runtime provides.
  • Combine with lib. The names you list in lib decide which replacements are even considered.
  • Skipped with noLib. If the default library is disabled, there is nothing to replace.
  • Version note. Introduced in TypeScript 5.8; older versions reject the option as unknown.