nextcanvas-ai
v0.1.2
Published
Click on your UI. Describe the change. Claude fixes the code.
Maintainers
Readme
nextcanvas-ai
Click on your UI. Describe the change. Claude fixes the code.
nextcanvas-ai is a dev-only tool for React apps that lets you visually edit your UI by clicking elements in the browser, describing what you want changed, and having Claude Code edit the source code automatically.
Supports: Next.js (App & Pages Router), Vite + React, Remix, Create React App, and any React project.
How it works
Browser ──click + describe──▶ HTTP Server ──▶ MCP Server ──▶ Claude Code
│
edits your code
│
Browser ◀──green checkmark── HTTP Server ◀── MCP Server ◀── resolves- You click an element in your running app and type a change (e.g. "make this button blue")
- nextcanvas detects the React component, file path, line number, props, and styles
- Claude Code reads the annotation, edits the source file, and resolves it
- Next.js Fast Refresh hot-reloads the change — you see it instantly
Install
npm install nextcanvas-ai
npx nextcanvas-ai-initThe init script auto-detects your framework and does everything:
- Detects Next.js, Vite, Remix, CRA — or lets you choose
- Adds
<NextCanvas />to your entry file (dev only, zero production impact) - Registers the MCP server with Claude Code
- Sets up auto-approve permissions so there are no prompts
- Creates a
CLAUDE.mdwith instructions for Claude - Adds a
dev:canvasscript to yourpackage.json
Use
npm run dev:canvasOne command. Starts Next.js and Claude Code together. Click any element in your browser, describe the change, and watch Claude handle it.
Features
Annotate
Click any element, type what you want changed. Claude reads the component source and edits the code.
- Detects React component name, file path, line number, and props via fiber tree
- Extracts CSS, bounding box, accessibility attributes, and nearby text context
- Supports text selection — highlight text and describe the change
Rearrange
Switch to rearrange mode and drag elements to reorder them. Claude updates the source to match the new order.
- Auto-detects flex/grid containers
- Drag handles appear on child elements
- Drop line shows insertion point
Threaded conversations
If Claude isn't sure what you mean, it asks a follow-up question that appears in your browser. You reply inline — no context switching.
Working indicator
A floating bubble with bouncing dots shows when Claude is processing your request. Each annotation shows its status: Queued or Working.
Manual setup
If you prefer not to use the init script:
1. Add to your root layout:
import { NextCanvas } from 'nextcanvas-ai'
export default function RootLayout({ children }) {
return (
<html>
<body>
{children}
{process.env.NODE_ENV === 'development' && <NextCanvas />}
</body>
</html>
)
}2. Register the MCP server:
claude mcp add nextcanvas -- node node_modules/nextcanvas-ai/bin/mcp.mjs3. Start your app and tell Claude to watch:
npm run dev
# In another terminal:
claude "Call the nextcanvas watch tool and process UI annotations"Props
<NextCanvas port={3377} />| Prop | Type | Default | Description |
|------|------|---------|-------------|
| port | number | 3377 | HTTP server port for browser-MCP communication |
How it works under the hood
Three parts
Browser overlay — A React client component rendered via portal. Handles click-to-annotate, hover highlights, rearrange drag, threaded conversations, and status display.
HTTP server — Lightweight Node.js server on port 3377. Bridges browser and MCP via /tmp/nextcanvas-annotations.json and /tmp/nextcanvas-responses.json.
MCP server — Stdio-based server using @modelcontextprotocol/sdk. Exposes tools to Claude Code:
| Tool | Description |
|------|-------------|
| watch | Wait for new annotations (main loop, long-polls 60s) |
| list_annotations | List all pending annotations |
| get_annotation | Get full details of one annotation |
| acknowledge | Tell the browser you're working on it |
| resolve | Mark annotation as done |
| reply | Ask a follow-up question |
| watch_replies | Wait for the developer's reply |
| get_page_info | Annotation count summary |
React source detection
nextcanvas walks the React fiber tree via __reactFiber$ keys on DOM elements to extract:
- Component name (
displayNameorname) - Source file path, line number, column number (from
_debugSource, dev mode only) - Serializable props
- Parent component chain (up to 5 levels)
This gives Claude the exact file and line to edit.
Requirements
- React 18+
- Claude Code with MCP support
- Node.js 18+
- Any React framework: Next.js, Vite, Remix, CRA, etc.
License
MIT
