Baseline overlay

A Vite plugin that displays an in-browser warning overlay for code with non-Baseline APIs.

Comment

Baseline Overlay

Inspiration

I was inspired by the challenge of building web applications that work consistently across all browsers. I wanted to create a tool that sits directly in the development cycle to help developers make informed decisions about API usage during development, not after deployment.

What it does

Baseline Overlay is a Vite plugin that provides real-time monitoring of web API usage in your development environment. It scans your JavaScript and CSS files for potentially non-baseline APIs and displays warnings in an elegant overlay directly in your browser.

The tool:

  • Shows detailed compatibility information including which browsers support each API and which don't
  • Provides spec documentation links for each detected API
  • Displays warnings in a beautiful overlay that appears in the bottom-right corner of your browser
  • Works with both JavaScript and CSS files, detecting modern CSS features and JavaScript APIs
  • Integrates seamlessly with Vite development server using WebSocket communication
  • Accurate line number detection that points to the exact location of non-baseline APIs in your source code

How we built it

Core Plugin Architecture:

  • Created a Vite plugin that hooks into the build process using both load and transform hooks
  • Used WebSocket communication to send warnings from the plugin to the browser overlay
  • Solved the challenge of accurate line number detection by reading original source files instead of transformed code

API Detection System:

  • Built a JavaScript scanner using Babel's parser to traverse AST and detect member expressions like navigator.keyboard
  • Created a CSS scanner using PostCSS
  • Implemented pattern matching to identify potentially non-baseline APIs
  • Added line number tracking that works with Vite's transformation pipeline

Baseline Checking:

  • Integrated with the web-features database to check if detected APIs are truly baseline
  • Built a checking system that cross-references APIs against browser support data
  • Added browser support information showing which browsers support each API

User Interface:

  • Created a vanilla JavaScript overlay component
  • Implemented WebSocket communication with fallback to polling for reliable warning delivery
  • Designed a responsive overlay with detailed information including file locations, accurate line numbers, and browser support
  • Built a beautiful, non-intrusive interface that doesn't interfere with development workflow

Tech Stack:

  • Vite plugin system for build integration
  • Babel parser for JavaScript AST traversal
  • PostCSS for CSS parsing
  • Vanilla JavaScript for the overlay UI
  • WebSocket for real-time communication
  • TypeScript for type safety

Challenges we ran into

  • Accurate Line Number Detection: Getting accurate line numbers for detected APIs was a bit of an hassle. Initially, the AST was processing transformed code from Vite's build pipeline, which shifted line numbers significantly. I solved this by reading the original source files directly instead of relying on the transformed code

  • WebSocket Connection Issues: Getting reliable communication between the Vite plugin and the browser overlay was challenging. The WebSocket connection would hang or fail to establish properly. I resorted to a timeout mechanism and fallback to polling to ensure warnings always reach the user.

  • ES Module Import Extensions: The plugin was using ES modules but missing .js file extensions in relative imports, causing module resolution failures.

  • Incorrect Source Directory Path: The plugin was scanning its own /src directory instead of the host project's source files.

Accomplishments that we're proud of

  • Seamless Developer Experience: I'm particularly proud of how the tool integrates into the development workflow without being intrusive. The overlay appears only when there are actual issues, and the design is clean and informative.

  • Accurate Line Number Detection: Successfully solved the complex challenge of getting accurate line numbers by reading original source files instead of transformed code.

  • Real-time Feedback The WebSocket integration provides instant feedback as developers write code, catching compatibility issues before they become problems.

What we learned

  • Vite Plugin Development: I gained understanding of Vite's plugin system and how to hook into the build process effectively.

  • AST Manipulation: Working with Babel's AST gave me valuable experience in code analysis and traversal

  • Line Number Accuracy

Built With

Share this project:

Updates