renderlintv0.2.0

Get started with renderlint

One command sets it up: it installs renderlint, writes a config, gates your build, and tells your coding agent to run it after every UI change. You need Node.js 18.17 or newer.

npx -y @yitec/renderlint init

Set it up through your coding agent

Paste this into Claude Code, Cursor, Codex, Copilot, Gemini CLI, Windsurf, Aider, Zed or Amp:

Set up renderlint in this project: run npx -y @yitec/renderlint init, then follow the “UI quality gate: renderlint” section it adds to AGENTS.md: after every UI change run npx renderlint and fix every reported error until it shows 0 errors.

Or run it yourself

npx -y @yitec/renderlint init   # one-time setup: config, build gate, agent instructions, Claude Code hook
npx renderlint                   # check: exits 1 if any error is found

Or just install it with npm i -D @yitec/renderlint. The command is renderlint either way. To try it once without installing: npx -y @yitec/renderlint http://localhost:3000.

What does init do?

  1. Adds renderlint as a dev dependency (creating a package.json for plain HTML sites).
  2. Writes renderlint.config.json, pointed at your dev command or static folder.
  3. Adds a lint:ui script and appends the check to build, so builds fail on UI defects (--no-build to skip).
  4. Installs the agent skills renderlint-setup, renderlint-fix and renderlint-e2e in .claude/skills/ (--no-skills to skip).
  5. Adds the agent workflow to AGENTS.md and creates or updates CLAUDE.md.
  6. Installs the Claude Code Stop hook in .claude/settings.json (--no-hook to skip).
  7. Adds .renderlint/ to .gitignore and makes sure a headless Chromium is available.

init is idempotent: run it again to update the skills it installed.

How do you point it at your app?

Without config, renderlint works out what to check: a running dev server, then your dev script (started and stopped for you), then a build folder (dist, build, out…), then index.html. You can also give it a target:

npx renderlint http://localhost:3000            # any running app
npx renderlint dist                             # a static build (served for you)
npx renderlint index.html about.html            # plain files
npx renderlint --serve "npm run preview" --url http://localhost:4173
npx renderlint --pages /,/pricing,/dashboard --viewports 360,768,1440
npx renderlint --sweep 1024,1366                # only these extra widths (--no-sweep to skip)
npx renderlint --ux                             # also click through every page
npx renderlint explain contrast                 # what a rule means and how to fix it

Every run writes .renderlint/report.json, .renderlint/report.md and annotated screenshots to .renderlint/screens/. Output formats: plain text (default), --json, --format md and --format github for pull-request annotations.

What does the output look like?

✖ contrast (3)  Text does not have enough contrast with what is actually behind it …
  error Low text contrast: 2.66:1, needs 4.5:1 — #ffffff on a non-uniform background (≈#459bf4).
        at #top > section.hero > div.hero-copy > a.pill > b  "New"
        in Hero — src/components/Hero.tsx:42
        page / · all viewports · see .renderlint/screens/index@375.png #3
       fix use text #2e2e2e (currently #ffffff on #459bf4)

✖ 4 error(s), 2 warning(s) · screenshots in .renderlint/screens

How do you fail the build on UI defects?

init appends the check to your build script. By hand:

Frameworkbuild script
Vite (React, Vue, Svelte, Solid, Preact, Lit), Qwikvite build && renderlint dist
Next.jsnext build && renderlint --serve "npx next start -p 4319" --url http://localhost:4319
Next.js static exportnext build && renderlint out
SvelteKitvite build && renderlint --serve "npx vite preview --port 4319 --strictPort" --url http://localhost:4319
Astroastro build && renderlint dist
Nuxtnuxt generate && renderlint .output/public
Angularng build && renderlint dist/<project>/browser
Eleventy, Hugo, Jekyllrenderlint _site / renderlint public
WordPress and ElementorNo build step: renderlint finds the local site (wp-env, LocalWP, DDEV, Lando, Docker Compose)
Rails, Django, Laravel, anything with a serverrenderlint --serve "bin/rails s -p 4319" --url http://localhost:4319

Framework guides: all frameworks, integrations.

How do you make Claude Code check its own UI?

init registers a Stop hook in .claude/settings.json:

{ "hooks": { "Stop": [{ "hooks": [{ "type": "command", "command": "npx renderlint hook", "timeout": 600 }] }] } }

When Claude is about to finish a turn in which UI files changed, the hook runs renderlint on the routes the edit can affect. If errors remain, the report goes back to Claude (exit code 2) and it keeps working. It never blocks more than 4 times in a row, and does nothing when no UI file changed. Other agents get the same workflow through AGENTS.md and three skills.

How do you run it in GitHub Actions?

name: UI lint
on: [pull_request]
jobs:
  renderlint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: 20, cache: npm }
      - run: npm ci
      - run: npx playwright install --with-deps chromium
      - run: npm run build
      - run: npx renderlint dist --format github   # inline PR annotations; exits 1 on errors
      - uses: actions/upload-artifact@v4
        if: always()
        with: { name: renderlint, path: .renderlint }

How do you see findings while you code?

// vite.config.ts
import renderlint from '@yitec/renderlint/vite';

export default defineConfig({
  plugins: [react(), renderlint()],
});

In vite dev, an overlay lists findings for the current viewport and links each to its component file and line. vite build fails on errors. In any other app: import('@yitec/renderlint/client').then((m) => m.start()).

How do you configure it?

renderlint.config.json (or .js/.mjs, or a "renderlint" key in package.json):

{
  "serve": "npm run dev",
  "pages": ["/", "/pricing"],
  "viewports": [375, 768, 1280],
  "colorSchemes": "auto",
  "rules": { "line-length": "off", "tap-target": "error" },
  "ignore": [{ "rule": "contrast", "selector": ".legal-footnote" }],
  "states": [{ "name": "account menu", "click": "[aria-label=Account]", "waitFor": "[role=menu]" }],
  "mock": { "**/api/notifications*": [] }
}

All options: configuration. Pages behind a login: authentication and roles and coverage. Playwright: withRenderlint. Storybook: renderlint storybook.

What are the limits?

  • Labels inside <canvas> charts (Chart.js, ECharts in canvas mode) are pixels and can’t be inspected. SVG charts are checked.
  • Pages are checked as they load, with each menu opened. Other states behind clicks are linted when you list them in states or reach them in a Playwright test; --ux judges the clicks themselves.
  • Server mocks are Node only. Pages a Django, Rails, Laravel or Go server renders need a running backend with test accounts.
  • Contrast follows WCAG 2 AA math, not APCA.
  • A single page takes about 4–10 seconds at three viewports with the sweep and stress passes. Use --sweep 1024 or --no-sweep for a faster inner loop.