Run the Editor from a checkout

Most people run the Editor as the macOS app. This page is the other path: cloning the Desde repository and running the Editor as a command-line tool. It exists for two audiences, people working on Desde itself, and anyone who wants to run it on Windows or Linux, since the signed app is Mac-only.

Nothing here changes what the Editor does. It is the same tool, started a different way.

Prerequisites#

You need git and Node 22.12 or newer. Check your Node version with node -v.

Install and build#

Clone the repository:

git clone https://github.com/desde-design/desde.git

Install the root dependencies:

cd desde && npm install

Install the CLI's own dependencies. The CLI has a separate node_modules. The root install does not cover it, and the CLI's launcher script looks for its TypeScript loader there specifically.

npm --prefix editor-cli install

Build the Editor's own interface bundle:

npm --prefix editor-cli run build:ui

That last step is not optional on a fresh clone. editor-cli/ui-src/dist is gitignored, so it does not arrive with the checkout, and the CLI refuses to start without it. The build reads shared React components from the monorepo's root src/, which is why the root install has to come first.

Note You do not need to build the bridge. The bridge is the small script the Editor injects into your prototype so it can highlight and read elements. Its bundle at dist/bridge-bundle.js is committed to the repository, so npm run build:bridge is only needed if you change bridge source yourself.

Start the Editor#

From the Desde checkout, pass the path to your prototype:

node editor-cli/bin/desde.mjs ../my-prototype

The path can be relative or absolute. The terminal prints something close to this:

[editor-cli] branch mode: editing the current working tree in place at /Users/you/my-prototype (no worktree, no auto-commit)
▸ Vite running at http://127.0.0.1:5173
▸ Editor UI ready at http://127.0.0.1:4321
▸ Bridge version 2026-09-01a-callsite-edit-target
▸ Orchestrator: SDK (CLAUDE.md loaded natively)
▸ Smoke check passed (bridge tag + data-desde-src present in served output)

Your browser opens at the Editor URL on its own. If it does not, open the printed URL yourself.

Warning Use the exact URL that was printed, host and all. The Editor's API rejects any request whose Origin header is not exactly http://127.0.0.1:<port>. Visiting http://localhost:4321 instead loads the page but makes every action fail with a 403.

What the boot actually does#

It checks your framework first, before anything slow starts. It reads your package.json for a vue or react dependency. If Vue and React are both present, Vue wins. A Vue major other than 3 is refused outright. See the repository gate for the full check.

It starts your dev server, not its own. The Editor loads your Vite config, merges in a handful of plugins (five on a Vue repo, two on a React one), and runs the result. Two of them matter here: one injects the bridge into the served HTML, and one stamps a data-desde-src="file:line:column" attribute onto your elements so a click in the browser can be traced back to a line of source. Neither is ever written to disk. Your repository is untouched by the injection.

It picks two ports. The editor interface wants 127.0.0.1:4321 and your Vite server wants 127.0.0.1:5173. If either is taken (a second Editor is already running, or you already have a dev server up), it silently falls back to a free port the operating system chooses. This is why you read the URL off the terminal rather than assuming 4321.

Override either with --shell-port or --vite-port, and skip the browser launch with --no-open. Run with -h for the full list, or see the CLI reference.

The `.desde` directory#

A .desde/ directory appears in your repository the first time you use the Editor. It holds the Editor's own state: per-edit backups it uses for Undo, chat transcripts, extracted component manifests, and project configuration.

You do not have to add it to .gitignore. On boot the Editor appends .desde/ to .git/info/exclude in your checkout. That is a local ignore file: never committed, never visible to your teammates. Your git status stays clean.

More detail#