DEV Community: Leo

Your Build Target Is Not an API Contract: Enforcing Baseline with TypeScript

Leo — Sat, 25 Jul 2026 20:33:45 +0000

Vite 7 and later use Baseline Widely Available as the default production build target.

Now put this in a Vite application:

Promise.withResolvers<number>();

document.startViewTransition(() => {
  // Update the DOM.
});

Then run:

npx vite build

The build succeeds.

Regular TypeScript accepts the same code when the standard ESNext and DOM libraries are loaded:

npx tsc --noEmit --target ESNext --lib ESNext,DOM

# exit code 0

At the time of testing, however, neither API was Baseline Widely Available:

Promise.withResolvers() was Baseline 2024 Newly Available.
Document.startViewTransition() was Baseline 2025 Newly Available.

That result is not a bug in Vite or TypeScript.

It exposes a gap between two different contracts:

Layer	What it controls	What it does not control
Vite build target	Which JavaScript syntax must be transformed for the target browsers	Whether every runtime API you call is available
TypeScript `lib`	Which global APIs exist in the type environment	Whether those APIs meet your Baseline policy
Baseline	Cross-browser availability of web platform features	Your build output or runtime polyfills

A build target is not an API contract.

The 30-second version

Use typescript-baseline-lib for JavaScript built-ins such as Promise, Array, and Map.
Use @baseline-types/dom-widely-available for browser APIs such as Document, ResizeObserver, and fetch.
Load both from a dedicated TypeScript configuration and run it as a separate CI check.

The result is an ordinary tsc error. No additional source-code parser is involved.

Why the build passes

Vite describes its TypeScript support as transpile-only. It removes TypeScript syntax but does not run type checking by itself.

Its build target tells the transformer which JavaScript syntax needs to be lowered. It does not automatically reject every API that falls outside the corresponding Baseline target, and it does not generally inject API polyfills.

TypeScript checks APIs through declaration files such as lib.esnext.d.ts and lib.dom.d.ts. Those files model a selected ECMAScript or web platform surface. They are not filtered by Baseline status.

Both tools are doing their intended jobs. The missing layer is a declaration set that represents the API policy we want to enforce.

Add a Baseline API check

Install TypeScript and the two generated declaration packages:

npm install --save-dev \
  typescript@^7 \
  typescript-baseline-lib \
  @baseline-types/dom-widely-available

Commit the lockfile. The package versions determine the exact Baseline snapshots evaluated in CI.

Keep your existing build configuration and add a dedicated TypeScript project.

tsconfig.baseline.json

{
  "compilerOptions": {
    "target": "ESNext",
    "module": "ESNext",
    "moduleResolution": "Bundler",
    "strict": true,
    "noEmit": true,
    "noLib": true,
    "allowImportingTsExtensions": true,
    "types": [
      "typescript-baseline-lib",
      "@baseline-types/dom-widely-available"
    ]
  },
  "include": [
    "src/**/*.ts"
  ],
  "exclude": [
    "**/vite-env.d.ts"
  ]
}

The important options are:

{
  "compilerOptions": {
    "noLib": true,
    "types": [
      "typescript-baseline-lib",
      "@baseline-types/dom-widely-available"
    ]
  }
}

noLib removes TypeScript's standard ES and DOM libraries. The types entries replace them with the Baseline-oriented declarations.

Do not combine this configuration with the standard es* libraries. Doing so would reintroduce the APIs the gate is intended to remove.

I also recommend leaving skipLibCheck disabled. Declaration conflicts are useful signals here, not noise to suppress.

Why this config does not extend the build config

Many frontend projects already declare compilerOptions.lib.

Combining an inherited lib with noLib: true produces a configuration error. A standalone file is therefore the safest copy-paste starting point.

For a larger codebase, extract options such as strict, jsx, paths, and module resolution into a shared config that contains neither lib nor types. The normal build and Baseline check can then extend that shared configuration independently.

If the project contains TSX, add src/**/*.tsx to include and copy its existing jsx option into the Baseline config.

