🧩 Bring Baseline browser compatibility insights directly inside VS Code — with real-time diagnostics, hovers, quick fixes, MDN links, and full reports.

Baseline Assistant brings browser compatibility awareness into your editor — powered by the official Baseline dataset, plus MDN and web‑features.
Detect, explain, and safely fix non‑Baseline APIs before they break in production.
This document is the advanced reference for usage, configuration, quick fixes, and integration details.

• Requirements
• Why Baseline Assistant?
• Installation
• Usage (Getting Started)
• Key Features
• Available Quick Fixes
• MDN Integration
• How It Works
• Commands
• Settings (quick start)
• Settings reference
• Status bar & commands
• Configuration files
• Quick Testing
• Development & Packaging
• Performance
• Design Philosophy
• Known Limitations
• License
• Feedback & Contributions
• Contact
• About the Project / Team

• VS Code ≥ 1.85.0
• Node.js ≥ 18 (LTS recommended: 18 or 20)
• npm ≥ 9
• (Optional) Git

🔒 Security: the extension does not run in Untrusted Workspaces (see capabilities.untrustedWorkspaces).

Modern web APIs evolve fast; it’s easy to ship features that aren’t yet part of the Baseline set, causing unexpected compatibility issues.

Baseline Assistant integrates the official Baseline dataset, combined with web-features and MDN data, directly into VS Code.
It shows which features are safe to use for your chosen Baseline year, warns when code relies on non‑Baseline APIs, and offers quick, safe fixes — all without leaving your editor.

1. Install Visual Studio Code (v1.85.0 or later).
2. Download the latest .vsix from Releases or build locally:

npm ci
npm run package             # uses @vscode/vsce via npm scripts
# equivalent:
npx vsce package            # if vsce is not in your PATH

3. Install the VSIX extension into VS Code:

# if vsce produced a simple pattern
code --install-extension baseline-vscode-*.vsix

# or if the VSIX includes publisher & name (recommended)
code --install-extension baseline-local.baseline-vscode-*.vsix

1. Open a JavaScript/TypeScript/CSS/HTML file (React/Vue/Svelte templates are also recognized).
2. Run Baseline: Rescan Active Editor from the Command Palette, or simply save the file.
3. Hover an API to see Baseline compatibility and Quick Fixes.
4. Use Baseline: Open Overview Panel for workspace-wide stats.

ℹ️ Baseline commands are available even without an open file (command-based activation).

Diagnostics	Hover Info	Quick Fix

(Add screenshots to assets/ to showcase the experience.)

✅ Official Baseline Integration – Uses Baseline cohorts (2023–2025) to detect non‑Baseline APIs.
⚡ Real-time Diagnostics – Highlights unsupported or risky features in JS, TS, CSS, and HTML.
💬 Hover Insights – Shows Baseline status (with “since YEAR” when known), your target Baseline year, MDN links, and compatibility notes.
🧠 Smart Quick Fixes – Wrap or refactor unsupported CSS features (e.g., @scroll-timeline, animation-timeline, view-transition-name).
🔄 Browserslist Detection – Reads your project’s targets and adapts messages accordingly.
📊 Explorer Decorations – Per-file issue counters right in the Explorer.
📤 Report Export – Generate detailed JSON or Markdown reports.
⚙️ Customizable Rules – Configure severities, debounce delay, ignored folders, and UI behavior.
🪶 Lightweight & Fast – Caching and debounce keep the experience smooth.

Baseline Assistant focuses on safe-by-default fixes (guard/comment) and opt-in fallbacks when semantics might change.

Examples

/* Wrap a property with @supports */
@supports (scroll-timeline: auto) {
  .scroller { scroll-timeline: my-tl; }
}

/* Replace animation-timeline with a plain animation fallback */
.scroller {
  /* @baseline-note:css-animation-timeline */
  /* Baseline fallback */
  animation: var(--baseline-fallback-animation, none);
}

/* Guarded use of view-transition-name */
@supports (view-transition-name: none) {
  .page { view-transition-name: page; }
}

/* Comment + guidance
   --baseline-view-transition-name: page;
   @supports (view-transition-name: none) {
     view-transition-name: var(--baseline-view-transition-name);
   }
*/

/* Guard View Transitions API */
if (document && typeof document.startViewTransition === "function") {
  document.startViewTransition(() => {
    // transition logic
  });
} else {
  /* Baseline fallback: API unavailable — apply the update directly */
}

Note on structuredClone: a JSON-based fallback drops functions, Symbols, Map/Set, Dates, typed arrays, and circular refs. It’s a compatibility hint, not a drop‑in replacement.
Extra transpilation helper: ?? (Nullish Coalescing) → rewrite to (a !== null && a !== undefined ? a : b) and link to Babel/SWC docs.

