Builds

build has two independent options: --target decides what is built, and --package decides how it is delivered.

--package never changes the target. --package standalone is the default output of each target.

Static site

npm run build

The output in out/static runs on any static file server or CDN. A static site has no API routes, so it has no MCP endpoint and no AI assistant. build:app is the same build.

Set app.basePath when the site is served under a sub-path.

Registry server

npm run build -- --target registry

• The generated app is always in registry mode, whatever runtime.mode says.
• The output is a Next.js server bundle in out/registry, started with node out/registry/server.js.
• The build does not compile or serve workspace source. Content arrives later with publish.
• The build bakes the database driver, asset storage provider, email provider, MCP setting, assistant setting, and custom server modules. Set them before you build, usually in a registry profile.
• The build writes out/registry/README.md, listing every environment variable the build needs.

See Deploy a registry.

Vercel

npm run build -- --target registry --package vercel

When you choose the Vercel option, init writes a vercel.json with this build command and "framework": null. Pick --target static instead to host the static site on Vercel.

Build cache

Handoff does not rebuild a component whose files did not change since its last build. The cache in .handoff/.cache/ records each component's files and every file its last build read, Sass partials included. The lockfile covers files under node_modules. Every full build and every publish uses the cache.

The cache does not track assets that a stylesheet loads through url(). Rebuild everything with:

npm run build -- --force

Build only the catalog

npx handoff-app build:components
npx handoff-app build:components button

Builds catalog items without the documentation app. A name builds one item. build --skip-components does the reverse: it builds the app without a component build first.