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 initSet 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 runnpx renderlintand 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?
- Adds renderlint as a dev dependency (creating a
package.jsonfor plain HTML sites). - Writes
renderlint.config.json, pointed at your dev command or static folder. - Adds a
lint:uiscript and appends the check tobuild, so builds fail on UI defects (--no-buildto skip). - Installs the agent skills
renderlint-setup,renderlint-fixandrenderlint-e2ein.claude/skills/(--no-skillsto skip). - Adds the agent workflow to
AGENTS.mdand creates or updatesCLAUDE.md. - Installs the Claude Code Stop hook in
.claude/settings.json(--no-hookto skip). - Adds
.renderlint/to.gitignoreand 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:
| Framework | build script |
|---|---|
| Vite (React, Vue, Svelte, Solid, Preact, Lit), Qwik | vite build && renderlint dist |
| Next.js | next build && renderlint --serve "npx next start -p 4319" --url http://localhost:4319 |
| Next.js static export | next build && renderlint out |
| SvelteKit | vite build && renderlint --serve "npx vite preview --port 4319 --strictPort" --url http://localhost:4319 |
| Astro | astro build && renderlint dist |
| Nuxt | nuxt generate && renderlint .output/public |
| Angular | ng build && renderlint dist/<project>/browser |
| Eleventy, Hugo, Jekyll | renderlint _site / renderlint public |
| WordPress and Elementor | No build step: renderlint finds the local site (wp-env, LocalWP, DDEV, Lando, Docker Compose) |
| Rails, Django, Laravel, anything with a server | renderlint --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
statesor reach them in a Playwright test;--uxjudges 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 1024or--no-sweepfor a faster inner loop.