A common answer to "which browsers does this project support?" is a line in tsconfig.json, something like "target": "es2022". I understand why. It looks like a compatibility setting. But it isn't one, and this post is about what to use instead if you want the type checker to know about your browser target.

I'll stay in the type layer. Linting gets a short mention at the end.

What target and lib actually promise

target decides which syntax TypeScript emits and, when you don't set lib, which declaration files get loaded by default. lib decides which built-in APIs the checker believes exist. Neither one adds code at runtime. If lib declares Set.prototype.difference, TypeScript accepts the call, and whether it runs depends entirely on the browser.

ECMAScript years also don't line up with browsers. A feature lands in a spec year, then ships in each engine on its own schedule, then takes time to reach the devices your users actually have. The author of TypeScript issue #62536 describes using lib: "ES2022" as a stand-in and notes that it is "not self-updating and could still include items that some browsers are yet to support". That issue asks for a "baseline-widely-available" lib value. It is open, labeled Suggestion and Awaiting More Feedback.

Until something like that exists in TypeScript, the lib has to come from a package.

Replacing the JavaScript lib

typescript-baseline-lib is a generated set of declarations for JavaScript built-ins, filtered by web-features data to a Baseline target. Version 0.1.1 uses a snapshot from 2026-10-02 and targets Widely available. A built-in outside the target simply has no declaration.

Because it replaces the standard libs instead of adding to them, it runs under noLib. Here is the config I use next to an ordinary tsconfig.json:

// tsconfig.baseline.json
{
  "extends": "./tsconfig.json",
  "compilerOptions": {
    "lib": null,
    "noLib": true,
    "libReplacement": false,
    "noEmit": true,
    "skipLibCheck": false,
    "types": ["typescript-baseline-lib", "@typescript/lib-dom"]
  },
  "include": ["src/**/*.ts"]
}

Line by line:

• "lib": null drops the lib array inherited from the base config, which in my case is ["ESNext", "DOM"].
• "noLib": true tells TypeScript not to load any of its bundled lib.*.d.ts files.
• "libReplacement": false turns off lib-name lookup, which has nothing to resolve once noLib is on.
• types brings in the Baseline JavaScript declarations and a DOM lib. With noLib, DOM is not loaded for you, so it has to be listed. I use modern-web-types installed under the @typescript/lib-dom alias.
• "skipLibCheck": false makes TypeScript check the declaration files against each other, which is how I confirmed the two packages fit together.

Sample input:

// src/builtins.ts
const current = new Set(["a", "b", "c"]);
const removed = new Set(["b"]);
export const kept = current.difference(removed); // set-methods: Newly available 2024-06-11

export const answer = Promise.try(() => 42); // promise-try: Newly available 2025-01-07

The base config passes this file because ESNext declares both methods. The Baseline config does not:

$ npx tsc -p tsconfig.baseline.json
src/builtins.ts(3,29): error TS2550: Property 'difference' does not exist on type 'Set<string>'. Do you need to change your target library? Try changing the 'lib' compiler option to 'es2025' or later.
src/builtins.ts(5,31): error TS2550: Property 'try' does not exist on type 'PromiseConstructor'. Do you need to change your target library? Try changing the 'lib' compiler option to 'es2025' or later.

The "try changing the lib" hint is TypeScript's standard TS2550 text. In this setup, following it would remove the check.

Why it has to be noLib

The tempting shortcut is to leave lib alone and add the package to types:

{
  "compilerOptions": {
    "lib": ["DOM"],
    "libReplacement": true,
    "types": ["typescript-baseline-lib"]
  }
}

In my test project on TypeScript 6.0.3, that produced 42 errors inside declaration files, in addition to the expected TS2550 errors in source:

node_modules/typescript-baseline-lib/baseline.d.ts(765,6): error TS2300: Duplicate identifier 'IteratorResult'.
node_modules/typescript/lib/lib.es2015.iterable.d.ts(37,6): error TS2300: Duplicate identifier 'IteratorResult'.
node_modules/typescript/lib/lib.es5.d.ts(118,5): error TS2374: Duplicate index signature for type 'number'.