Vite client declaration note

A typical Vite project contains:

/// <reference types="vite/client" />

Vite's client declarations include asset modules and environment types, but they can also reference Worker APIs. Worker declarations are outside the scope of the DOM package used here.

For a strict browser-only gate, exclude the existing vite-env.d.ts and declare only the asset types your application uses:

// src/baseline-env.d.ts
declare module "*.css";

declare module "*.svg" {
  const url: string;
  export default url;
}

declare module "*.png" {
  const url: string;
  export default url;
}

If your application uses import.meta.env, add only the required ImportMetaEnv declarations to the same file.

This avoids widening the Baseline type surface with unrelated Worker globals.

See what the gate catches

Add a mix of established and newer APIs:

const newestOdd = [2, 5, 8, 11].findLast(
  (value) => value % 2 === 1,
);

const response = await fetch("https://example.com");

const observer = new ResizeObserver(() => {});

Promise.withResolvers<number>();
Array.fromAsync([1, 2, 3]);

new EyeDropper();

document.startViewTransition(() => {});

console.log(newestOdd, response.status, observer);

export {};

Run the dedicated check:

npx tsc -p tsconfig.baseline.json

The established APIs compile, while the APIs outside Widely Available are rejected:

error TS2550: Property 'withResolvers' does not exist on type 'PromiseConstructor'.

error TS2550: Property 'fromAsync' does not exist on type 'ArrayConstructor'.

error TS2304: Cannot find name 'EyeDropper'.

error TS2339: Property 'startViewTransition' does not exist on type 'Document'.

At the time of testing:

API	Baseline status	Result
`Array.prototype.findLast()`	Widely Available	Accepted
`fetch()`	Widely Available	Accepted
`ResizeObserver`	Widely Available	Accepted
`Promise.withResolvers()`	2024 Newly Available	Rejected
`Array.fromAsync()`	2024 Newly Available	Rejected
`EyeDropper`	Limited availability	Rejected
`Document.startViewTransition()`	2025 Newly Available	Rejected

Baseline status changes over time. These results were verified on July 23, 2026.

Turn it into a CI contract

Add a separate package script:

{
  "scripts": {
    "check:baseline": "tsc -p tsconfig.baseline.json"
  }
}

If your existing CI job already installs dependencies, adding this command may be enough:

npm run check:baseline

A standalone GitHub Actions workflow looks like this:

# .github/workflows/baseline-types.yml
name: Baseline API check

on:
  pull_request:
  push:
    branches: [main]

permissions:
  contents: read

jobs:
  baseline:
    runs-on: ubuntu-latest
    timeout-minutes: 10

    steps:
      - uses: actions/checkout@v6

      - uses: actions/setup-node@v6
        with:
          node-version: 24
          cache: npm

      - run: npm ci
      - run: npm run check:baseline

For an existing project, introduce this as a separate check first. Review the initial findings, decide how each API should be handled, and only then make the check required.

That avoids turning a useful policy migration into an unexplained wall of CI failures.

Rolling target or fixed year?

A moving target is appropriate for applications that want to adopt APIs as they become Widely Available:

{
  "compilerOptions": {
    "types": [
      "typescript-baseline-lib",
      "@baseline-types/dom-widely-available"
    ]
  }
}

The declaration set advances when the underlying compatibility data and packages are updated.

A fixed Baseline year is more suitable for a library contract, a long-lived release branch, or a product that updates its browser policy deliberately.

Install the matching DOM target:

npm install --save-dev @baseline-types/dom-2024

Then use the cumulative 2024 targets:

{
  "compilerOptions": {
    "noLib": true,
    "types": [
      "typescript-baseline-lib/year/2024",
      "@baseline-types/dom-2024"
    ]
  }
}

A year target contains APIs that became Baseline Newly Available by the end of that year. It is not the same as saying every API was already Widely Available during that year.

