Peer Dependencies

Real A11y is a lean dev-time audit suite. It relies on a small set of peers you probably already have — React, Storybook, Playwright — plus a couple of popular companion libraries (Testing Library) that don't formally peer on anything but where version mismatches still bite. This page is the matrix.

Compatibility matrix

Real A11y package	Node	React	Storybook	Playwright
@real-a11y-dev/inspector	≥ 20	—	—	—
@real-a11y-dev/react	≥ 20	18 or 19	—	—
@real-a11y-dev/testing	≥ 20	—	—	—
@real-a11y-dev/testing/playwright	≥ 20	—	—	≥ 1.49
@real-a11y-dev/storybook-addon	≥ 20	18 or 19	≥ 8.0	—
@real-a11y-dev/cli	≥ 22.12	—	—	≥ 1.49 (optional)
@real-a11y-dev/mcp	≥ 20	—	—	≥ 1.49

@real-a11y-dev/inspector has no runtime peers — it uses standard DOM APIs, and the extraction engine it bundles has none either. @real-a11y-dev/testing takes any Element root, so your test runner and component renderer are entirely your choice.

Playwright is an optional peer of @real-a11y-dev/cli — install it (npm i -D playwright) only when you audit real URLs: the audit, inspect, snapshot, tree, and login commands. Static and DOM-root usage needs nothing extra. Of @real-a11y-dev/mcp it is a required peer, since every browser tool needs it: npm installs it with the server, npx -y @real-a11y-dev/mcp included, and so does pnpm with its default auto-install-peers. With Yarn, or pnpm with that setting off, you add it yourself. Note both packages peer on playwright (not @playwright/test) and pin it to >=1.49 <2. npm moves a Playwright your own range allows into that range, and stops with ERESOLVE on one pinned outside it, 2.x included, rather than warning. @real-a11y-dev/testing pins the same >=1.49 <2 range — it used to accept any version, inheriting nothing but a * while the browser driver was a real dependency of it, and states the range directly now that the driver is bundled.

---

Companion libraries

Real A11y packages don't declare these as peers, but most users install at least one of them alongside @real-a11y-dev/testing. The versions below are what works cleanly with React 19 — pinning older versions surfaces peer errors that look Real A11y-related but aren't.

@testing-library/react

Not a peer of any Real A11y package — you can use @real-a11y-dev/testing without it (just pass any Element as the audit root). But if you use it: version 16.0.0 declares react: ^18 as its own peer. Installing it alongside React 19 gives:

npm error ERESOLVE could not resolve
npm error While resolving: your-app
npm error Found: react@19.2.4
npm error Could not resolve dependency:
npm error peer react@"^18.0.0" from @testing-library/react@16.0.0

Fix: install @testing-library/react@^16.1.0 (or later). Version 16.1 relaxed the peer to react: ^18 || ^19.

npm install -D @testing-library/react@^16.1.0

@playwright/test in Next.js 15 projects

Next 15 declares @playwright/test@^1.51.1 as an optional peer. @real-a11y-dev/testing/playwright itself is happy with ^1.49, but npm resolves against Next's optional peer and errors out:

npm error peerOptional @playwright/test@"^1.51.1" from next@15.5.14

Fix: install @playwright/test@^1.51.1 to satisfy both.

npm install -D @playwright/test@^1.51.1

---

@real-a11y-dev/storybook-addon — Storybook version

The addon's manager imports storybook/manager-api and its preview imports storybook/preview-api. Those subpaths arrived in Storybook 9, when the standalone @storybook/manager-api, @storybook/preview-api and @storybook/theming packages were folded into storybook itself — they stopped publishing at 8.6, and storybook@8 exposes no equivalent subpath. So the supported range is Storybook 9.x, 10.x or 11.x; 8 and earlier will not work, and there is no build that can serve both sides of that split.

The 11 half of that range is written ^11.0.0-0, not ^11.0.0. Storybook 11 is still prerelease — 11.0.0-alpha.0 is the only 11.x published — and npm ranges exclude prereleases unless the range itself names one, so ^11.0.0 would have matched nothing you can currently install. Support for 11 is verified against that alpha — tsc checks the addon against Storybook 11's own declarations — and re-checked by an advisory CI job. The unit tests mock the Storybook API, so they are not part of that evidence. Treat 11 support as provisional until 11 ships stable.

Note that a single storybook dependency is all you need now: if your project still carries @storybook/manager-api or @storybook/preview-api from a Storybook 8 setup, remove them.

@real-a11y-dev/react — React version

React 18 and React 19 are both supported — the peer range is ^18.0.0 || ^19.0.0. A future React 20 therefore fails the peer check at install time (an ERESOLVE error on npm, like the @testing-library/react case above; a warning on pnpm and Yarn) instead of resolving silently against a major the package has never been built against. On React 19 specifically, the inspector's floating-panel mode is SSR-safe (it gates the portal behind a client-mount effect), but you still need "use client" at the consumer boundary — see the Next.js recipe for the full pattern.

@real-a11y-dev/testing/playwright — browser install

After adding the package, install the Chromium engine:

npx playwright install chromium
# Linux CI: add --with-deps to install required system packages
npx playwright install chromium --with-deps

The adapter only uses Chromium — Firefox and WebKit aren't needed for the audit bundle.

---

Single React instance

Several of the edge cases above (especially in Storybook and SSR apps) boil down to having two copies of React resolved on the page. The manager mixes React internals from one copy with jsx-runtime calls against another, and hooks die.

Verify a single resolution:

npm ls react react-dom

One version per package, one path. If you see more than one, look at transitive deps that pin React to a specific version (often older Storybook addons or legacy test helpers) and either upgrade them or override the version via overrides / resolutions / pnpm.overrides in package.json.

{
  "overrides": {
    "react": "19.2.4",
    "react-dom": "19.2.4"
  }
}

---

Clean install recipe

When peer conflicts get tangled, a clean install clears the lockfile state:

rm -rf node_modules package-lock.json
npm install

For pnpm:

rm -rf node_modules pnpm-lock.yaml
pnpm install

Re-run npm ls react / pnpm why react afterwards to confirm a single resolution.