The config only asks for DOM, so where do lib.es5.d.ts and lib.es2015.iterable.d.ts come from? --explainFiles answers it:

node_modules/typescript/lib/lib.es5.d.ts
  Library referenced via 'es5' from file 'node_modules/typescript/lib/lib.es2015.d.ts'
node_modules/typescript/lib/lib.es2015.d.ts
  Library referenced via 'es2015' from file 'node_modules/@typescript/lib-dom/lib.dom.d.ts'

The DOM file starts with /// <reference lib="es2015" />, the same as @types/web. Outside noLib, TypeScript follows that reference and loads the ES2015 libs, which pull in ES5. Now the standard declarations and the Baseline declarations both define IteratorResult, PropertyKey, Partial, and the rest, and the checker reports every collision.

Under noLib, those references were not followed. --listFilesOnly on the working config shows exactly five files: my two sources, typescript-baseline-lib/baseline.d.ts, typescript-baseline-lib/index.d.ts, and @typescript/lib-dom/lib.dom.d.ts. With skipLibCheck: false there were no declaration errors.

So the rule is: one config with noLib, both packages in types. A single noLib tsconfig also worked for me. I keep it separate so the editor uses the wider ESNext lib and CI runs the Baseline one.

TypeScript 6 and 7

I ran the same configs on TypeScript 6.0.3 and 7.0.2. The diagnostics matched: the two TS2550 errors from the Baseline config, a clean run from the base config, and duplicate-declaration errors (TS2300, TS2374) from the non-noLib shortcut. The only difference I saw was the exit code on failure, 2 on 6.0.3 and 1 on 7.0.2. Both are non-zero, so CI treats them the same.

I only compared tsc output on 7.0.2. Editor behavior and other tooling are a separate question. I stayed on 6.0.3 for the project because typescript-eslint 8.71.1 declares a TypeScript peer range of <6.1.0.

DOM is a separate layer

This config is responsible for JavaScript built-ins. DOM types come from whatever you list next to it. With modern-web-types, you get every API shipped in at least one stable engine, which is what you want for writing progressive enhancements. If you would rather have the type system enforce DOM support too, uhyo's @baseline-types/dom-* packages provide DOM libs cut to a Baseline target. Those are two different answers to the DOM question, so pick one per config.

Declaring a polyfill

If you ship a polyfill, add its feature explicitly:

"types": [
  "typescript-baseline-lib",
  "typescript-baseline-lib/allow/promise-try",
  "@typescript/lib-dom"
]

With that entry, Promise.try type-checked and Set#difference was still an error. An allow/* entry only adds declarations, so you still need the import that loads the polyfill (I used core-js/proposals/promise-try).

For feature-detected code, the pattern I use is an intersection type with the member marked optional, so the compiler requires a typeof check before the call:

type MaybeSetMethods<T> = Set<T> & {
  difference?: (other: ReadonlySet<T>) => Set<T>;
};

Do you need this?

If your project never touches built-ins newer than your lib year, and you are happy reviewing that by hand, probably not. If you already lint against a Browserslist config using eslint-plugin-compat or @koddsson/eslint-plugin-tscompat, that covers similar ground at the lint layer. Browserslist also accepts Baseline queries such as baseline widely available if you want one policy name across tools.

What the type layer adds is that built-ins outside the target are absent from the declarations. The error shows up in tsc, at the line, before lint runs.

For DOM APIs and per-call checks I use eslint-plugin-baseline-js with its type-aware preset. I walk through that layer, with the ESLint config and CI scripts, in a separate post on DEV. The choice of target belongs to your audience data, and web.dev's How to choose your Baseline target covers that. Whichever target you pick, pin the package version: Widely available moves with each data release, and a bump should be a change you review.

Disclosure: I maintain eslint-plugin-baseline-js and typescript-baseline-lib.