Storybook Addon Baseline

Automatically detect browser compatibility for your Storybook components using Baseline data. Supports React, Vue, Angular with CSS-in-JS detection.

Comment

Storybook Addon Baseline - Project Story

Inspiration

The inspiration came from Google's Baseline initiative - a unified way to understand browser compatibility for web features. As developers, we constantly struggle with questions like "Can I use CSS Grid?" or "Is container queries safe to use?" While tools like caniuse.com exist, they require context switching away from our development workflow.

We realized that Storybook - where developers already build and document their components - was the perfect place to surface this information. Why not automatically detect CSS features from your components and show browser compatibility right in your development environment?

The goal was simple: Make browser compatibility a first-class citizen in the component development workflow.

What it does

Storybook Addon Baseline automatically detects CSS features used in your components and displays their browser compatibility using Google's Baseline data.

Key Features:

  1. Automatic CSS Detection - Analyzes your component styles and detects 40+ modern CSS features (Grid, Flexbox, Container Queries, :has(), oklch(), etc.)

  2. Multi-Framework Support:

    • React: Extracts CSS from styled-components, Emotion, and Stitches
    • Vue: Parses Vue Single File Components (SFC) <style> blocks
    • Angular: Extracts from @Component decorator styles array
    • All Frameworks: Manual annotation and inline CSS detection

  3. Browser Compatibility Matrix - Shows which browsers support each detected feature with visual indicators:

    • 🟢 Widely Available (Baseline 2023 or earlier)
    • 🟡 Newly Available (Baseline 2024)
    • 🔴 Not Baseline (Limited support)

  4. Developer Experience:

    • Filtering by support level
    • Search functionality
    • Export reports (JSON, CSV, HTML)
    • Console warnings for non-Baseline features
    • Zero configuration for basic usage

  5. Smart Detection:

    • Parses CSS from inline styles, CSS files, and CSS-in-JS
    • Handles template literals, object syntax, and tagged templates
    • Supports scoped styles (Vue scoped, Angular ViewEncapsulation)
    • Combines manual annotations with automatic detection

How we built it

Architecture

The addon is built in TypeScript with a modular architecture:

addon/
├── src/
│   ├── analyzer/           # CSS and component parsers
│   │   ├── css-analyzer.ts       # PostCSS-based CSS parser
│   │   ├── js-analyzer.ts        # Babel-based JS parser (React CSS-in-JS)
│   │   ├── vue-analyzer.ts       # Vue SFC parser
│   │   ├── angular-analyzer.ts   # Angular component parser
│   │   └── extractors/           # Library-specific extractors
│   ├── components/         # React UI components
│   ├── baseline.ts         # Baseline computation logic
│   ├── constants.ts        # Feature definitions
│   └── withGlobals.ts      # Storybook decorator

Technology Stack

  1. Parsing & Analysis:

    • PostCSS - CSS parsing and AST traversal
    • Babel Parser - JavaScript/TypeScript parsing for CSS-in-JS
    • @vue/compiler-sfc - Vue Single File Component parsing
    • web-features - Google's Baseline data package

  2. UI & Integration:

    • React - UI components for the addon panel
    • Storybook API - Addon integration (decorators, panels, toolbar)
    • TypeScript - Type safety throughout

  3. Build & Testing:

    • tsup - Fast TypeScript bundler
    • Vitest - Unit testing (67 tests)
    • ESLint & Prettier - Code quality

Implementation Journey

Phase 1: MVP (v0.1.0)

  • Manual feature annotation
  • Basic Baseline panel
  • CSS file detection
  • ~15 CSS features

Phase 2: React CSS-in-JS (v0.2.0)

  • Babel parser integration
  • styled-components extractor
  • Emotion extractor (object + template syntax)
  • Stitches extractor
  • Expanded to 40+ CSS features
  • Enhanced UI with filtering and export

Phase 3: Vue Support (v0.3.0)

  • Vue SFC parser with @vue/compiler-sfc
  • Scoped and module styles support
  • vue-styled-components extractor
  • Pinceau extractor
  • 11 Vue example stories

Phase 4: Angular Support (v0.4.0)

  • Angular component parser (reused Babel)
  • @Component decorator extraction
  • ViewEncapsulation support
  • 5 Angular example stories

