Install

Requirements, creating a new Handoff project with the wizard, and the project layout.

Requirements

Node.js 22 or newer. Node.js 24 LTS is recommended.
npm 10 or newer.
A paid Figma account, only if you fetch foundations from a Figma library.
PostgreSQL, only if you run a registry.

Create a project

Run the wizard

Terminal

npx handoff-app init
cd my-handoff-project

The wizard asks for the project name, sample content or a blank project, JavaScript or TypeScript, an optional Vercel setup, and optional Figma credentials. It writes the starter files and installs handoff-app in the project.

Fetch Figma foundations (optional)

Terminal

npm run fetch

See Figma foundations for the credentials and the output.

Start the documentation

Terminal

npm run start

Open http://localhost:3000. Handoff rebuilds changed files while the command runs.

npm scripts

init adds npm scripts that run the project's own version of handoff-app, so local development and CI use the same version:

Terminal

npm run fetch       # fetch Figma foundations
npm run start       # local server with Handoff file watchers
npm run dev         # local server without file watchers
npm run build       # static build by default
npm run publish     # publish to a registry
npm run checkout    # check out from a registry
npm run login       # sign in to a registry
npm run logout      # sign out of a registry
npm run db:migrate  # registry database migrations

npm passes the arguments after -- to the CLI, for example npm run build -- --target registry. For commands without a script, use npx handoff-app <command>. See the CLI reference.

Project layout

my-handoff-project/
├─ handoff.config.ts
├─ .env
├─ components/
├─ patterns/
├─ pages/
├─ exported/       # fetched tokens and assets; commit this directory
├─ public/api/     # generated docs API; gitignored
├─ out/            # build output; gitignored
├─ .vercel/        # --package vercel output; gitignored
└─ .handoff/       # local Handoff state and saved logins; gitignored

In a project that init creates, the working directory is the repository root.
.handoff/ holds the build cache and cli-auth.json, the saved registry logins. Never commit it.

Next steps

Add Handoff to an existing app instead of a new project.
Declare catalog items.
Configure Handoff.

Install

On this page