Skip to content

docs: explain Baseline checks and setup #22

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
3ru merged 1 commit into from
Oct 4, 2026
Merged

docs: explain Baseline checks and setup #22

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
107 changes: 33 additions & 74 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,110 +1,69 @@
# TypeScript Baseline Lib Generator

This project generates `baseline.d.ts`. This TypeScript lib contains declarations for JavaScript features that are [Baseline Widely available](https://web.dev/baseline).
Catch JavaScript API calls that are too new for your Baseline target. `typescript-baseline-lib` gives your editor and TypeScript compiler a set of built-in types selected by [Baseline](https://web.dev/baseline) browser support data.

The generator currently classifies `javascript.builtins.*` and the `arguments` object from `web-features`.
TypeScript's `ESNext` lib can accept APIs that your supported browsers cannot run. This package selects declarations from TypeScript using per-API data from `web-features`. By default, it includes Baseline Widely available APIs: those supported across the Baseline core browsers for at least 30 months.

## Best-practice setup
In the October 2026 snapshot, TypeScript accepts `.at()` but reports an error for `Promise.try()`:

TypeScript does not yet include `"baseline"` as a built-in `lib`. Install this package and the supported TypeScript major:
```ts
["a", "b"].at(-1);
Promise.try(() => 42);
```

Use it to check browser code or shared JavaScript modules before shipping. It checks API types; it does not transform syntax or load polyfills.

## Get started

The package supports TypeScript 6 and 7. Install it with TypeScript:

```sh
npm install --save-dev typescript@^7 typescript-baseline-lib
```

Configure the package as the complete global lib:
For JavaScript built-ins without browser or Node.js globals, start with this `tsconfig.json`:

```json
{
"compilerOptions": {
"noLib": true,
"strict": true,
"noEmit": true,
"types": ["typescript-baseline-lib"]
}
}
```

Run the compiler:
Run the check:

```sh
npx tsc --noEmit
npx tsc
```

With this configuration, TypeScript accepts supported JavaScript APIs that are Baseline Widely available. TypeScript reports APIs outside this target as errors.

Examples include `Promise.try` and `Intl.Segmenter` before they reach this Baseline status. The project goal is first-class `--lib baseline` support in TypeScript.

For more configurations, read the [Usage Guide](docs/USAGE.md).

This package replaces the default TypeScript libs. Do not set `compilerOptions.lib`. Do not combine this package with standard `es*` libs.

If your project needs other ambient type packages, add them to `types`. Some packages require runtime APIs outside the selected Baseline target.

The generator preserves audited declarations that support TypeScript. These declarations do not represent runtime APIs.

The generator does not add unavailable runtime APIs to support third-party packages.

## Allow a polyfilled feature

If the runtime loads an audited polyfill, add its generated `web-features` entry after the base package. For example, core-js can provide `Promise.try`:

```ts
import "core-js/proposals/promise-try";
```

```json
{
"compilerOptions": {
"noLib": true,
"types": [
"typescript-baseline-lib",
"typescript-baseline-lib/allow/promise-try"
]
}
}
```

Only entries in `registry/allowlist.json` are public. The registry defines permanent public paths.

Published entry paths remain valid. After all registered compat keys become Baseline Widely available, the entry refers to the base package.

The generator rejects features with `baselineStatus: false`.

## Target a Baseline year

Baseline year targets contain all JavaScript features that became Baseline Newly available by the end of a completed calendar year. For example, Baseline 2024 includes `Promise.withResolvers`:

```json
{
"compilerOptions": {
"noLib": true,
"types": ["typescript-baseline-lib/year/2024"]
}
}
```
This package replaces TypeScript's standard JavaScript libs. Do not combine it with `lib` or standard `es*` declarations. For browser globals, an existing tsconfig, or a separate CI check, follow the [Usage Guide](docs/USAGE.md).

The generator creates year entry points from the `baselineLowDate` of each compat row. Each entry is a complete alternative to the rolling base.
## Choose a target

The generator omits the current year until that year is complete. The first generated year is 2020.
| Target | Use it when |
| --- | --- |
| `typescript-baseline-lib` | You want the Widely available snapshot in the installed package. |
| `typescript-baseline-lib/year/2024` | You want APIs that became Newly available by the end of 2024. |
| `typescript-baseline-lib/allow/promise-try` | You load a suitable polyfill and need its types alongside the root target. |

The generator cannot close the TypeScript declaration graphs for 2015 through 2019. Those graphs require symbols from later years.
Year targets are complete alternatives to the root target. Choose one completed year from 2020 onward; do not combine it with the root or an `allow/*` entry. A year fixes the cutoff, while the installed package fixes the declaration snapshot. Pin the package version and commit your lockfile for repeatable checks.

This limit belongs to the implementation, not the Baseline specification.
An `allow/*` entry adds types only. Load the matching polyfill before using the API. The [allowlist](registry/allowlist.json) defines the public entries, and their paths remain valid after an API becomes Widely available. See the [polyfill example](docs/USAGE.md#i-polyfill-one-api-outside-the-rolling-target) for setup.

Do not combine a `year/*` entry point with the base package or an `allow/*` entry point. Each year file is a complete historical target.
## Scope

An `allow/*` entry applies only to the current rolling base. The generation report lists declaration-backed compat keys and managed upstream gaps.
The package covers JavaScript built-ins and the `arguments` object. It does not filter DOM or Worker APIs, check syntax support, or prove that code will run in every browser. Additional ambient declarations can expose APIs outside the selected target.

The report is in `derived/current/generation.json`. The generator does not create declarations for behavior that TypeScript cannot model.
The generator can only select APIs modeled by TypeScript declarations. Its [generation report](derived/current/generation.json) records declaration coverage and known gaps. Helper types needed by TypeScript are kept separately from runtime API availability.

Year boundaries apply to runtime JavaScript APIs. The pinned TypeScript toolchain supplies helper declarations.
For syntax and Web API checks, use [eslint-plugin-baseline-js](https://github.com/3ru/eslint-plugin-baseline-js) alongside this package.

These helper declarations are not historical runtime features.
## Work on the generator

## Current contract
This repository generates the npm package from pinned TypeScript and `web-features` inputs. The same inputs produce the same declarations, and the tests check both supported TypeScript majors and integration with the pinned upstream compiler.

- The public targets include the rolling base, completed cumulative years from 2020, and audited `allow/*` additions.
- The scope includes `javascript.builtins.*` and the `arguments` object.
- DOM, Web Worker, syntax, grammar, statements, and operators are outside the scope.
- `registry/compat-management.json` manages special compat rows and records a source URL for each row.
- The repository stores one rolling dataset and one set of derived artifacts. Git stores the history.
The long-term goal is native `--lib baseline` support in TypeScript. For the current package, use the configuration above. See [Contributing](CONTRIBUTING.md) to run the generator and tests, or [Operations](docs/OPERATIONS.md) to update its inputs.
114 changes: 36 additions & 78 deletions deploy/readmes/baseline.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,117 +1,75 @@
# {{PACKAGE_NAME}}

This package contains generated `baseline` declarations for TypeScript.
Catch JavaScript API calls that are too new for your Baseline target. This package gives your editor and TypeScript compiler a set of built-in types selected by [Baseline](https://web.dev/baseline) browser support data.

The [`TypeScript-Baseline-lib-generator`](https://github.com/3ru/TypeScript-Baseline-lib-generator) repository produces this package. It combines TypeScript declarations for JavaScript features that are [Baseline Widely available](https://web.dev/baseline).
TypeScript's `ESNext` lib can accept APIs that your supported browsers cannot run. This package selects declarations from TypeScript using per-API data from `web-features`. By default, it includes Baseline Widely available APIs: those supported across the Baseline core browsers for at least 30 months.

Current snapshot:
In the October 2026 snapshot, TypeScript accepts `.at()` but reports an error for `Promise.try()`:

- Supported TypeScript versions: `{{TYPESCRIPT_PEER_DEPENDENCY_RANGE}}`
- Baseline date: `{{BASELINE_DATE}}`
- TypeScript package: `{{TYPESCRIPT_VERSION}}`
- web-features package: `{{WEB_FEATURES_VERSION}}`
- web-features gitHead: `{{WEB_FEATURES_GIT_HEAD}}`
- Included compat rows: `{{INCLUDED_COMPAT_COUNT}}`
- Selected declaration units: `{{SELECTED_UNIT_COUNT}}`
- Transformed units: `{{TRANSFORMED_UNIT_COUNT}}`
```ts
["a", "b"].at(-1);
Promise.try(() => 42);
```

Use it to check browser code or shared JavaScript modules before shipping. It checks API types; it does not transform syntax or load polyfills.

## Best-practice setup
## Get started

TypeScript does not yet include `"baseline"` as a built-in `lib`. Install this package and the supported TypeScript major:
The package supports TypeScript 6 and 7. Install it with TypeScript:

```sh
npm install --save-dev typescript@^7 {{PACKAGE_NAME}}
```

This package also supports TypeScript 6 within `{{TYPESCRIPT_PEER_DEPENDENCY_RANGE}}`. TypeScript is an optional peer dependency.

Tools can read the same snapshot facts from `{{PACKAGE_NAME}}/snapshot.json`.

Configure the package as the complete global lib:
For JavaScript built-ins without browser or Node.js globals, start with this `tsconfig.json`:

```json
{
"compilerOptions": {
"noLib": true,
"strict": true,
"noEmit": true,
"types": ["{{PACKAGE_NAME}}"]
}
}
```

Run the compiler:
Run the check:

```sh
npx tsc --noEmit
```

With this configuration, TypeScript accepts supported JavaScript APIs that are Baseline Widely available. TypeScript reports APIs outside this target as errors.

This package replaces the default TypeScript libs. Do not set `compilerOptions.lib`. Do not combine this package with standard `es*` libs.

If your project needs other ambient type packages, add them to `types`. Some packages require runtime APIs outside the selected Baseline target.

The package preserves declarations that support TypeScript. These declarations do not represent runtime APIs.

The package does not expose unavailable runtime APIs to support third-party packages.

## Allow a polyfilled feature

If the runtime loads an audited polyfill, add its generated `web-features` entry after the base package. For example, core-js can provide `Promise.try`:

```ts
import "core-js/proposals/promise-try";
```

```json
{
"compilerOptions": {
"noLib": true,
"types": [
"{{PACKAGE_NAME}}",
"{{PACKAGE_NAME}}/allow/promise-try"
]
}
}
npx tsc
```

Only audited entries are public. Published entry paths remain valid.

After all compat keys become Baseline Widely available, the entry refers to the base package.
This package replaces TypeScript's standard JavaScript libs. Do not combine it with `lib` or standard `es*` declarations. For browser globals, an existing tsconfig, or a separate CI check, follow the [Usage Guide](https://github.com/3ru/TypeScript-Baseline-lib-generator/blob/main/docs/USAGE.md).

The generator rejects features with `baselineStatus: false`.
## Choose a target

## Target a Baseline year
| Target | Use it when |
| --- | --- |
| `{{PACKAGE_NAME}}` | You want the Widely available snapshot in the installed package. |
| `{{PACKAGE_NAME}}/year/2024` | You want APIs that became Newly available by the end of 2024. |
| `{{PACKAGE_NAME}}/allow/promise-try` | You load a suitable polyfill and need its types alongside the root target. |

Baseline year targets contain all JavaScript features that became Baseline Newly available by the end of a completed calendar year. For example, Baseline 2024 includes `Promise.withResolvers`:

```json
{
"compilerOptions": {
"noLib": true,
"types": ["{{PACKAGE_NAME}}/year/2024"]
}
}
```
Year targets are complete alternatives to the root target. Choose one completed year from 2020 onward; do not combine it with the root or an `allow/*` entry. A year fixes the cutoff, while the installed package fixes the declaration snapshot. Pin the package version and commit your lockfile for repeatable checks.

The generator creates year entry points from the `baselineLowDate` of each compat row. Each entry is a complete alternative to the rolling base.
An `allow/*` entry adds types only. Load the matching polyfill before using the API. The [allowlist](https://github.com/3ru/TypeScript-Baseline-lib-generator/blob/main/registry/allowlist.json) defines the public entries, and their paths remain valid after an API becomes Widely available. See the [polyfill example](https://github.com/3ru/TypeScript-Baseline-lib-generator/blob/main/docs/USAGE.md#i-polyfill-one-api-outside-the-rolling-target) for setup.

The generator omits the current year until that year is complete. Targets before 2020 are not available because their declaration graphs require later symbols.
## Scope

Do not combine a `year/*` entry point with the base package or an `allow/*` entry point. Each year file is a complete historical target.
The package covers JavaScript built-ins and the `arguments` object. It does not filter DOM or Worker APIs, check syntax support, or prove that code will run in every browser. Additional ambient declarations can expose APIs outside the selected target.

An `allow/*` entry applies only to the current rolling base. `reports/generation.json` lists declaration-backed compat keys and managed upstream gaps.
The generator can only select APIs modeled by TypeScript declarations. The package's `reports/generation.json` records declaration coverage and known gaps. Helper types needed by TypeScript are kept separately from runtime API availability.

The generator does not create declarations for behavior that TypeScript cannot model.
For syntax and Web API checks, use [eslint-plugin-baseline-js](https://github.com/3ru/eslint-plugin-baseline-js) alongside this package.

Year boundaries apply to runtime JavaScript APIs. The pinned TypeScript toolchain supplies helper declarations.
## Snapshot

These helper declarations are not historical runtime features.
- Supported TypeScript versions: `{{TYPESCRIPT_PEER_DEPENDENCY_RANGE}}`
- Baseline date: `{{BASELINE_DATE}}`
- TypeScript declarations: `{{TYPESCRIPT_VERSION}}`
- web-features package: `{{WEB_FEATURES_VERSION}}`
- Included compat rows: `{{INCLUDED_COMPAT_COUNT}}`

## Notes
Snapshot data and the web-features source revision are also available in `{{PACKAGE_NAME}}/snapshot.json`. TypeScript is an optional peer dependency.

- The base public surface is one `baseline` lib.
- Audited `allow/*` entry points add declarations for explicitly polyfilled APIs.
- Completed cumulative year entry points are complete alternatives to the base lib.
- The current scope includes `javascript.builtins.*` and the `arguments` object.
- The npm `typescript` package supplies the declarations. The package preserves the Microsoft license notice.
The [generator repository](https://github.com/3ru/TypeScript-Baseline-lib-generator) contains the source and contribution guide. Declarations come from TypeScript, and the package preserves Microsoft's license notice.
Loading
Loading