Docs
Open docs navigation
Configuration

Updated May 13, 2026

6 min read

Environment Variables

Configure your client site with environment variables for API connection, branding, and optional features.

environment variablesconfigurationenv setupapi keyswhite label

Handover uses environment variables for configuration. This keeps sensitive data secure and makes sites easy to customize per client.

Required Variables

These variables must be set for the site to function. Copy them from your Handover project dashboard or let the CLI write them during scaffolding. The API URL should be the HTTP site domain, usually ending in .convex.site, not the Convex client deployment URL ending in .convex.cloud.

  • Next.js: NEXT_PUBLIC_HANDOVER_API_URL and NEXT_PUBLIC_HANDOVER_API_KEY
  • Vite React and TanStack Start: VITE_HANDOVER_API_URL and VITE_HANDOVER_API_KEY
  • Astro: PUBLIC_HANDOVER_API_URL and PUBLIC_HANDOVER_API_KEY
# Next.js
NEXT_PUBLIC_HANDOVER_API_URL=https://your-app.convex.site
NEXT_PUBLIC_HANDOVER_API_KEY=ho_live_your_project_key_here

# Vite React / TanStack Start
VITE_HANDOVER_API_URL=https://your-app.convex.site
VITE_HANDOVER_API_KEY=ho_live_your_project_key_here

# Astro
PUBLIC_HANDOVER_API_URL=https://your-app.convex.site
PUBLIC_HANDOVER_API_KEY=ho_live_your_project_key_here
bash

Deploy Credentials

pnpm handover deploy, including manifest, docs, blog, and asset deploys, uses only the API URL/key pair above. HANDOVER_ADMIN_SESSION, HANDOVER_ADMIN_USERNAME, and HANDOVER_ADMIN_PASSWORD are reserved for direct admin API updates and generated /admin sessions.

API Key Format

API keys have a specific format to indicate environment. Always use live keys for production deployments.

  • Live keys: ho_live_[uuid] - for production sites
  • Test keys: ho_test_[uuid] - for development/staging
  • Keys are generated when you create a project
  • Regenerate keys if compromised

Branding Variables (Optional)

Customize the admin interface and site metadata per client. All branding variables are optional and have sensible defaults.

# Site branding
NEXT_PUBLIC_SITE_NAME="Acme Corp Website"
NEXT_PUBLIC_ADMIN_TITLE="Acme Admin Dashboard"
NEXT_PUBLIC_BRAND_TAGLINE="Keep your content fresh..."
NEXT_PUBLIC_SUPPORT_EMAIL="support@acmecorp.com"
bash

Security Best Practices

Follow these guidelines to keep your configuration secure.

  • Never commit .env.local to version control
  • Add .env.local to .gitignore
  • Use different API keys for staging and production
  • Rotate API keys when team members leave
  • Store production env vars in hosting platform securely

Vercel/Netlify Setup

When deploying to hosting platforms, add environment variables through their dashboard rather than committing them.

# Vercel CLI
vercel env add NEXT_PUBLIC_HANDOVER_API_URL
vercel env add NEXT_PUBLIC_HANDOVER_API_KEY

# Or use dashboard: Settings > Environment Variables
bash
Source doc: packages/create-handover/templates/next-js/.env.example

Related guides

Getting started

Initial setup and configuration.

Deployment checklist

Complete pre-launch checklist.

Back to docs