frameshot

# frameshot [](https://www.npmjs.com/package/frameshot-mcp) [](https://www.npmjs.com/package/frameshot-mcp) [](https://github.com/kamegoro/frameshot) [](https://opensource.org/licenses/MIT) **Give your AI agent eyes.** Render components with real Vite imports, Tailwind, and CSS Modules — right in your terminal or AI chat. No story files required. <p align="center"> <img src="docs/demo.gif" alt="frameshot demo" width="720" /> </p> **Claude Code** ```bash claude mcp add frameshot -- npx frameshot-mcp@latest ``` <details> <summary>Cursor · VS Code · Windsurf · Cline</summary> ```json { "mcpServers": { "frameshot": { "command": "npx", "args": ["frameshot-mcp@latest"] } } } ``` </details> --- ## Watch mode — live AI feedback loop The AI edits a file, saves it, and immediately sees how it looks — without you calling anything. ``` watch_start({ patterns: ["src/components/Button.tsx"] }) → renders on every save → call watch_get_latest("watch-1") to see it ``` The agent fixes → saves → sees → fixes again. You just watch. --- ## GitHub Action — free Chromatic alternative Two lines. Auto-detects changed components. Posts before/after/diff screenshots directly in the PR comment. ```yaml - uses: actions/checkout@v7 with: fetch-depth: 0 - uses: kamegoro/frameshot@v0.8.0 ``` <p align="center"> <img src="docs/diff-before.png" alt="Before" width="210" /> &nbsp; <img src="docs/diff-after.png" alt="After" width="210" /> &nbsp; <img src="docs/diff-result.png" alt="Diff" width="210" /> </p> Changed `.tsx`, `.jsx`, `.vue`, `.svelte`, `.astro`, `.mdx` files detected automatically. No Storybook. No signup. Free forever. <details> <summary>Options</summary> ```yaml - uses: kamegoro/frameshot@v0.8.0 with: paths: "./src/components/*.tsx" # default: auto-detect extensions: ".jsx,.tsx,.vue" # default: .jsx,.tsx,.vue,.svelte,.astro,.mdx exclude: "*.test.*,*.spec.*" # default: *.test.*,*.spec.*,*.stories.* ``` </details> --- ## Render any component Point to a file. Get a screenshot. Full Vite pipeline. ``` render_file("src/components/Dashboard.tsx") ``` <p align="center"> <img src="docs/example-output.png" alt="Rendered PricingCard with full Tailwind styling" width="280" /> </p> Resolves your project's real imports, Tailwind config, CSS Modules, and path aliases — not a CDN polyfill. --- ## Using with Claude After installing, just describe what you want: ``` "Render src/components/PricingCard.tsx — does it look right?" "Refactor the layout to CSS grid and show me before/after" "Watch Button.tsx while I edit — tell me when something looks off" ``` Claude calls `render_file`, `diff_component`, `watch_start`, or any other tool automatically. --- ## Try it without an AI client Works standalone on any React / Vue / Svelte project: ```bash npx frameshot render src/components/Button.tsx npx frameshot diff src/components/Header.tsx npx frameshot catalog src/components/ --recursive ``` Images display inline in iTerm2, Kitty, and Sixel terminals. Saved to `.frameshot/` by default. > First run installs Playwright's Chromium (~150MB). Subsequent renders are fast. --- ## Tools | Tool | What it does | |------|-------------| | `render_file` | Render a file via Vite — real imports, Tailwind, CSS Modules | | `diff_component` | Pixel diff before/after — % changed, highlighted pixels | | `watch_start` | Watch files — auto-render on every save | | `watch_get_latest` | Get the latest render from a watch session | | `render_catalog` | Render every component in a directory at once | | `screenshot_url` | Screenshot any URL — localhost, staging, prod | | `render_responsive` | Mobile + tablet + desktop in one call | | `render_theme` | Light + dark mode side by side | | `audit_a11y` | axe-core accessibility audit (WCAG violations) | | `render_component` | Render a self-contained code snippet | <details> <summary>All 22 tools</summary> | Tool | What it does | |------|-------------| | `render_file` | Render a project file with full Vite dependency resolution | | `render_component` | Render a self-contained snippet → screenshot | | `screenshot_url` | Screenshot any URL with retry and network idle wait | | `render_responsive` | Mobile + tablet + desktop in one call | | `render_variants` | Multiple prop/state variants at once | | `render_theme` | Light + dark mode side by side | | `render_interaction` | Simulate click/hover/type, then screenshot | | `render_grid` | Multiple snippets in a labeled grid | | `render_matrix` | Viewport × theme matrix in one call | | `capture_animation` | Multi-frame CSS animation capture | | `diff_component` | Before/after pixel diff with % changed | | `diff_reference` | Compare render against a reference image (Figma QA) | | `audit_a11y` | axe-core accessibility audit | | `perf_audit` | DOM count, depth, render timing | | `render_catalog` | Render all components in a directory | | `snapshot_save` | Save a render as named baseline | | `snapshot_check` | Compare current render against saved baseline | | `snapshot_list` | List all saved snapshots | | `watch_start` | Start watching files — renders on every save | | `watch_stop` | Stop a watch session | | `watch_get_latest` | Get the latest rendered screenshot from a session | | `watch_list` | List active watch sessions | </details> --- ## Performance | Scenario | Time | |----------|------| | Warm render (Vite server cached) | **~200–500ms** | | CDN fallback (no Vite) | **~120ms** | | Cold start (first render) | ~1–3s | | Subsequent renders (same session) | ~200ms | Vite server is cached per project root. Browser pool stays warm between MCP calls. --- ## vs. alternatives | | Storybook | Chromatic | Browser MCP | **frameshot** | |---|-----------|-----------|-------------|---------------| | Setup | Stories + config | SaaS signup | Browser install | **`npx` — done** | | Speed | Dev server startup | Cloud round-trip | 2–5s | **~200ms warm** | | Cost | Free (labor cost) | $149–800+/mo | Free | **Free forever** | | Story files needed | Yes | Yes | No | **No** | | Real imports resolved | Via Storybook | Via Storybook | No | **Via Vite** | | Works offline | Yes | No | Yes | **Yes** | | Watch mode | No | No | No | **Yes** | | AI-native (MCP) | No | No | Full-page only | **Component-level** | --- ## Development ```bash git clone https://github.com/kamegoro/frameshot.git cd frameshot && npm install npx playwright install chromium npm run build && npm test ``` See [CONTRIBUTING.md](.github/CONTRIBUTING.md) for architecture details. --- MIT © [kamegoro](https://github.com/kamegoro)