Do not combine a fixed year/* entry with the rolling root package.

Make polyfills explicit

Sometimes an API is outside the selected Baseline target, but your runtime intentionally provides it.

For example, core-js can provide Promise.withResolvers:

npm install core-js

Load the runtime implementation:

import "core-js/proposals/promise-with-resolvers";

Then add the matching audited declaration entry:

{
  "compilerOptions": {
    "noLib": true,
    "types": [
      "typescript-baseline-lib",
      "typescript-baseline-lib/allow/promise-withresolvers",
      "@baseline-types/dom-widely-available"
    ]
  }
}

This permits only that API. The rest of the Baseline boundary remains unchanged.

The allow/* entry changes type availability only. It does not install or load a runtime polyfill.

That separation is intentional: the runtime implementation and the type-level exception should both be visible in review.

What this check does not guarantee

This is an API-surface gate, not a complete browser compatibility system.

It does not guarantee:

That an API works without browser-specific bugs.
That requirements such as HTTPS, permissions, or user activation are met.
That your actual audience matches the Baseline browser population.
That JavaScript syntax, CSS, or HTML features meet the same target.
That dynamically accessed or deliberately untyped APIs will be detected.

The DOM declarations also preserve some supporting types to keep references valid. They should not be interpreted as a perfect rejection of every non-Baseline DOM symbol.

If your users include old embedded WebViews, managed enterprise browsers, or unusually long-lived devices, Baseline Widely Available may still be too broad. Browser analytics and runtime testing remain necessary.

For broader JavaScript checks, I also use eslint-plugin-baseline-js. It covers syntax and Web API cases that cannot be represented by a TypeScript declaration file.

Scope the check carefully in monorepos

noLib: true replaces the complete global TypeScript library.

That is useful for browser code, but it should not automatically be applied to every package in a monorepo.

For example, current Node.js declarations may depend on standard-library APIs that are newer than your selected Baseline target. A universal configuration combining browser, Node.js, test-runner, and framework globals can therefore produce dependency-level errors unrelated to your browser contract.

Run the gate over the source that actually shares the browser compatibility policy:

{
  "include": [
    "packages/browser/src/**/*.ts"
  ]
}

Keep separate build configurations for Node-only entry points, tooling, tests, and browser applications.

The boundary should follow the deployment environment, not the repository root.

Why generated declaration files?

Manually maintaining a list of APIs would become stale almost immediately.

typescript-baseline-lib generates its JavaScript declarations from the web-features compatibility dataset and TypeScript's own library declarations. The repository checks in its dataset snapshot, classification reports, declaration inventory, generated output, and audit results.

@baseline-types applies Baseline filtering to the generator used for TypeScript's DOM declarations.

The two projects deliberately cover different surfaces:

Package	Surface
`typescript-baseline-lib`	JavaScript built-ins such as `Promise`, `Array`, `Map`, and `Intl`
`@baseline-types/dom-*`	DOM and web platform APIs such as `Document`, `Window`, and `ResizeObserver`

The package lock then makes a given CI run reproducible.

Where this is going

typescript-baseline-lib is currently a public alpha. I recommend adopting it as an additional CI gate before making it the only TypeScript configuration for a production application.

The longer-term goal is first-class TypeScript support:

{
  "compilerOptions": {
    "lib": [
      "baseline"
    ]
  }
}

The corresponding TypeScript proposal is currently awaiting more real-world feedback.

If you try the package, the most useful feedback is concrete:

Which project and TypeScript version did you test?
Which API did the gate catch?
Was the result expected?
Did a framework or ambient type package introduce a conflict?
Could the check remain enabled in CI?

Try it on one browser-only package:

npm install --save-dev \
  typescript@^7 \
  typescript-baseline-lib \
  @baseline-types/dom-widely-available

npx tsc -p tsconfig.baseline.json

Browser compatibility policies should not depend on every reviewer remembering the support status of every API.

A small, reproducible CI check is a better contract.

Bringing Baseline into Product Development — and Keeping It Safe in Practice

Leo — Wed, 10 Sep 2025 04:10:25 +0000

