eslint-plugin-baseline-js

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.

[!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 >= 8.57 (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

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.

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 /.../). |

Baseline for HTML and CSS

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

• ESLint for CSS: https://github.com/eslint/css
• HTML ESLint: https://github.com/yeonjuan/html-eslint

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