@glitchreplay/a11y

Accessibility scanning integration for any Sentry-compatible SDK. Runs axe-core in the browser, reports WCAG violations to GlitchReplay alongside errors, and surfaces them under the dashboard's Accessibility tab.

Install

pnpm add @glitchreplay/a11y axe-core

axe-core is a peer dependency. The SDK does not bundle it.

Use

import * as Sentry from "@sentry/nextjs";
import { axeIntegration } from "@glitchreplay/a11y";

Sentry.init({
  dsn: "https://<your-key>@glitchreplay.com/0",
  // GlitchReplay records every session by default; sessions not linked to
  // an error are pruned at 3 days regardless of tier (see PRICING.md).
  replaysSessionSampleRate: 1.0,
  replaysOnErrorSampleRate: 1.0,
  integrations: [
    Sentry.replayIntegration({
      maskAllText: true,
      maskAllInputs: true,
      blockAllMedia: true,
    }),
    axeIntegration({
      runOn: ["development", "staging", "production"],
      productionSampleRate: 0.05,        // 5% of prod page loads
      wcagLevel: "AA",
      minImpact: "moderate",
    }),
  ],
});

Options

| Option | Default | Notes | |---|---|---| | runOn | ["development","staging"] | Reads process.env.NODE_ENV and a globalThis.__GR_ENV__ runtime override. Add "production" to enable RUM-style sampling (gated by productionSampleRate). | | productionSampleRate | 0 | Probability (0..1) of scanning each page load when running in production. The dice roll happens once per page load; if rolled out, the integration stays dormant. Has no effect outside production. | | interval | 30000 | Milliseconds between scans in dev/staging. Ignored in production sampling mode (one-shot per page load via requestIdleCallback). | | wcagLevel | "AA" | Highest level to flag ("A", "AA", "AAA"). Lower levels are included. | | rules | — | Per-rule axe.run overrides; e.g. { "color-contrast": { enabled: true } }. | | context | document | Element or selector to scan. Pass a sub-tree to limit cost. | | minImpact | "minor" | Skip violations below this axe-core impact level. | | beforeCapture | — | Hook called per-violation. Return false to drop. |

How it appears in GlitchReplay

Each violation is captured as an event tagged glitchreplay.event_type=a11y_violation. The consumer worker reads that tag, populates ada_category, ada_wcag_level, and ada_rule_id on the issue, and the issue lands under the Accessibility tab. Same fingerprint dedup, same resolve / ignore / assign workflow as exceptions.

Production scanning

In production with productionSampleRate > 0, the integration:

1. Rolls the dice once when the page loads.
2. If rolled in, schedules one scan via requestIdleCallback (or setTimeout(1500) on browsers that don't support it) after the page reaches readyState === "complete".
3. Reports any violations through the SDK's normal capture path, then stays dormant for the rest of the page load.

axe-core's full ruleset can take 100ms+ on a complex page, which is why production runs are one-shot rather than the dev/staging interval loop. Same fingerprint dedup means even at low rates (1–5%) you accumulate full rule coverage across visitors within hours on busy sites. Tune context to a sub-tree if you want to scope the work further.