Baseline gives teams a simple way to answer a hard question: when is a web platform feature safe to use everywhere that matters? Instead of juggling browser-version matrices, you align on a shared, function-level line and make consistent, defensible decisions.

There is also a clear business angle. If a user’s browser silently lacks a feature you rely on, you can lose conversions, trigger avoidable support tickets, and erode trust without anyone noticing the root cause. Treating Baseline as a product standard reduces that risk. It turns a nebulous, recurring debate into a policy you can document, audit, and enforce automatically.

A quick primer on Baseline

Baseline tracks when a feature reaches parity across the four major engines (Safari, Chrome, Edge, and Firefox). It communicates readiness in three stages:

Limited availability — Not yet supported in all Baseline browsers; treat as experimental and avoid for production unless you have a well‑designed fallback.
Newly available — Supported in all current stable releases; good default for early adoption with care.
Widely available — Newly, plus 30 months of universal support; practical proxy for very low risk in the wild.

You can also target by year. For example, “2023” means: allow anything that became Baseline newly available in 2023 or earlier.

It is a feature‑first lens. Rather than anchoring on version lists for each browser, you ask, “Has this capability reached the line?” and get a single answer you can reason about.

Choosing “our Baseline”

Start with Widely as the default. It’s a conservative, low‑friction starting point because it bakes in real‑world adoption time after universal support lands.

Then estimate “our Year.” Use your analytics or RUM to understand the browsers your users actually run. Vary the year (2021, 2022, 2023, …) and estimate coverage. If you use Google Analytics, the Google Analytics Baseline Checker can visualize this; otherwise, you can massage internal logs into the same shape.

Finally, define your exception policy. Some features come with reasonable fallbacks you can ship today and progressively enhance later. Others carry more cross-browser risk and should wait even if they are technically Widely. Write down how exceptions are proposed, reviewed, and documented.

This sequence—safe default, data-informed tuning, explicit exceptions—makes the policy clear and keeps decisions explainable.

Why not rely on UA tables alone?

User-Agent strings are easy to spoof and often polluted by crawlers and scanners. Even when they are accurate, a version label does not capture enterprise policies, flags, or safety modes that can disable capabilities. UA-led policies also force you to manage version matrices, which age poorly and rarely map cleanly to how specifications group features.

Baseline draws the line at the capability itself. Keep UA data for coverage estimates and stakeholder communication, but let features drive the decision.

Bringing it into the workflow

First, set your build/transpile targets to align with your chosen Baseline. Some tools default to Widely already; others let you convert Baseline to a Browserslist query or an esbuild target. The goal is that the code you ship matches the line you agreed on.

Second, catch issues where they happen: in the editor and in CI. ESLint can enforce Baseline for JavaScript, and complementary plugins can do the same for CSS and HTML. When someone reaches for a feature that sits beyond the line, they see a precise, actionable message before it merges.

Third, document the policy. State the default (for example, “Widely”), the way you set the year, and how exceptions work. That turns a tribal norm into policy-as-code and keeps newcomers aligned.

Example: don’t use `Date#getYear()/setYear()`

Date#getYear() and Date#setYear() are deprecated. They also fall below a sensible Baseline threshold. Reaching for them is a recipe for subtle bugs.

With a Baseline rule enabled, you would see a message like:

One policy, three surfaces: JS, CSS, and HTML

The easiest way to make Baseline “real” for your team is to enable it where code is written. JavaScript is the obvious starting point, but it helps to bring CSS and HTML into the same conversation so your policy feels coherent.

Here is a Flat Config example that wires the three together. Adjust the file globs and the strictness to match your repo. The JavaScript section uses the built‑in presets exposed by eslint-plugin-baseline-js.

// eslint.config.js (Flat Config)
import tsParser from "@typescript-eslint/parser";
import baselineJs, { BASELINE } from "eslint-plugin-baseline-js";
import cssPlugin from "@eslint/css";
import htmlPlugin from "@html-eslint/eslint-plugin";
import htmlParser from "@html-eslint/parser";

