Skip to main content
The live preview is a container running next dev on ephemeral disk, hydrated from your saved project files. It is not a deployment: file saves and preview syncs reach it instantly and touch no hosting environment, and nothing on your live site changes until you deploy. The container itself is disposable. It auto-suspends after idle (a stopped preview is routine, not a failure), it is excluded from checkpoints, and it can be rebuilt from the saved project at any time. The saved project, and in particular its package.json, is the only source of truth: since 2026-09-02 the platform no longer seeds the starter template over a project that has files, and leftover starter files from older boots are cleaned automatically on the next sync.
The tools on this page are the agent tool catalog, used by external agents such as the Claude Code plugin and LLM connectors. The AI assistant inside the builder carries an equivalent surface of its own and applies the same repairs automatically when the preview misbehaves.

​
Reading preview state

preview_overview is the one-call status and the first call in any code-change workflow. It returns ready, the user-visible preview URL, status (running / stopped / starting), health, phase, the last sync timestamp, and the count of file changes pending sync, plus blockers (hard stops to surface to the user) and hints (next actions for the agent). ready: true here means the container is up and the project’s files have landed on it. A change is not verifiable, and not “done”, while ready is false. A phase of syncing means files are still being delivered: check again every 5 to 10 seconds until ready. A blocker naming a delivery or Node-version problem carries the fix in plain language; surface it rather than retrying blindly.

​
Boot phases

preview_health is a passthrough of the container’s own /api/health endpoint: { ready, phase, app, proxy }. The phase field is the boot truth:
ready: true is gated server-side on both preview_health and preview_overview: it means the dev server compiled and the project’s files landed on this machine. If a page still renders the starter template or “Untitled site”, treat that as container divergence (Class 1 below), never as a health problem. Polling preview_health never wakes a stopped machine: a stopped preview is answered from the machine state as { ready: false, phase: "stopped", machine_status } - start it with preview_start, then poll.

​
Status and lifecycle

​
Getting changes onto it

preview_sync reports the container’s real per-file result. The synced count is the container’s successful count, so a genuine 0 means 0:

​
Seeing and diagnosing

The verification tools (verify_typecheck, verify_lint, verify_run_tests) also run inside the preview environment and return structured exit codes; prefer them over log-scraping for typecheck, lint, and test results.
An empty preview_client_errors result is not proof the page is clean. Check the returned capture_installed flag: false means capture is not wired on this container (an older machine image), so recreate it with preview_force_recompile({ refresh_image: true }). Even when true, errors are only recorded when the page actually runs in a browser, so load it first (for example with preview_screenshot) and re-check.

​
Repair

​
When the preview breaks: classify first

Preview failures divide into four classes. Only one of them is fixed by editing code, so read the error and classify before acting:
  1. The error names a file that is not in the project. For example Module not found: Can't resolve '@radix-ui/react-label' from ./components/ui/label.tsx, when the project’s saved file list has no such file. That is a starter leftover on the container, not your code: run preview_force_recompile. If the identical error persists, run it once more with refresh_image: true; only the full recreate prunes leftovers. Two fixes are forbidden: never add the starter’s package to the project’s package.json to silence the error, and never delete or edit the container file by hand, because container edits sync back into the saved project.
  2. Module not found: Can't resolve './x' where the importing file is inside node_modules/<pkg>/. A package failing to resolve its own relative file is a broken install: run preview_reinstall_deps and poll the install log as described above.
  3. The error points at a file the project owns. Fix the code. This is the only class where editing is the answer. One sub-case: a persistent module-not-found on a file the project does own means the project imports a package it never declared. Add the dependency to package.json; recreating the container cannot fix a manifest defect.
  4. Blank page, or the HTML serves but interactivity is dead. This is hydration territory: run preview_client_errors. A capture_installed: false result means an old container image, so run preview_force_recompile({ refresh_image: true }).
Related container state, same discipline: missing images for files that do exist in the media library are Class-1-adjacent divergence, fixed by preview_assets_resync, never by re-uploading.
Since 2026-09-02, a recreated machine of a project with files no longer seeds the starter template or its node_modules. It waits for the project’s own files and installs exactly what package.json declares, so a routine reinstall after refresh_image: true is no longer required; reach for preview_reinstall_deps only when the install itself is broken.

​
Preview-green is not deploy-green

A build error that does not surface in the live preview can still kill a deploy: the deploy pipeline uses a different bundler, Node baseline, and env injection. Verify the deploy path itself before shipping; see Deployments.