Local Preview
Running a filesystem-backed preview of your workspace before pushing to a registry.
handoff-app startstart boots the same handoff-app Next.js server a registry runs, same pages, same
component preview rendering, same MCP endpoint, but backed by StaticDataProvider instead of
Postgres. StaticDataProvider reads directly off the workspace filesystem
(HANDOFF_WORKING_PATH): design-system/dist/ for compiled tokens, per-component build
artifacts under components/<id>/dist/<id>.json (shared global assets like main.css /
main.js live under public/api/component/), pages/**/*.md for docs, icons/catalog.json /
logos/logo-set.json for assets. No DATABASE_URL, no registry connection required.
`start`, not `dev`
start builds components, patterns, JS and CSS first, then runs a dev server with file
watchers and WebSocket live reload. handoff-app dev is a different command: plain next dev
against the materialized app, with no component build, so the preview comes up empty. It
exists for debugging the Next.js app itself, not for previewing a design system.
This is the same getDataProvider() switch Architecture
describes, every page and API route reads through it identically in both modes, so what you see
locally is a faithful preview of what a registry will render once you push.
What's local-only vs. push-dependent
Anything derived purely from files in the workspace renders identically in start and on a
registry: foundation pages (colors, typography, spacing, icons, logos), component
docs/previews, and markdown pages.
What you can't preview locally, because it only exists once persisted to a registry's database:
- The changelog (
/api/handoff/changelog), built from sync events recorded on push. - Component validation history and version history, recorded per push.
- Anything authored directly in the registry's own UI (pages/patterns edited by a stakeholder,
not pulled back down yet), until you run
pull. - MCP tools/routes that require an authenticated registry connection in registry mode (workspace mode itself is open by default, see MCP → Auth).
The dev loop
edit locally → handoff-app start (preview) → handoff-app push:all (or push) → verify on the registryfetch and tokens:build refresh token data as needed in between; pull brings remote edits
(anything changed in the registry's own UI) back down before you continue editing. See
CLI reference for every command's flags, and
Install for first-time setup via handoff-app init.