Baseline CLI

Inspiration

We've all been there - you ship a feature that works perfectly in Chrome, then get bug reports from Safari users saying everything's broken. Or worse, you're using some cool new CSS feature and find out later that a third of your users can't even see your site properly.

The problem is that keeping track of browser compatibility is a nightmare. Can I use container queries? Is optional chaining safe yet? You end up with 15 tabs open on caniuse.com, cross-referencing everything manually. We wanted to build something that just tells you "hey, this code won't work for X% of your users" before you ship it.

What it does

Baseline CLI is a command-line tool that scans your HTML, CSS, and JavaScript files and checks every feature against the Web Platform Baseline - basically the stuff that works everywhere vs. the cutting-edge stuff that doesn't yet.

It catches things like:

That fancy CSS Grid syntax that Safari 14 doesn't support
JavaScript features like private class fields that aren't quite baseline yet
Vendor-prefixed properties you forgot to clean up
Modern HTML elements that might need polyfills

But here's the cool part - we didn't just stop at checking. We added an AI-powered fix command that actually rewrites your CSS to be more compatible. It removes old vendor prefixes, updates gradient syntax, and suggests modern alternatives. You can review the changes before applying them, so you're always in control.

How we built it

The core is TypeScript, using VS Code's language services to parse CSS and HTML (the same parsers that power VS Code itself), and the TypeScript Compiler API for JavaScript/TypeScript analysis. We hooked it up to the official web-features dataset from the Chrome team, which tracks what's actually available across browsers.

For the AI fixes, we integrated both OpenAI and Anthropic APIs. The CLI generates diffs so you can see exactly what's changing before you accept it.

The tricky part was making it work everywhere - CI/CD environments, local dev, you name it. We used esbuild to bundle everything into a single executable that just works. Also added support for config files, environment variables, and .env files so teams can set it up however they want.

Challenges we ran into

The ESM/CommonJS nightmare: The web-features package is ESM-only, but most CI/CD environments still expect CommonJS. We spent hours fighting with module systems before finally figuring out how to bundle it properly with esbuild and polyfill import.meta for the CJS output.

Parsing is hard: CSS has like 1,800 properties, JavaScript has dozens of node types, and HTML is its own beast. Mapping all of that to web features was... a lot. We ended up building a massive mapping system that checks everything from CSS selectors to JS API calls.

Making AI suggestions actually good: Early versions of the fix command would suggest terrible changes. We had to tune the prompts carefully to make sure it modernizes code without breaking it or making it worse.

Accomplishments that we're proud of

538 features detected accurately across HTML, CSS, and JavaScript
Zero dependencies for the end user - just npm install -g and go
Actually published and working on npm - you can install and use it right now
Real AI fixes that work - not just theoretical, we tested it on actual legacy codebases
Beautiful HTML reports that you can share with your team

What we learned

Browser compatibility is way more complex than we thought. There are thousands of features, and the baseline status changes constantly as browsers update. We also learned that building a good CLI isn't just about functionality - the UX matters a ton. Progress bars, colors, clear error messages - all that stuff makes the difference between a tool people use and one they abandon.

Also, the npm publishing workflow is surprisingly finicky when you're dealing with binary bundling and cross-platform compatibility.

What's next for Baseline CLI

Framework-specific checks - add support for React/Vue/Svelte so we can catch framework-specific compatibility issues
Custom baseline targets - let teams define their own browser support matrix (e.g., "last 2 versions + IE 11")
Automatic polyfill suggestions - when we detect a non-baseline feature, suggest the right polyfill
VS Code extension - inline warnings right in your editor as you code
GitHub Action - pre-built action so you can just drop it in your workflow
Fix command for JavaScript - right now we only fix CSS because JS is riskier, but we want to expand this with better safety checks