• Hover: shows Documentation (MDN) when available for the feature. If no exact link is known, a Search on MDN link is provided.
• Problems panel: every diagnostic includes a clickable MDN docs link (exact page when known, otherwise an MDN search).

1. Reads your Browserslist (.browserslistrc or package.json) to detect your target environment (or forces the target when baseline.browserslistOverride is set).
2. Loads the official Baseline dataset to determine which features are Baseline-safe for the selected year.
3. Cross-references MDN and web-features data to identify risky or deprecated APIs.
4. Analyzes open files (JavaScript, TypeScript, CSS, HTML) and flags unsupported features.
5. Shows diagnostics, hover details, and Quick Fixes inside the editor.
6. Lets you rescan or export reports anytime from the Command Palette.

Architecture overview

Editor Events → Parser → Feature Matcher
         ↓               ↓
   Browserslist Loader    ↘
         ↓                 Compatibility Engine
         ↓                        ↓
     Diagnostics ← Hover Info ← Quick Fix Builder

💡 Tip: Customize or disable shortcuts in File → Preferences → Keyboard Shortcuts (Ctrl + K Ctrl + S) and search for Baseline.

Put this in .vscode/settings.json:

{
  "baseline.enabled": true,
  "baseline.languages": ["javascript", "typescript", "css", "html"],
  "baseline.analysisDebounceMs": 250,
  "baseline.year": "latest",            // also: "2025", "2024", "2023"
  "baseline.browserslistOverride": "",
  "baseline.browserslistEnv": "",
  "baseline.fallbackToDefaults": true,
  "baseline.severities": { "css-has": "warning" },
  "baseline.ignore": ["**/node_modules/**", "**/dist/**", ".baseline/**"],
  "baseline.ui": {
    "decorations": true,
    "codelens": true,
    "telemetry": false
  },
  "baseline.verboseLogging": false
}

Type: boolean • Default: true
Turns the extension on/off for the workspace. When false, diagnostics and decorations are cleared.

Type: string[] • Default: ["javascript","typescript","css","html"]
List of VS Code language IDs to analyze.
Notes:

• React variants are recognized automatically (javascriptreact → JS, typescriptreact → TS).
• scss/less are treated as CSS internally.

Type: number (ms) • Default: 250
How long to wait after you stop typing before re-analyzing the current file.

Type: "latest" | "2025" | "2024" | "2023" • Default: "latest"
Selects the Baseline dataset year used by the rules.

Type: string (Browserslist query) • Default: ""
Forces the target environment regardless of files on disk.
Examples: "chrome 104", "last 2 chrome versions, ios >= 16, not dead".
When non-empty, this takes precedence over .browserslistrc/package.json.

Type: string • Default: ""
Selects the environment when your Browserslist defines multiple envs.
Examples: "production", "development".
If empty, the extension tries process.env.BROWSERSLIST_ENV, then NODE_ENV, then auto.

Type: boolean • Default: true
When no Browserslist config is found or it resolves to nothing:

• true → use Browserslist defaults.
• false → run in generic mode (no specific targets). Diagnostics still appear, but phrasing is generic (Baseline vs Non‑Baseline) rather than per‑target.

Type: string (path) • Default: "data/baseline-rules.json"
Path (relative to the workspace) to a JSON file that adds and/or overrides rules by id.
This file is merged after the Baseline/web‑features rules and before baseline.severities is applied. See Configuration files → External rules for schema.

Type: object map of <rule-id> -> "off" | "info" | "warning" | "error" • Default: {}
Per-rule severity overrides (UI only). Example:

"baseline.severities": {
  "css-has": "warning",
  "view-transitions-api": "off"
}

Type: string[] (glob patterns) • Default: ["**/node_modules/**","**/dist/**",".baseline/**"]
Files/folders to ignore during analysis (micromatch globs).

Type: boolean • Default: true
Shows inline gutter/overview decorations for detected features.

Type: boolean • Default: true
Shows CodeLens above unsupported features with quick fixes (when available).

Type: boolean • Default: false
Enables minimal, privacy-friendly telemetry for UI affordances (never your source code).

Type: boolean • Default: false
Prints detailed logs to the Baseline Assistant output channel (useful for debugging target resolution and rule matches).

