create-handover

Scaffold a new Handover client site — a white-label admin boilerplate that connects to the Handover CMS platform via API key.

Usage

Scaffold a new project

pnpm create handover@latest
# or
npx create-handover@latest
# or with a target directory:
pnpm create handover@latest my-client-site

The interactive setup lets the user choose pnpm, npm, yarn, or bun for dependency install and the printed next-step commands.

Add agent-friendly component mappings

pnpm handover add homepage.hero.title "Ship faster with Handover"
pnpm handover deploy
# or without global install
npx create-handover@latest add homepage.hero.title "Ship faster with Handover"

This command writes to .handover/agents.json by default (override with --file). It also copies your Handover API key into the registry when found in process.env, .env.local, or .env. Run pnpm handover deploy to push the local registry to your live Handover project.

Remote deploys use the Handover API URL/key from your env file. Admin sessions are only needed for direct admin API updates, not handover deploy.

The CLI will prompt you for:

• Project directory name — where to scaffold the project
• Template selection — pick between bundled framework starters (arrow keys + Enter)
• tRPC placeholder — optional tRPC env stub (Next.js template only)
• Package manager — choose pnpm, npm, yarn, or bun for install and next-step commands
• Handover credentials — optionally write API URL and key into the generated env file
• Dependency install — optionally install dependencies after scaffolding
• Git setup — optionally initialize a repository on main

Scaffolds include .handover/context.json, which gives coding agents the template metadata, API env names, and known site component slots.

What you get

Bundled templates:

• next — production-ready Next.js admin template pre-wired to Handover
• vite-react — Vite + React + TypeScript admin starter
• tanstack-start — TanStack Start + Vite + TypeScript admin starter
• astro — Astro content starter with docs/blog routes and image-key rendering

All templates are sourced from templates/ at the workspace root and packed into this package for npm releases.

All templates include:

• /admin — password-protected content & media management dashboard
• /admin/login — authentication gate
• /docs and /blog routes where supported by the framework starter
• White-label branding surface via framework-specific lib/branding module
• User management (create/update/disable/delete/reset)
• Lock-state (HANDOVER_LOCKED) handling built in

Setup after scaffolding

cd my-client-site
# Use the package manager selected during setup, for example:
pnpm install
# `.env.local` is created automatically from `.env.example`
# Fill in your API key and URL values
pnpm dev

Environment variables

| Variable | Description | |---|---| | NEXT_PUBLIC_HANDOVER_API_URL | Your Handover platform URL for Next.js | | NEXT_PUBLIC_HANDOVER_API_KEY | Project API key (ho_live_*) for Next.js | | VITE_HANDOVER_API_URL | Handover platform URL for Vite React and TanStack Start | | VITE_HANDOVER_API_KEY | Project API key for Vite React and TanStack Start | | PUBLIC_HANDOVER_API_URL | Handover platform URL for Astro | | PUBLIC_HANDOVER_API_KEY | Project API key for Astro | | NEXT_PUBLIC_SITE_NAME | Display name for the admin UI (optional) |

Options

--template <id>         Choose bundled template id (next, vite-react, tanstack-start, astro)
--list-templates        Print bundled templates and exit
--template-dir <path>   Use a custom local template instead of the bundled one
--api-url <url>         Write Handover backend URL into the scaffold env file
--api-key <key>         Write Handover API key into the scaffold env file
--package-manager <pm>  Choose pnpm, npm, yarn, or bun for next steps/install
--install               Install dependencies after scaffolding
--no-install            Skip dependency install
--git                   Initialize a git repository after scaffolding
--no-git                Skip git initialization
--file <path>           Override registry path for `add` command
-y, --yes               Skip prompts; pass --template or --template-dir

Remote deploy env:
HANDOVER_API_URL or framework public variants (NEXT_PUBLIC_ / VITE_ / PUBLIC_)
HANDOVER_API_KEY or framework public variants (NEXT_PUBLIC_ / VITE_ / PUBLIC_)

tanstack-router is accepted as a backward-compatible alias and maps to tanstack-start.

Deploy content from local files

pnpm handover deploy
pnpm handover deploy --manifest ./handover.content.json --mode merge
pnpm handover deploy --docs ./docs
pnpm handover deploy --blog ./blog
pnpm handover deploy --assets .handover/assets

Markdown frontmatter can set title, slug, excerpt, collection, and status. Uploaded images get a stable Handover key so generated sites can render them through content.imagesByKey.<key>.url.

Agents should keep Handover-managed images as local files in .handover/assets. A plain pnpm handover deploy uploads that folder when it exists; pnpm handover deploy --assets .handover/assets is the explicit form. Supported image extensions are .png, .jpg, .jpeg, .webp, .svg, and .gif. Do not store image bytes or temporary upload URLs in .handover/agents.json.

HANDOVER_TEMPLATE_DIR=/path/to/template   Env-based template override

Links

• Handover Platform
• SDK on npm