Skip to content
Eqo

Getting Started

This guide walks you through installing Eqo, creating your configuration, and running your first RGAA v4.1.2 audit. The whole process takes about 5 minutes.

Prerequisites

Section titled “Prerequisites”

Before you begin, make sure you have:

  • Node.js 22 or higher — Eqo requires Node LTS. Check with node --version.
  • A Next.js project — Eqo analyzes your source files and connects to a running app for runtime analysis.
  • Your app accessible at a URL — Eqo does not start your dev server for you.

  1. Install Eqo

    Add Eqo as a development dependency in your Next.js project root:

    Terminal window
    pnpm add -D @kodalabs-io/eqo

  2. Install Playwright for runtime analysis

    Runtime analysis (browser-based audit) requires Playwright and axe-core as peer dependencies:

    Terminal window
    pnpm add -D playwright @axe-core/playwright axe-core
    pnpm exec playwright install chromium

    Skip this step entirely if you are starting with --static-only. You can add Playwright later when you are ready for runtime analysis.

  3. Initialize your configuration

    Run eqo init in your project root. Eqo reads your package.json to pre-populate the project name and generates a rgaa.config.ts with sensible defaults:

    Terminal window
    pnpm eqo init

    This creates rgaa.config.ts in your project root:

    rgaa.config.ts
    import { defineConfig } from "@kodalabs-io/eqo";
    

    export default defineConfig({
      baseUrl: "http://localhost:3000",
      projectName: "my-app",
      locale: "en-US",
    

      pages: [
        { path: "/", name: "Home" },
      ],
    

      output: [
        { format: "json",     path: "./public/rgaa-report.json" },
        { format: "html",     path: "./reports/rgaa.html" },
        { format: "sarif",    path: "./reports/rgaa.sarif" },
        { format: "markdown", path: "./reports/rgaa.md" },
      ],
    

      thresholds: {
        complianceRate: 0,
        failOn: "threshold",
      },
    });

  4. Configure your pages and outputs

    Open rgaa.config.ts and add the pages you want to audit. For a French organization, a representative sample should include:

    pages: [
      { path: "/",                  name: "Home" },
      { path: "/about",             name: "About" },
      { path: "/contact",           name: "Contact" },
      { path: "/mentions-legales",  name: "Legal Notices" },
      { path: "/accessibilite",     name: "Accessibility Declaration" },
    ],

    If your reports should be in French, set the locale:

    locale: "fr-FR",

    See the Configuration reference for all available options and their defaults.

  5. Start your Next.js application

    Eqo’s runtime phase connects to a live URL. Start your dev server in a separate terminal — and keep it running during the audit:

    Terminal window
    # In a separate terminal
    npm run dev

    Make sure your app is accessible at the URL you set in baseUrl (default: http://localhost:3000). Eqo does not wait for the server to start; if it is unreachable, the runtime phase will report an error for each page.

  6. Run your first audit

    Terminal window
    npx eqo analyze

    Runs both phases: static AST analysis on your source files, then Playwright runtime analysis on each configured page. Requires your app to be running.

Reading your first report

Section titled “Reading your first report”

After the audit, Eqo prints a summary to the terminal:

  eqo — RGAA v4.1.2 Accessibility Analyzer
  2026-03-01T10:00:00.000Z


  ✔ Static analysis complete
  ✔ Runtime analysis complete
  ✔ Analysis complete


  ┌─────────────────────────────────────────┐
  │  Compliance rate:     72%               │
  │  Applicable:          43 criteria       │
  │  Validated:           31 criteria       │
  │  Invalidated:          8 criteria       │
  │  Needs review:         4 criteria       │
  │  Total issues:        23               │
  └─────────────────────────────────────────┘


  ℹ Report written to public/rgaa-report.json
  ℹ Report written to reports/rgaa.html
  ℹ Report written to reports/rgaa.sarif
  ℹ Report written to reports/rgaa.md

Open reports/rgaa.html in your browser for the interactive visual report — filterable by theme, severity, and page.

Understanding the compliance rate

Section titled “Understanding the compliance rate”
complianceRate = validated criteria ÷ applicable criteria
  • Applicable: criteria that apply to at least one of your audited pages
  • Validated: applicable criteria where all automated checks passed on all pages
  • Needs review: criteria excluded from the rate (require manual checking)
  • Not applicable: criteria that don’t apply to any page, or are exempted in the config

Add to your package.json scripts

Section titled “Add to your package.json scripts”

For convenience, add the audit commands to your project’s scripts:

{
  "scripts": {
    "a11y": "eqo analyze",
    "a11y:static": "eqo analyze --static-only",
    "a11y:ci": "eqo analyze --threshold 80"
  }
}

Next steps

Section titled “Next steps”