export default [
  // Register the JS plugin once
  { plugins: { "baseline-js": baselineJs } },

  // JavaScript (JS) — recommended preset (auto Web APIs + JS builtins)
  baselineJs.configs.recommended({ available: BASELINE.WIDELY, level: "warn" }),

  // TypeScript (TS) — attach parser + type-aware preset
  {
    files: ["**/*.{ts,tsx}"],
    languageOptions: { parser: tsParser, parserOptions: { project: ["./tsconfig.json"] } },
  },
  baselineJs.configs["recommended-ts"]({ available: BASELINE.WIDELY, level: "warn" }),

  // CSS: Baseline
  {
    files: ["**/*.{css,scss}"],
    plugins: { "@css": cssPlugin },
    language: "@css/css",
    rules: { "@css/use-baseline": ["warn", { available: "widely" }] },
  },

  // HTML: Baseline
  {
    files: ["**/*.{html,htm}"],
    plugins: { "@html-eslint": htmlPlugin },
    languageOptions: { parser: htmlParser },
    rules: { "@html-eslint/use-baseline": ["warn", { available: "widely" }] },
  },
];

Notes

You can target a specific year (e.g., { available: 2022 }). Items with “Limited availability” are treated as beyond the configured year, so they will be flagged until they enter Baseline.
The single rule is baseline-js/use-baseline. Presets above expand it for JS and TS with sensible defaults (auto for JS, type‑aware for TS).

Closing thought

Baseline is a way to agree on reality. Pick a line, show your work, and let tooling hold it for you. That is how teams move fast without gambling with user experience.

Translate Markdown to Any Language (GitHub Bot)

Leo — Fri, 31 Mar 2023 14:38:32 +0000

Most open-source projects are written in English, raising barriers to participation from speakers of other languages. In addition, translation is a labor-intensive process, so documentation has yet to be internationalized to a great extent.
I have created a GitHub Actions that automatically translate documents using multiple AI models.
It is open source and requires an individual API key, but it is free.

Setup

All you need is an Open AI API Key and Actions workflow settings. Please see README for details.

To prevent your API KEY from being misused, we only allow people who have write permission to access the repository to run the bot.

Usage

Once the workflow is set up, comment on the issue or pr with a command to translate the input file.

/gpt-translate [input filepath] [output filepath] [target language]

Comment on Issues

View Actual Issues

Auto-generated PR

A PR is created depending on where the command is entered. (If you comment on a PR, the commit is added to that PR.)

View actual PR

Interestingly, I could translate Voynich's Manuscript (undeciphered script), ancient Greek, and other languages. (Not possible with GPT-4)
We could also build a kind of OSS document for time travelers :)

Human-in-the-Loop

Originally, the texts translated by GPT are of fairly high quality.

However, a human can also review the translation files created by this bot to perfect the translation further.

GitHub's function to accept reviews as is on a new commit allows us to build a very seamless translation experience.

If you have any suggestions for improvement or bugs, please feel free to write them in Issues!

🌎As a non-English speaking person, I would be happy if the various OSS are easier to understand!

Repo

Thanks for the 250 stars🌟

3ru / gpt-translate

💬Translate Files into Any Languages with AI

🌎 Markdown Translation BOT

This GitHub action translates your markdown files into multiple languages using multiple AI models.

Tip

Now Available: AI Models from Multiple Providers✨
We've expanded beyond OpenAI to support various AI model providers.
For a comprehensive list of supported providers and detailed information, please refer to our release notes.

🧐 Current Status

The action supports translating markdown(.md), markdown-jsx(.mdx), json(.json) files only.
The command can be executed exclusively by individuals with write permissions to the repository.

These limitations prevent API abuse by non-trusted parties.

🔧 Setup

Repository Settings

1. Settings > Actions > General

Enable Read and write permissions
Enable Allow GitHub Actions to create and approve pull requests

2. Settings > Secrets and variables > Actions

Set your API key(OPENAI_API_KEY) to…

View on GitHub

This is my very first OSS and I would be happy if you like it.