Key Technical Decisions

  1. Reusable Parsers - Used Babel for both React CSS-in-JS and Angular components (no new dependencies!)

  2. Modular Extractors - Each CSS-in-JS library has its own extractor, making it easy to add new libraries

  3. Unified Detection Flow - All sources (CSS, JS, Vue, Angular) feed into the same feature detection engine

  4. Zero Config - Works out of the box with sensible defaults, but highly configurable

Challenges we ran into

1. CSS-in-JS Parsing Complexity

Challenge: CSS-in-JS libraries use different syntaxes:

  • styled-components: Template literals with interpolations
  • Emotion: Both object syntax and template literals
  • Stitches: Object syntax with nested selectors

Solution: Created a modular extractor system where each library has its own parser. Built a objectToCSS utility to convert JavaScript objects to CSS strings, handling camelCase → kebab-case conversion, unit additions, and nested selectors.

2. Vue Template Literal Escaping

Challenge: Vue SFC code contains template literals with {{ }} syntax, which caused parsing errors when stored as strings in TypeScript.

Solution: Initially tried escaping backticks, but this became messy. Eventually simplified by using manual feature annotation for complex cases and focusing on clean, working examples.

3. Babel Traverse ESM/CJS Compatibility

Challenge: The Babel traverse module has different exports for ESM and CJS, causing (0, oS.default) is not a function errors in production builds.

Solution: 

import traverseModule from "@babel/traverse";
const traverse = (traverseModule as any).default || traverseModule;

4. Feature Detection Accuracy

Challenge: Detecting CSS features from AST is tricky. For example, distinguishing between gap (Grid/Flexbox) and grid-gap (Grid-specific).

Solution: Used PostCSS to parse CSS into AST, then matched against feature patterns. Built comprehensive test suites (67 tests) to ensure accuracy.

5. Performance with Large Codebases

Challenge: Parsing large CSS-in-JS files could be slow.

Solution:

  • Lazy parsing (only when addon panel is open)
  • Caching parsed results per story
  • Efficient AST traversal
  • No unnecessary re-parsing

Accomplishments that we're proud of

1. Multi-Framework Support

Successfully implemented automatic detection for 3 major frameworks (React, Vue, Angular) - something most Storybook addons don't do!

2. Code Reuse Efficiency

  • Vue implementation: Estimated 20-29 hours, completed in 3-4 hours (8x faster!)
  • Angular implementation: Estimated 19-27 hours, completed in 2 hours (10x faster!)
  • Achieved through excellent code reuse and modular architecture

3. Comprehensive Testing

  • 67 unit tests covering all parsers and extractors
  • 31 example stories demonstrating real-world usage
  • 100% test pass rate

4. Zero Dependencies for Core Features

Angular support required no new dependencies - reused existing Babel parser. This keeps the bundle size small and reduces maintenance burden.

5. Production-Ready Quality

  • Full TypeScript type safety
  • Comprehensive error handling
  • Graceful fallbacks
  • Clear console warnings
  • Extensive documentation

6. Developer Experience

  • Works out of the box with zero configuration
  • Intuitive UI with filtering and search
  • Export functionality for reports
  • Clear documentation with examples
  • Backward compatible (no breaking changes across versions)

What we learned

Technical Learnings

  1. AST Parsing is Powerful - Understanding Abstract Syntax Trees opened up possibilities for analyzing code in ways we hadn't imagined. The ability to traverse and extract information from code programmatically is incredibly powerful.

  2. Framework-Specific Parsers - Each framework has its own way of handling styles:

    • React: CSS-in-JS with JavaScript objects
    • Vue: Template-based SFCs with <style> blocks
    • Angular: Decorator-based with styles arrays

Understanding these patterns was key to building universal support.

  1. Build Tool Complexity - Managing ESM/CJS compatibility, TypeScript compilation, and bundling for Storybook addons taught us a lot about modern JavaScript build tools.

  2. Testing is Essential - With 67 tests, we caught numerous edge cases early. Tests gave us confidence to refactor and add features quickly.

