Install

handoff-app is a single npm package that a workspace installs as a dependency, then drives through its CLI. There's no separate server process to run locally, start boots the same Next.js app the registry runs, just backed by the filesystem instead of Postgres (see Local preview).

Requirements

• Node 20.9+ (handoff-app's engines field requires >=20.9.0).
• Don't nest a workspace under a parent npm/pnpm workspace that also hoists handoff-app's own dependencies (next, drizzle-orm, etc.), it can shadow versions and confuse handoff-app's own dependency resolution. Give the workspace repo its own lockfile.

Add it to an existing repo

Install handoff-app in the workspace's own package.json (not at a monorepo root, see Directory conventions for why per-workspace install is the recommended pattern):

npm install handoff-app

A minimal workspace package.json needs little else:

{
  "name": "my-design-system",
  "private": true,
  "scripts": {
    "start": "handoff-app start",
    "fetch": "handoff-app fetch",
    "build": "handoff-app build:components",
    "push": "handoff-app push:all"
  },
  "dependencies": {
    "handoff-app": "^2.0.0"
    // + any runtime deps your component templates import (bootstrap, jquery, etc.)
  }
}

handoff-app brings its own next, react, react-dom, drizzle-orm, playwright-core, and build toolchain as direct dependencies, a workspace doesn't install any of these itself. If you're migrating an older workspace that used to deploy itself as a Next.js app, it can drop next, react, react-dom, @sparticuz/chromium, and any eslint-config-next / @types/react* packages once it's push-only.

Scaffold a new workspace

npx handoff-app init

handoff-app fetch

handoff-app start