Skip to content
schalkneethlingPublic

About

Embeddable browser compatibility tables backed by live browser-compat-data. Web component + self-hostable API

Topics

Resources

Contributing

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

170 Commits

Folders and files

Repository files navigation

bcd-embed

Embeddable browser compatibility tables backed by live @mdn/browser-compat-data.

The data pipeline is built and lives on main: a contract, a normalizer, a static artifact generator, a read-only HTTP handler, a Cloudflare Worker adapter, a private publisher, and the freshness workflows that keep it current with new BCD releases. The API Worker has been deployed to Cloudflare since 15 November 2026, answers on https://api.browser-compat.dev, and serves BCD 8.1.9, behind a Cloudflare rate limiting rule and with Sentry alerting. One launch requirement remains open, a test under sustained load, which the deployment page lists. The web component (packages/element) has not been started. The design and sequencing decisions live in docs/planning.

Repository layout

The monorepo keeps the contract, normalization pipeline, static artifact generator, edge adapter, and web component versioned together. The implemented workspaces are:

  • packages/schema — @bcd-embed/schema, the canonical Zod schemas, inferred TypeScript types, and derived JSON Schema.
  • packages/core — @bcd-embed/core, the pure BCD subtree normalizer.
  • packages/generator — @bcd-embed/generator, which validates the pinned BCD data, normalizes every addressable feature with core, and writes the static JSON artifacts (plus gzip and Brotli variants) to a local directory. It also ships a tool that compares two generated trees.
  • packages/server — @bcd-embed/server, a portable, read-only Fetch handler that answers API requests from generated artifacts through a small storage interface.
  • packages/publisher — @bcd-embed/publisher, a private Node tool that checks a candidate artifact tree against a baseline and, only when an operator explicitly opts in, uploads it to an R2 bucket and switches the current snapshot.
  • packages/element — @bcd-embed/element, the future <bcd-compat-table> web component. The component does not exist yet; the workspace holds the screen reader tests for the Phase 1 static markup.
  • apps/worker — @bcd-embed/worker, the Cloudflare Worker that runs the server handler against an R2 bucket binding and adds edge caching and error reporting. It is deployed manually with pnpm --filter @bcd-embed/worker run deploy, and the endpoint verifier checks it after each deploy.
  • apps/docs — @bcd-embed/docs, the playground that validates a response against the contract.
  • apps/website — @bcd-embed/website, the documentation site, built with Starlight. Its pages are the Markdown files in apps/website/src/content/docs. It is configured for Cloudflare hosting and has not been deployed.

Each package and app has its own README with the details of its behavior.

Automation

Six GitHub Actions workflows live in .github/workflows/, and the scripts they call live in scripts/:

  • ci.yml runs pnpm check, a generation check at full BCD volume, and the core mutation gate on every pull request and push to main. A pull request that changes only .github/freshness-approvals.json runs just the format check and approval validation for that file.
  • freshness.yml handles Dependabot pull requests that update @mdn/browser-compat-data. It generates artifacts from both the base and the candidate, and fails the pull request when the output diff crosses the reviewed limits, unless a maintainer approved that exact change in .github/freshness-approvals.json. To approve one, follow Approving a blocked BCD update. Auto-merge is off unless an operator turns it on with a repository variable.
  • freshness-backstop.yml runs on pushes to main, weekly, and on manual dispatch. It validates main and preserves a candidate artifact tree. Publishing to R2 only happens on a manual dispatch with publish set, behind a protected environment, and needs an exact-hash approval whenever the diff gate blocks the change, so no automatic publication is configured. How publication works explains what is uploaded and how to run it.
  • dependabot-worker-types.yml regenerates apps/worker/worker-configuration.d.ts on Dependabot pull requests and commits it to the pull request's branch, because a Wrangler update can change the generated types and fail CI's wrangler types --check. The commit starts a CI run that someone with write access must approve once. The manual steps for when it fails are in apps/worker/README.md.
  • legacy-cleanup.yml deletes one folder, v1/<snapshot>/, that the publisher wrote before the content-addressed layout. It runs only on manual dispatch from main, behind the protected environment, and counts without deleting unless execute is checked. How publication works explains it.
  • screen-readers.yml runs the web component's screen reader tests with VoiceOver on macOS and Orca on Linux, on pull requests that change packages/element or the Phase 1 markup. Its screen-readers job is a required check: it reports on every pull request, passes when the tests pass or were not needed, and fails when they fail. Each run records what the screen reader said. The details are in packages/element/README.md.

The design behind the freshness workflows is in docs/planning/06-phase5-freshness.md.

Planning documents

The design documents in docs/planning are:

The validation records for the finished phases are:

Contract package

@bcd-embed/schema exports the canonical Zod schemas and inferred TypeScript types from its package root. Standalone JSON Schema Draft 2020-12 documents are published at these subpaths:

  • @bcd-embed/schema/json-schema/feature-response
  • @bcd-embed/schema/json-schema/browsers-response
  • @bcd-embed/schema/json-schema/index-response
  • @bcd-embed/schema/json-schema/meta-response
  • @bcd-embed/schema/json-schema/api-error-response

Regenerate the committed documents with pnpm --filter @bcd-embed/schema generate:json-schema. Package tests fail when the committed documents differ from the canonical Zod definitions. JSON Schema validates the portable structural contract; relational invariants that JSON Schema cannot express, such as summary projection and response-wide target coverage, are documented in the schema $comment and enforced by Zod.

The @bcd-embed/schema/fixtures/v1 subpath publishes the adversarial normalized golden response, its named-case catalog, and exact source fragments extracted from @mdn/browser-compat-data@8.1.3. These fragments are a frozen snapshot: automatic BCD updates do not change them, and tests check the snapshot against its own recorded source rather than the installed BCD. See the schema README to regenerate them deliberately.

Core package

@bcd-embed/core exports normalizeFeatureSubtree, the framework-free, side-effect-free transform from one addressable BCD subtree plus BCD browser metadata to normalized features and the exact referenced support-target metadata. It performs no I/O and does not add timestamps, source identity, or a response envelope; those remain generator responsibilities. Normalization failures throw BcdNormalizationError with the failing BCD key.

Development

Requirements:

  • Node.js 24 or newer. CI runs 26.13.0, so that is the tested version.
  • pnpm 11.24.0, managed through Corepack

Install dependencies and run the complete repository check:

corepack enable
pnpm install
pnpm check

Useful commands:

pnpm dev              # Run the contract playground
pnpm dev:website      # Run the documentation site
pnpm fixtures:report  # Summarize the v1 golden fixture corpus
pnpm format           # Format the repository
pnpm lint             # Run JavaScript/TypeScript and CSS linting
pnpm typecheck        # Type-check every implemented workspace
pnpm test             # Run the test suite
pnpm build            # Build every implemented workspace

Validate a normalized response from a file with both the canonical Zod schema and the corresponding published JSON Schema:

pnpm schema:validate --kind feature-response response.json

The accepted kinds are feature-response, browsers-response, index-response, meta-response, and api-error-response. Use - or omit the file to read JSON from standard input. The fixture report also supports --json for machine-readable output.

Tooling

Calavera owns the shared formatting, linting, and TypeScript policy. Its repeatable recipe is stored in calavera.config.json. Preview a tooling update before applying it:

pnpm dlx create-project-calavera apply --dry-run
pnpm dlx create-project-calavera apply

Package and application builds use Vite; tests use Vitest. The documentation site builds with Astro.

License

MIT

About

Embeddable browser compatibility tables backed by live browser-compat-data. Web component + self-hostable API

Topics

Resources

Contributing

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages