Skip to content

About

✅ ESLint plugin to enforce the JavaScript Baseline.

Topics

Resources

Contributing

Stars

235 stars

Watchers

2 watching

Forks

Repository files navigation

eslint-plugin-baseline-js

baseline

Enforce the JavaScript Baseline (widely / newly / year) with a single ESLint rule powered by web‑features. This plugin delegates detection to eslint-plugin-es-x and ESLint core (plus a few small gap‑filling rules) and reports with one consistent Baseline message.

npm version npm downloads bundle JSDocs License CI

Note

This project hasn’t reached a major release yet, so behavior and options may change. Please feel free to report false negatives/positives and any rough edges as issues.

Install

  • npm: npm i -D eslint-plugin-baseline-js
  • pnpm: pnpm add -D eslint-plugin-baseline-js
  • yarn: yarn add -D eslint-plugin-baseline-js

Recommended

  • ESLint >= 9.29.0 and < 11 (Flat Config)

Quick Start (Flat Config)

// eslint.config.js
import baselineJs from "eslint-plugin-baseline-js";

export default [
  {
    files: ["**/*.{js,ts,jsx,tsx}"],
    plugins: { "baseline-js": baselineJs },
    rules: {
      // Allow only "widely available" Baseline features
      "baseline-js/use-baseline": ["error", { available: "widely" }],
    },
  },
];

Preset Configs

This plugin ships Flat Config presets you can call from configs:

import baselineJs from "eslint-plugin-baseline-js";

export default [
  // Register the plugin once (required for Flat Config)
  { plugins: { "baseline-js": baselineJs } },

  // Recommended: enables Web APIs & JS builtins detection with `preset: 'auto'`.
  // Level defaults to 'error'; pass level to change severity
  baselineJs.configs.recommended({ available: "widely", level: "warn" }),

  // TypeScript-aware: requires type info for instance-member checks (`preset: 'type-aware'`).
  // Works best with @typescript-eslint/parser and a proper tsconfig.
  // baselineJs.configs["recommended-ts"]({ available: "widely", level: "error" }),
];

Note on plugin key

  • Presets assume the plugin is registered under the key "baseline-js".

See more real-world configs in examples/

Common Configurations

// Newly available (more permissive)
'baseline-js/use-baseline': ['warn', { available: 'newly' }];

// Year-based – allow features that became Baseline in or before 2020
'baseline-js/use-baseline': ['error', { available: 2020 }];

// Ignore knobs for pragmatic adoption
'baseline-js/use-baseline': [
  'error',
  {
    available: 2018,
    // Skip specific web-features by ID (or regex as '/.../')
    ignoreFeatures: ['nullish-coalescing', '/^optional-/'],
    // Skip reports produced on certain ESTree node types
    ignoreNodeTypes: ['WithStatement', '/Expression$/'],
  },
];

// Turn off in tests or generated folders (ESLint standard overrides)
export default [
  { /* project defaults ... */ },
  {
    files: ['**/*.test.*', 'coverage/**'],
    rules: { 'baseline-js/use-baseline': 'off' },
  },
];

What Gets Reported?

Features from web‑features (group: "javascript") that exceed your configured Baseline.

Baseline setting Reports when...
"widely" the feature is not in Baseline “high”
"newly" the feature is marked as limited (false)
year (number) the feature’s Baseline year is greater than year

Demo

For type-level checks too, pair it with typescript-baseline-lib, which gives TypeScript a built-in lib selected by Baseline data. Try the demo to check JavaScript APIs with TypeScript and ESLint in your editor and CI. Its example PR changes one line to use Set.prototype.difference() and intentionally fails both checks.

getYear is deprecated

How It Works

  1. Data → scripts/data/build-features.mjs
    • Extracts the minimal JavaScript subset from web‑features into src/baseline/data/features.javascript.ts.
  2. Mapping → src/baseline/mapping/syntax.ts
    • Maps web‑features IDs to underlying rules (prefer eslint-plugin-es-x / ESLint core; custom rules only when necessary).
  3. Resolution → src/baseline/resolve.ts
    • Classifies “beyond baseline” by bucket (high/low/false → widely/newly/limited) or year.
    • Web API and JS builtin checks use the matched API member's own Baseline status from web‑features status.by_compat_key when it differs from the feature's, so URL.parse() is newer than the url feature.

Coverage

We publish a generated coverage report that lists all JavaScript features from web‑features and shows which ones are currently mapped by this plugin.

  • Report: docs/coverage.md
  • Regenerate locally: pnpm gen:coverage
    • Generator: scripts/coverage/generate-coverage.mjs

Options (rule)

Option Type Default Description
baseline widely, newly, number, widely Baseline level or year (alias: available).
ignoreFeatures string[] — Skip specific web‑features by ID (supports regex /.../) across syntax delegates and Web API/JS builtin detection.
ignoreNodeTypes string[] — Suppress reports by ESTree node.type (supports regex /.../).

Use with oxlint

See Linter compatibility for versioned Baseline check results under ESLint, Oxlint, and Bun.

Runs as an oxlint JS plugin. Just drop it into .oxlintrc.json:

// .oxlintrc.json
{
  "jsPlugins": ["eslint-plugin-baseline-js"],
  "rules": {
    "baseline-js/use-baseline": [
      "warn",
      {
        "available": "widely",
        "includeWebApis": { "preset": "auto" },
        "includeJsBuiltins": { "preset": "auto" }
      }
    ]
  }
}

Caution

Oxlint and Bun do not currently expose TypeScript type information through their JavaScript plugin APIs. Type-aware Baseline checks, such as Set.prototype.difference() and Iterator.prototype.map(), therefore cannot run in these hosts. Use the ESLint TypeScript setup to enable these checks.

Baseline for HTML, CSS, and React

Baseline works best when HTML, CSS, JS, and React all align. For markup, styles, and React, enable the "use-baseline" rules from these ESLint plugins:

Branding Note (Baseline)

The Baseline name and logos are Google trademarks. Logo assets are licensed under CC BY‑ND 4.0. If you use Baseline logos alongside this plugin, please follow the official guidelines and do not imply sponsorship, affiliation, or endorsement by Google. We embed the official Baseline icons via their published URLs (unmodified).

License

MIT


Thanks to Anthropic for sponsoring

About

✅ ESLint plugin to enforce the JavaScript Baseline.

Topics

Resources

Contributing

Stars

235 stars

Watchers

2 watching

Forks

Releases

Packages

Used by

Contributors

Languages