Get started with DesignJS

Clone the repo, install dependencies, and have the HTML/CSS canvas running locally in under five minutes — no cloud account required.

DesignJS runs entirely on your machine. The canvas is a local Vite app you run from the cloned repo; agents connect to it over a WebSocket bridge on 127.0.0.1:29170. Getting set up is two steps — start the canvas, then scaffold (or wire up) a project for your agent.

The canvas itself (the React + GrapesJS app) is not yet distributed as an npm package — you run it from the repo. The MCP server and the project scaffolder are published on npm (@designjs/mcp-server, create-designjs), so your agent’s project doesn’t need a clone.

Prerequisites

• Node.js 20 or later — nodejs.org
• pnpm 9 or later — install via Corepack:

corepack enable
corepack install -g pnpm@9

Step 1 — Start the canvas

1. Clone the repository

   git clone https://github.com/rubychilds/DesignJS.git
   cd DesignJS
   
2. Install dependencies

   From the repository root, install all workspace packages at once:

   pnpm install
   
3. Start the development server

   pnpm dev
   

   This command builds the @designjs/bridge package (so protocol types are up to date) and then boots the Vite dev server with the React canvas app. The WebSocket bridge starts automatically as part of the same process.

4. Open the canvas

   Navigate to http://localhost:3000 in your browser. You should see the three-pane editor — block palette on the left, the GrapesJS canvas in the center, and the style/layer panels on the right.

   The connection status indicator in the top-right corner of the editor shows whether an AI agent is currently connected. It will show disconnected until you complete step 2.

Step 2 — Scaffold a project for your agent

Leave the canvas running in its own terminal. In a second terminal, scaffold a new project wired up to the MCP server:

npm create designjs@latest my-app
cd my-app

This drops three files in my-app/:

• .mcp.json — tells Claude Code / Codex-style clients to spawn npx -y @designjs/mcp-server
• CLAUDE.md — agent guidance biasing tool choice toward DesignJS (and away from other design MCPs you may have configured globally)
• README.md — project-level quickstart + troubleshooting

Now start your agent from inside my-app (not its parent):

claude          # or cursor . / code .

On the first tool call, the agent runs npx -y @designjs/mcp-server, connects to the canvas, and the bridge dot in the editor topbar turns green.

Already have a project? create-designjs refuses to scaffold into a non-empty directory. For existing projects, write .mcp.json by hand — see Connect an agent for the three-line config and troubleshooting for the most common discovery issues.

What’s running

Once pnpm dev is up, two services are active:

Service	Address	Purpose
Canvas UI	http://localhost:3000	The visual editor you open in your browser
WebSocket bridge	ws://127.0.0.1:29170/designjs-bridge	The relay between the MCP server and the canvas

Both services are started by a single pnpm dev command. You do not need to start them separately.

Keyboard shortcuts

Once the canvas is open, a few shortcuts are worth knowing right away:

Action	Mac	Windows / Linux
Save	Cmd+S	Ctrl+S
Duplicate selection	Cmd+D	Ctrl+D

The canvas also auto-saves every 30 seconds to .designjs.json in the project root.

Next steps

Connect an AI agent

Wire Claude Code, Cursor, or VS Code to the canvas so your agent can read and write designs directly.