From a03d597562d2b002fb172702b6ab9a2bfdcf4383 Mon Sep 17 00:00:00 2001 From: Ryuya Date: Thu, 23 Jul 2026 01:15:51 -0700 Subject: [PATCH 1/2] docs: add usage guide --- README.md | 2 + docs/USAGE.md | 282 ++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 284 insertions(+) create mode 100644 docs/USAGE.md diff --git a/README.md b/README.md index 72c9034..f5dc549 100644 --- a/README.md +++ b/README.md @@ -28,6 +28,8 @@ npx tsc --noEmit Now only the supported Baseline widely available JavaScript surfaces type-check. APIs that haven't reached Baseline yet (`Promise.withResolvers`, `Array.fromAsync` until it promotes, and so on) are reported as errors. The end goal is first-class `--lib baseline` support upstream in TypeScript. +See the [Usage Guide](docs/USAGE.md) for browser, CI-only, shared-library, fixed-year, polyfill, Vite, Browserslist, and TypeScript 6 setups. + This package replaces TypeScript's default libs; do not set `compilerOptions.lib` or combine it with the standard `es*` libs. Add other ambient type packages to `types` only when the project needs them. Those packages can require APIs that are intentionally outside the selected Baseline target. The generator preserves audited erased compiler-support declarations, but it does not add unavailable runtime APIs merely to satisfy a third-party package. ## Allow a polyfilled feature diff --git a/docs/USAGE.md b/docs/USAGE.md new file mode 100644 index 0000000..3360627 --- /dev/null +++ b/docs/USAGE.md @@ -0,0 +1,282 @@ +# Usage Guide + +Copy-paste setups for common `typescript-baseline-lib` use cases. + +Use TypeScript 7 for new projects. The package also supports TypeScript 6 for +frameworks and tools that still require its programmatic API. + +## Before you choose a setup + +- Set `noLib: true`. TypeScript ignores `lib` when `noLib` is enabled. +- Choose one complete target: the rolling root package or one `year/*` entry. +- Add `allow/*` entries only to the rolling root package and only when the + runtime loads the matching polyfill. +- Keep `skipLibCheck` disabled. Hiding declaration conflicts weakens the gate. +- This package checks JavaScript built-in declarations. It does not transform + syntax, install polyfills, or Baseline-filter DOM APIs. + +## I want the current Baseline Widely Available target + +Install TypeScript and the generated lib: + +```sh +npm install --save-dev typescript@^7 typescript-baseline-lib +``` + +Use the package as the complete global JavaScript lib: + +```json +{ + "compilerOptions": { + "noLib": true, + "strict": true, + "types": ["typescript-baseline-lib"], + "noEmit": true + }, + "include": ["src/**/*.ts"] +} +``` + +```sh +npx tsc -p tsconfig.json +``` + +The root entry represents the current rolling snapshot shipped by each package +release. Use a year target when your compatibility contract must not move. + +## I want a browser app with DOM types + +Install the independently published DOM declarations: + +```sh +npm install --save-dev typescript@^7 typescript-baseline-lib @types/web +``` + +```json +{ + "compilerOptions": { + "noLib": true, + "strict": true, + "types": ["typescript-baseline-lib", "web"], + "noEmit": true + }, + "include": ["src/**/*.ts", "src/**/*.tsx"] +} +``` + +`@types/web` supplies `document`, `Window`, and other browser declarations. +Those DOM declarations are not filtered by this package. The Baseline gate +still applies only to the generated JavaScript built-ins. + +## I want a CI gate without replacing my build config + +Keep the project's normal `tsconfig.json` and add `tsconfig.baseline.json`: + +```json +{ + "extends": "./tsconfig.json", + "compilerOptions": { + "noLib": true, + "noEmit": true, + "types": ["typescript-baseline-lib"] + }, + "include": ["src/**/*.ts"] +} +``` + +Add a script: + +```json +{ + "scripts": { + "check:baseline": "tsc -p tsconfig.baseline.json" + } +} +``` + +```sh +npm run check:baseline +``` + +The child config replaces the inherited ambient `types`, and `noLib` disables +any inherited standard `lib`. For browser source, use +`["typescript-baseline-lib", "web"]` and install `@types/web` as shown above. + +## I want a shared package that runs in browsers and Node.js + +Run the Baseline gate only over the platform-neutral source: + +```json +{ + "extends": "./tsconfig.json", + "compilerOptions": { + "noLib": true, + "noEmit": true, + "types": ["typescript-baseline-lib"] + }, + "include": ["src/shared/**/*.ts"] +} +``` + +Do not add `dom`, `web`, or `node` globals to this shared-code gate. Keep +separate normal build configs for browser-only and Node-only entrypoints. + +Directly combining the current `@types/node` package with the Baseline lib is +not a supported universal setup. Node declarations can require standard-library +surfaces such as `Disposable` or `Float16Array` before they enter the selected +Baseline target. + +## I want a fixed Baseline year + +Use one complete cumulative year entry: + +```json +{ + "compilerOptions": { + "noLib": true, + "strict": true, + "types": ["typescript-baseline-lib/year/2024"], + "noEmit": true + }, + "include": ["src/**/*.ts"] +} +``` + +Do not combine a `year/*` entry with the root package or an `allow/*` entry. +The package currently publishes completed year targets from 2020 onward. + +## I polyfill one API outside the rolling target + +Install the runtime polyfill as a production dependency: + +```sh +npm install core-js +npm install --save-dev typescript@^7 typescript-baseline-lib +``` + +Load the polyfill from the application entrypoint: + +```ts +import "core-js/proposals/promise-with-resolvers"; + +const deferred = Promise.withResolvers(); +``` + +Then allow only its audited declaration entry: + +```json +{ + "compilerOptions": { + "noLib": true, + "strict": true, + "types": [ + "typescript-baseline-lib", + "typescript-baseline-lib/allow/promise-withresolvers" + ], + "noEmit": true + } +} +``` + +An `allow/*` entry changes type availability only. It never installs or loads a +runtime polyfill. Public entries are restricted to the repository's permanent +allowlist. + +## I want Vite to express the same policy + +Current Vite releases use Baseline Widely Available as the production default. +Make the intent explicit when desired: + +```ts +import { defineConfig } from "vite"; + +export default defineConfig({ + build: { + target: "baseline-widely-available", + }, +}); +``` + +Use this with the browser TypeScript setup above. Vite transforms syntax but +does not generally polyfill JavaScript APIs. Also note that Vite freezes its +Baseline browser snapshot per major release, while this package's root entry +is refreshed through separate dataset updates and package releases. + +## I want Browserslist and TypeScript to share a target + +For a rolling target, add `.browserslistrc`: + +```text +baseline widely available +``` + +Use it with `"types": ["typescript-baseline-lib"]`. + +For a fixed year: + +```text +baseline 2024 +``` + +Use it with `"types": ["typescript-baseline-lib/year/2024"]`. + +Browserslist configures compatible build and CSS tools. The TypeScript package +independently checks the JavaScript built-in declaration surface. + +## I must stay on TypeScript 6 + +Install the supported 6.x compiler: + +```sh +npm install --save-dev typescript@^6 typescript-baseline-lib +``` + +Use the same `noLib` and `types` settings from the recipes above. This is useful +while an editor, framework, or lint tool still depends on TypeScript 6's +programmatic API. + +## I want ESLint to enforce the same Baseline + +Add [`eslint-plugin-baseline-js`](https://github.com/3ru/eslint-plugin-baseline-js) +to cover JavaScript syntax and Web APIs that a TypeScript lib cannot model: + +```sh +npm install --save-dev eslint eslint-plugin-baseline-js +``` + +```js +// eslint.config.mjs +import baselineJs from "eslint-plugin-baseline-js"; + +export default [ + { plugins: { "baseline-js": baselineJs } }, + baselineJs.configs.recommended({ + available: "widely", + level: "error", + }), +]; +``` + +Use `available: 2024` with `typescript-baseline-lib/year/2024` when both tools +should enforce the same fixed year. + +## I want to inspect what TypeScript loaded + +```sh +npx tsc -p tsconfig.baseline.json --explainFiles +``` + +The output should include `typescript-baseline-lib` and should not include +TypeScript's standard `lib.es*.d.ts` files. + +## References + +- [TypeScript `noLib`](https://www.typescriptlang.org/tsconfig/noLib.html) +- [TypeScript `types`](https://www.typescriptlang.org/tsconfig/types) +- [TypeScript DOM declarations (`@types/web`)](https://github.com/microsoft/TypeScript-DOM-lib-generator) +- [TypeScript 7.0 and the TypeScript 6 transition](https://devblogs.microsoft.com/typescript/announcing-typescript-7-0/) +- [Vite build targets](https://vite.dev/config/build-options.html#build-target) +- [Browserslist Baseline queries](https://github.com/browserslist/browserslist#queries) +- [Choosing a Baseline target](https://web.dev/articles/how-to-choose-your-baseline-target) +- [Baseline and polyfills](https://web.dev/articles/baseline-and-polyfills) +- [`Promise.withResolvers` in core-js](https://core-js.io/docs/features/proposals/promise-withresolvers) From 73872e3fb758ff45cc318577e04a20a1c69e9cbd Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Thu, 30 Jul 2026 07:07:00 +0000 Subject: [PATCH 2/2] chore(deps): bump the github-actions group with 3 updates Bumps the github-actions group with 3 updates: [actions/checkout](https://github.com/actions/checkout), [actions/setup-node](https://github.com/actions/setup-node) and [actions/setup-go](https://github.com/actions/setup-go). Updates `actions/checkout` from 7.0.0 to 7.0.1 - [Release notes](https://github.com/actions/checkout/releases) - [Changelog](https://github.com/actions/checkout/blob/main/CHANGELOG.md) - [Commits](https://github.com/actions/checkout/compare/9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0...3d3c42e5aac5ba805825da76410c181273ba90b1) Updates `actions/setup-node` from 6.4.0 to 7.0.0 - [Release notes](https://github.com/actions/setup-node/releases) - [Commits](https://github.com/actions/setup-node/compare/48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e...820762786026740c76f36085b0efc47a31fe5020) Updates `actions/setup-go` from 6.5.0 to 7.0.0 - [Release notes](https://github.com/actions/setup-go/releases) - [Commits](https://github.com/actions/setup-go/compare/924ae3a1cded613372ab5595356fb5720e22ba16...b7ad1dad31e06c5925ef5d2fc7ad053ef454303e) --- updated-dependencies: - dependency-name: actions/checkout dependency-version: 7.0.1 dependency-type: direct:production update-type: version-update:semver-patch dependency-group: github-actions - dependency-name: actions/setup-node dependency-version: 7.0.0 dependency-type: direct:production update-type: version-update:semver-major dependency-group: github-actions - dependency-name: actions/setup-go dependency-version: 7.0.0 dependency-type: direct:production update-type: version-update:semver-major dependency-group: github-actions ... Signed-off-by: dependabot[bot] --- .github/workflows/package-dry-run.yml | 4 ++-- .github/workflows/release.yml | 8 ++++---- .github/workflows/test-typescript-go.yml | 6 +++--- .github/workflows/test-typescript.yml | 4 ++-- .github/workflows/typescript-update.yml | 4 ++-- .github/workflows/validate.yml | 4 ++-- .github/workflows/weekly-update.yml | 4 ++-- 7 files changed, 17 insertions(+), 17 deletions(-) diff --git a/.github/workflows/package-dry-run.yml b/.github/workflows/package-dry-run.yml index e156714..105a19b 100644 --- a/.github/workflows/package-dry-run.yml +++ b/.github/workflows/package-dry-run.yml @@ -23,8 +23,8 @@ jobs: runs-on: ubuntu-latest steps: - - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0 - - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0 + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0 with: node-version: "22" cache: "npm" diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 13c0821..40bb22a 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -37,8 +37,8 @@ jobs: echo "::error::Release can only run from the main branch (ref: ${{ github.ref }})" exit 1 - - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0 - - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0 + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0 with: node-version: "24" cache: "npm" @@ -129,8 +129,8 @@ jobs: id-token: write steps: - - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0 - - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0 + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0 with: node-version: "24" diff --git a/.github/workflows/test-typescript-go.yml b/.github/workflows/test-typescript-go.yml index 41fb1fb..d6d47ae 100644 --- a/.github/workflows/test-typescript-go.yml +++ b/.github/workflows/test-typescript-go.yml @@ -29,8 +29,8 @@ jobs: timeout-minutes: 45 steps: - - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0 - - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0 + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0 with: node-version: "22" cache: "npm" @@ -53,7 +53,7 @@ jobs: id: go-version run: echo "version=$(grep -m1 '^go ' .tmp/typescript-go/go.mod | awk '{print $2}')" >> "$GITHUB_OUTPUT" - - uses: actions/setup-go@924ae3a1cded613372ab5595356fb5720e22ba16 # v6.5.0 + - uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7.0.0 with: go-version: "${{ steps.go-version.outputs.version }}" cache-dependency-path: .tmp/typescript-go/go.sum diff --git a/.github/workflows/test-typescript.yml b/.github/workflows/test-typescript.yml index f2dc0a9..3fdf915 100644 --- a/.github/workflows/test-typescript.yml +++ b/.github/workflows/test-typescript.yml @@ -25,8 +25,8 @@ jobs: timeout-minutes: 60 steps: - - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0 - - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0 + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0 with: node-version: "22" cache: "npm" diff --git a/.github/workflows/typescript-update.yml b/.github/workflows/typescript-update.yml index 6a2e4f8..b483b42 100644 --- a/.github/workflows/typescript-update.yml +++ b/.github/workflows/typescript-update.yml @@ -24,8 +24,8 @@ jobs: runs-on: ubuntu-latest steps: - - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0 - - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0 + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0 with: node-version: "22" cache: "npm" diff --git a/.github/workflows/validate.yml b/.github/workflows/validate.yml index ed33dff..56003af 100644 --- a/.github/workflows/validate.yml +++ b/.github/workflows/validate.yml @@ -23,8 +23,8 @@ jobs: runs-on: ubuntu-latest steps: - - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0 - - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0 + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0 with: node-version: "22" cache: "npm" diff --git a/.github/workflows/weekly-update.yml b/.github/workflows/weekly-update.yml index a77c437..aa05220 100644 --- a/.github/workflows/weekly-update.yml +++ b/.github/workflows/weekly-update.yml @@ -24,8 +24,8 @@ jobs: runs-on: ubuntu-latest steps: - - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0 - - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0 + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0 with: node-version: "22" cache: "npm"