Process Learnings

  1. Plan, Then Execute - Creating detailed implementation plans (VUE_SUPPORT_PLAN.md, ANGULAR_SUPPORT_PLAN.md) before coding saved enormous time. We knew exactly what to build and could reuse patterns.

  2. Incremental Releases - Shipping v0.1.0 → v0.2.0 → v0.3.0 → v0.4.0 allowed us to:

    • Get feedback early
    • Validate architecture decisions
    • Build confidence in the codebase
    • Maintain backward compatibility

  3. Documentation Matters - Writing comprehensive docs (README, CHANGELOG, planning docs) helped us:

    • Clarify our thinking
    • Onboard future contributors
    • Provide value to users
    • Remember why we made certain decisions

  4. Code Reuse is King - The modular architecture paid off massively. Each new framework took less time than the previous one because we could reuse:

    • CSS analyzer
    • Feature detection engine
    • UI components
    • Testing patterns

Community Learnings

  1. Open Source Standards - Following Storybook's addon conventions, semantic versioning, and catalog requirements taught us how to build software that integrates well with ecosystems.

  2. User-Centric Design - Thinking about the developer experience (DX) from the start led to features like:

    • Zero config defaults
    • Clear error messages
    • Export functionality
    • Comprehensive examples

What's next for Storybook Addon Baseline

Short-term (Next 3 months)

  1. Svelte Support

    • Parse Svelte component <style> blocks
    • Support Svelte CSS-in-JS libraries
    • Estimated: 2-3 hours (following established patterns)

  2. Preprocessor Support

    • SCSS/Sass compilation
    • Less compilation
    • PostCSS plugin support
    • Challenge: Requires build-time integration

  3. Enhanced Feature Detection

    • CSS Custom Properties (CSS Variables)
    • CSS Animations and Transitions
    • CSS Transforms
    • Expand from 40+ to 60+ features

  4. Performance Optimizations

    • Web Worker for parsing (non-blocking)
    • Incremental parsing (only changed files)
    • Better caching strategies

Medium-term (3-6 months)

  1. AI-Powered Suggestions

    • Suggest polyfills for non-Baseline features
    • Recommend alternative CSS approaches
    • Auto-generate fallback styles

  2. CI/CD Integration

    • GitHub Action to check Baseline compliance
    • Fail builds if non-Baseline features detected
    • Generate compatibility reports in PRs

  3. Historical Baseline Tracking

    • Track when features became Baseline
    • Show adoption timeline
    • Predict future Baseline dates

  4. Team Collaboration Features

    • Share compatibility reports
    • Team-wide Baseline targets
    • Component library compatibility dashboard

Long-term (6-12 months)

  1. Visual Regression Testing

    • Integrate with Chromatic
    • Test components across browsers
    • Automated cross-browser screenshots

  2. Polyfill Automation

    • Auto-inject polyfills based on target browsers
    • Smart bundling (only include needed polyfills)
    • Integration with PostCSS/Babel

  3. Baseline Studio

    • Standalone web app (not just Storybook addon)
    • Analyze entire codebases
    • Team dashboards and analytics
    • Browser support planning tools

  4. Framework Expansion

    • Solid.js support
    • Qwik support
    • Lit (Web Components) enhanced support
    • React Native (mobile compatibility)

Community Goals

  1. Grow Adoption

    • Target: 1,000+ weekly downloads
    • Get featured in Storybook blog
    • Present at conferences (React Summit, Vue.js Nation)

  2. Build Community

    • Accept community contributions
    • Create contributor guide
    • Host office hours for questions
    • Build Discord community

  3. Enterprise Features

    • Custom Baseline definitions
    • Private feature databases
    • Advanced reporting and analytics
    • Enterprise support packages

Impact & Vision

Our vision is to make browser compatibility a solved problem in the component development workflow. Developers should never have to:

  • Context switch to caniuse.com
  • Wonder if a CSS feature is safe to use
  • Discover browser issues in production
  • Manually track which features they're using

With Storybook Addon Baseline, compatibility information is:

  • ✅ Automatic - No manual work required
  • ✅ Contextual - Right where you're building components
  • ✅ Actionable - Clear warnings and recommendations
  • ✅ Comprehensive - Covers all major frameworks

We believe this will lead to:

  • Fewer browser compatibility bugs in production
  • Faster development (no context switching)
  • Better user experiences (more informed CSS choices)
  • Wider adoption of modern CSS features (with confidence)

Thank You

Thank you for considering Storybook Addon Baseline! We're excited about the future and would love your feedback, contributions, and support.

Links:

Built with ❤️ by cajpany

Built With

Share this project:

Updates