Baseline Guardian

The quality gate for modern web development. Baseline Guardian automatically enforces browser compatibility standards on every pull request, so your team can innovate fearlessly.

Comment

1. Inspiration

The inspiration for Baseline Guardian came from a common friction point in modern web development: IDE linters are great for suggesting best practices, but they are not enforceable. We've all seen a pull request where a cutting-edge, poorly-supported CSS feature slips through code review during a tight deadline, only to cause regressions on a key browser. We wanted to solve this problem at the team level, moving compatibility checks from a friendly, ignorable nudge in the editor to a mandatory, automated quality gate in the CI/CD pipeline. The goal was to create a tool that enforces standards impartially, ensuring consistency and stability for the entire team.

2. What it does

Baseline Guardian is a GitHub Action that acts as an automated policy engine for web compatibility. On every pull request, it performs a simple but powerful workflow:

  1. It automatically scans the CSS files changed in the PR.
  2. It cross-references every CSS property against the official web-features dataset to determine its Baseline status (widely available, newly available, or limited availability).
  3. It validates these statuses against a simple, team-defined policy in a .baseline-guardian.yml file.
  4. If it finds any violations, it fails the build and posts a clear, actionable report directly as a comment on the pull request. This report details the problematic feature, its status, the policy it violates, and a direct link to the MDN documentation for easy learning and fixing.

3. How we built it

Baseline Guardian is built as a self-contained GitHub Action using Node.js and TypeScript to ensure strong typing and reliability.

  • CI/CD Integration: We used the official GitHub Actions Toolkit (@actions/core, @actions/github) to interact seamlessly with the workflow environment, read the GITHUB_TOKEN, and post status checks and comments to the pull request API.
  • CSS Parsing: We used the robust PostCSS library to parse CSS files. Its speed and ability to handle complex and modern syntax made it the perfect choice for accurately identifying all the properties in a given file.
  • Baseline Data: The core of the project relies on the authoritative web-features npm package. This allowed us to query the official Baseline status for any given CSS property, ensuring our reports are based on the latest source of truth.
  • Bundling: To create a dependency-free and performant action, we used @vercel/ncc to compile our TypeScript and bundle all node_modules into a single, distributable dist/index.js file.

4. Challenges we ran into

  • Finding the Source of Truth: Our initial assumption was that Baseline data lived in the @mdn/browser-compat-data package. After debugging incorrect results, we discovered through the documentation that the authoritative source had evolved to the web-features package. Overcoming this required research and a quick, successful pivot, which was a critical learning experience.
  • The GitHub Action Learning Curve: Building a Node.js action for the first time presented several technical hurdles. The most significant was understanding the build process—realizing that all dependencies must be bundled using a tool like ncc, as the runner environment does not perform an npm install.
  • Designing Actionable Feedback: Simply failing the build isn't enough. The biggest design challenge was crafting a PR comment that was genuinely helpful, not just noisy. We focused on making the report clear, concise, and educational by including the "what, why, where" and the crucial MDN link.

5. Accomplishments that we're proud of

  • The Core Innovation: We are incredibly proud of shifting the problem of compatibility from the individual developer's editor to the team's CI/CD pipeline. Creating a "policy-as-code" engine that acts as a true quality gate is the single biggest accomplishment of this project.
  • The Developer Experience of the Report: The final PR comment is something we're very proud of. It's not just a linter error; it's a rich, formatted, and educational tool that helps developers fix their code and learn about the web platform at the same time.
  • A Complete, Working Action: We successfully built, debugged, and tested a complete, end-to-end GitHub Action. From the initial PR trigger to the final, accurate comment, the entire pipeline works flawlessly, which is a major accomplishment for a hackathon.

6. What we learned

  • The Power of the CI/CD Pipeline: We learned that the CI/CD workflow is the most powerful point of leverage for enforcing team-wide quality and standards. Automating checks here ensures consistency in a way that local tooling never can.
  • The Importance of Bundling: We gained a deep, practical understanding of how Node.js-based GitHub Actions are executed and the critical role that bundlers like ncc play in creating portable and dependency-free actions.
  • Data Sources Evolve: Our experience finding the web-features package was a powerful lesson in the ever-evolving nature of web standards. It highlighted the importance of reading documentation carefully and staying current with the ecosystem.

7. What's next for Baseline Guardian

This MVP is a powerful foundation, and we're excited about where it could go next.

  • Expand Support: The immediate next step is to add scanners for JavaScript APIs and HTML elements, providing full-stack compatibility checking.
  • Broader CI/CD Integration: We plan to refactor the core logic into a standalone CLI tool that can be packaged for other platforms like GitLab CI, CircleCI, and Bitbucket Pipelines.
  • Smarter Suggestions: A future version could enhance the PR comment by suggesting common polyfills or CSS fallbacks for the non-compliant features it finds, turning the report from just a warning into a direct solution.
  • IDE Sync: We envision an IDE extension that reads the project's central .baseline-guardian.yml file and applies the exact same rules in the editor, creating a perfect sync between local linting and CI/CD enforcement.

Built With

Share this project:

Updates