• The status bar shows something like Baseline: env:production or the active Browserslist query.
  Hover it to see the environment label, a short sample of resolved targets, and the source (for example: settings, .browserslistrc, package.json#browserslist, defaults).
• Useful commands (⇧⌘P / Ctrl+Shift+P):
  • Baseline: Refresh Browserslist — re-reads config and rescans files.
  • Baseline: Rescan Active File — re-runs analysis on the current editor.
  • Baseline: Fix All in File / Workspace — applies available quick fixes.

Three kinds of files influence rules and targets.

Holds all options described above.

Default path: data/baseline-rules.json (configurable via baseline.rulesFile).
This file lets you add custom rules and/or override rules generated from Baseline/web‑features (by id).
Changes are picked up on activation or when you run Baseline: Refresh Data.

Schema

{
  "rules": [
    {
      "id": "css-animation-timeline",
      "title": "Scroll-driven animations: animation-timeline",
      "languages": ["css", "html"],                     // optional; inferred from id if omitted
      "pattern": "/animation[-\s]*timeline\s*:/i",     // string RegExp or { "source": "...", "flags": "i" }
      "baseline": false,                                 // whether it should be treated as “Baseline” in info
      "severity": "warning",                             // default UI severity: "info" | "warning" | "error"
      "supportNote": "Safari TP only",                   // optional; shown in hover
      "docs": "https://developer.mozilla.org/..."        // optional; MDN link in hover/Problems
    }
  ]
}

Priority (rules):

1. Baseline rules (web‑features + built‑in CSS safety nets)
2. Merge/override via external rules file (baseline.rulesFile, default data/baseline-rules.json)
3. baseline.severities adjusts the final UI severity

ℹ️ The engine deduplicates by family + pattern and prefers certain top‑level IDs; when equal, lexical order of the id wins.

Defines your target browsers with Browserslist.
If multiple environments are defined, select one with baseline.browserslistEnv.

Example .browserslistrc

[production]
last 2 Chrome versions
last 2 Firefox versions
iOS >= 16
not dead

[development]
last 1 Chrome version
last 1 Firefox version

Source & priority (Browserslist)

1. baseline.browserslistOverride (if non-empty)
2. .browserslistrc or package.json#browserslist (honoring baseline.browserslistrc if set)
3. If nothing is found and baseline.fallbackToDefaults: true → Browserslist defaults
   (The status bar indicates the active source: settings, .browserslistrc, package.json#browserslist, defaults.)

If the config is empty/invalid

• With baseline.fallbackToDefaults: true → Baseline uses defaults.
• With baseline.fallbackToDefaults: false → Baseline runs in generic mode (no specific targets). Messages reflect Baseline vs Non‑Baseline rather than a per‑target verdict.

• The Problems panel shows each issue’s rule id; use that id in baseline.severities or in your external rules file.
• You can open an MDN link directly from the diagnostic code in the Problems panel.

1. Open a JavaScript, TypeScript, CSS, or HTML file.
2. Hover a modern feature (e.g., scroll-timeline, :has(), view-transition-name).
3. See the Baseline hover with MDN info and the year of Baseline inclusion.
4. Run Baseline: Fix All In File to wrap unsupported CSS features.
5. Use Baseline: Export Report to generate a workspace-wide compatibility summary.
6. Change .browserslistrc (or package.json#browserslist) — the extension will auto‑rescan. You can also run Baseline: Refresh Browserslist manually if needed.

git clone https://github.com/TD-AI-Lab/baseline-vscode
cd baseline-vscode
npm ci
npm run build
npm run package        # uses @vscode/vsce (local binary via npm scripts)
# or
npx vsce package       # alternative equivalent

Run in VS Code (Dev)

• Open the folder in VS Code
• npm ci
• npm run build (or npm run watch)
• Press F5 → launches the Extension Development Host

Keep your VSIX lean — example .vscodeignore:

**/*.ts
**/*.map
src/**
test/**
.git/**
.github/**
.vscode/**
node_modules/**

# out/** and assets/** remain included via "files" in package.json

• Local-first: no network calls during analysis.
• Debounced, incremental scans with caching for a smooth experience.
• Designed to work across multiple open editors without blocking.

1. Local-first — instant feedback with zero external dependencies during analysis.
2. Transparent — clear rule IDs, hover details, and Problems-panel links back to MDN.
3. Safe-by-default — Quick Fixes never silently change semantics; guard/comment patterns are preferred.

• Quick Fixes mainly target CSS for now; most JS/DOM rules are diagnostics-only.
• Partial framework template coverage (Vue/Svelte).
• No automated test suite yet.

Roadmap: JS/DOM fixers, async FS reads, stats panel, tests.

Released under the MIT License — see LICENSE.

Please open issues and PRs at:
https://github.com/TD-AI-Lab/baseline-vscode

📧 tdai.flo@gmail.com
🐦 https://x.com/TD_AI_Lab

This extension was conceived and developed for the Google Hackathon 2025 to bring Baseline browser-compatibility intelligence directly to developers’ editors.
The project reflects an engineering focus on clarity, safety, and real-world usefulness — from diagnostics and hovers to Quick Fixes and configurable rules.

“Built for the web, by those who love to make it better.”

© 2025 Baseline Assistant — Built with ❤️ for the Google Hackathon.