Local development

The repository uses pnpm workspaces. Use Node 24.22.1 and pnpm 12.16.1. Run these commands from the repository root:

pnpm install --frozen-lockfile
pnpm run dev

The website normally starts at http://localhost:4321; use the address Astro prints if that port is occupied. Astro renders the custom landing page; Starlight serves these docs under /docs/.

Build the extension

pnpm run build:extension

In chrome://extensions or edge://extensions, enable Developer mode, choose Load unpacked, and select packages/extension/dist/extension. Reopen DevTools if it was already open, then choose Anatomy.

pnpm run dev:extension

This builds the extension and serves an independent React fixture at http://localhost:4174. It does not watch extension files: rebuild and reload the extension after changing its source.

Build for Firefox

pnpm run build:firefox

In desktop Firefox 140 or later, open about:debugging#/runtime/this-firefox, choose Load Temporary Add-on…, and select packages/extension/dist/firefox/manifest.json. Reopen Developer Tools, then choose Anatomy.

Firefox removes this temporary add-on when it restarts. Permanent installation requires Mozilla signing; local packaging does not sign or publish it.

pnpm run dev:firefox launches Firefox in a separate profile and reloads the extension when the built files change. Rebuild after source edits. Chrome and Firefox use the same capture engine and inspector; Firefox’s manifest uses a background event page instead of a service worker.

Check the workspace

pnpm run format
pnpm run check
pnpm run build
pnpm test
pnpm run test:website

Oxfmt formats both apps, including Astro, CSS, and Markdown. Oxlint checks JavaScript and TypeScript, including the JavaScript portions of Astro files. astro check covers Astro templates and types.

The extension tests load the real extension in Chromium. Install a browser with pnpm --filter @react-anatomy/extension exec playwright install chromium. On Linux, install the browser dependencies with pnpm --filter @react-anatomy/extension exec playwright install --with-deps chromium as needed. Tests use full Chromium in headless mode and do not require a display server. CHROME_PATH can select an existing Chromium binary; CHROME_SYSROOT can supply a custom library root.

For Firefox, install desktop Firefox and run pnpm run test:firefox. This runs Mozilla’s extension linter and a browser suite against the real Anatomy DevTools panel and toolbar action. Selenium Manager locates Firefox and geckodriver, or use FIREFOX_PATH and GECKODRIVER_PATH to select them explicitly. Use geckodriver 0.36 or later. FIREFOX_SYSROOT optionally supplies Linux shared libraries.

Compatibility validation

The compatibility workloads have their own lockfile and dependencies. Install them once, then run the browser matrix:

pnpm run setup:compatibility
pnpm run test:compatibility

This builds and checks six pinned React versions, Excalidraw, and Next.js App Router in the real Chrome/Chromium and Firefox DevTools panels. Use the browser environment variables above to select versions; run against the minimum and current stable browsers for a release. It does not download browser binaries itself beyond Selenium Manager’s normal browser/driver discovery.

pnpm run test:public-apps separately checks react.dev and shadcn/ui over the network. Results and screenshots are written to packages/extension/artifacts/compatibility/results/. Public deployments supplement the pinned workloads; their changes or availability can fail the public-site check without changing the repeatable local matrix.

The Compatibility page summarizes browser and React requirements. Detailed test results and release checks live in the repository’s docs/validation/ notes.

Package a local build

pnpm run package:extension
pnpm run package:firefox

These commands write separate versioned ZIPs under packages/extension/artifacts/. Extract the Chrome archive before using Load unpacked, or the Firefox archive before selecting its manifest.json under Load Temporary Add-on…. Packaging does not publish anything.

Landing-page example

The website bundles the Orbit sample app and the real Anatomy inspector into two isolated frames. The sample is interactive; the inspector reads its actual React tree and props. Its transport is restricted to that sample, so it does not inspect other pages or require extension permissions.

The example bundles are generated before dev and build. If you change the demo or extension source while Astro is already running, rebuild them and reload:

pnpm --filter @react-anatomy/website exec node scripts/build-demo.ts

pnpm run test:website builds the site and checks the example’s desktop and mobile interactions, reduced motion, screenshots, and documentation search in Chromium.

Shared identity

The approved Exploded Stack artwork lives in packages/brand. The extension build copies its size-specific icons; the website imports the SVGs. Edit the shared package to update the source artwork in one place.

The inspector UI and rendering modules use strict TypeScript. Run pnpm run type-check to check the extension and website. Oxlint, Oxfmt, type-checking, website checks, and browser suites run as separate CI matrix jobs.