cloudcannon-dev-server

The CloudCannon dev server

cloudcannon dev runs the real CloudCannon app against local files, with no login, on one origin. This skill starts the local editing loop and hands it to the user.

The rule that costs the most sessions

MUST rebuild the site after every change. cloudcannon dev never builds.

Why: the server serves a directory and syncs source files; it does not run the SSG. --app-sync carries an editor save to disk, so the field shows the new text — but the preview renders the built output, and nothing regenerated it. The user sees their edit in the field and the old page beside it, with no error anywhere.

The loop

cloudcannon configure detect-build-commands   # build command and output directory
<build the site>                              # see The build command, below
cloudcannon dev <output-dir> --port 10101     # leave running

Then tell them to open http://localhost:10101, and that Ctrl-C stops the server.

They do this	This happens
Change a source file in the editor	It reaches disk. Rebuild, then the preview updates itself
Change a source file on disk	Same — the server syncs it into the app. Rebuild, same result

The preview reloads itself whenever the output directory changes, so a rebuild in a second terminal closes the loop with nothing else running. See dev-server-api.md § Events.

Offer the user both routes and let them pick:

Route	What they do	Costs
Manual	Re-run the build after a batch of edits	Nothing. Rebuild when they want a fresh preview
Watched	Run watch-build.mjs	A full build per change

Default to manual. A watched rebuild after each save changes the output directory, and the preview then reloads the whole page. The editable regions' own in-place re-render is hidden behind that reload, so testing visual editing feels jarring. Manual also suits a slow build, or a post-build step that rewrites the whole output.

Offer watched when the user wants the preview to follow edits that editable regions don't re-render on their own: content edited in the source editor, data files, templates or styles.

The build command

MUST detect the build with the CLI rather than by looking for config files. cloudcannon configure detect-build-commands is the product's own detection and covers every SSG the CLI knows. MUST NOT keep a second detection table anywhere in this skill; it would drift from the CLI's. Take the command it suggests (npm run build), not the bare SSG command — see setup.md § Build commands.

When to use

• The user wants to see and edit their site in CloudCannon before it is deployed anywhere
• You just wrote editable regions, collections or inputs and the user needs to try them
• The user reports a page as missing, blank or broken in CloudCannon, and you need to reproduce it locally against the real app

When not to use

• Authoring collections, inputs or structures — that is cloudcannon-configuration. This skill serves the result; it does not decide it.
• Authoring editable regions — that is cloudcannon-visual-editing.
• Checking that a site's output is correct — whether URLs match the collection config, whether pages are orphaned. This skill starts a server; it does not grade the site.
• Driving the editor in a browser — clicking regions, dumping inputs, screenshotting. Ask the user to look.
• Final sign-off. Local CloudCannon has no real save-to-git, no build pipeline and no permissions. A human still confirms on the hosted site.
• Testing hosted-only behaviour. The local app isn't told the SSG, so SSG-specific rules don't apply locally — a Hugo site's config files show in a collection locally even without include_developer_files (Site config as data). Creating new files isn't a faithful test either: an unsaved new entry carries a temporary flat name.

Contents

File	Covers
setup.md	Prerequisites, what cloudcannon dev does and does not do, the build, ports
dev-server-api.md	The /__api surface — every route and the event stream
troubleshooting.md	Symptom → cause → fix
scripts/README.md	watch-build.mjs and its flags

Common mistakes

Excuse	Reality
"cloudcannon dev is running, so the loop works."	It serves a directory and nothing else. Until something rebuilds, the preview is whatever was built last.
"The editor saved but the page did not change."	Expected. Rebuild — and with a watcher, wait for the build to finish.
"I will open /index.html to see the built page."	/ and /index.html both serve the CloudCannon app. The built homepage is at /__output/index.html.
"/about/ returns 500, the server is broken."	The server has no directory index. Request /about/index.html.
"Port 10101 answers, so my site is up."	It proves a dev server is there, not that it is yours. Serve on a port you chose and know is free.
"The diff is huge, something corrupted it."	CloudCannon reserialises the whole frontmatter on save. Diff the field you changed.