vite-flare-starter

name	vite-flare-starter
description	Scaffold a full-stack Cloudflare app from the vite-flare-starter template — React 19 + Hono + D1+Drizzle + better-auth + Tailwind v4+shadcn/ui + TanStack Query + R2 + Workers AI. Run setup.sh to clone, configure, and deploy. Use whenever the user wants a batteries-included Cloudflare full-stack app, vite-flare-starter scaffold, or a React + Cloudflare app with auth + database + Workers AI ready to go.
compatibility	claude-code-only

Vite Flare Starter

Clone and configure the batteries-included Cloudflare starter into a standalone project. Produces a fully rebranded, deployable full-stack app.

Stack

Layer	Technology	Version
Frontend	React, Vite, Tailwind CSS, shadcn/ui	19, 6.x, v4, latest
Backend	Hono (on Cloudflare Workers)	4.x
Database	D1 (SQLite at edge) + Drizzle ORM	0.38+
Auth	better-auth (Google OAuth + email/password)	latest
Storage	R2 (S3-compatible object storage)	—
AI	Workers AI binding	—
Data Fetching	TanStack Query	v5

Cloudflare Bindings

Binding	Type	Purpose
DB	D1 Database	Primary application database
AVATARS	R2 Bucket	User avatar storage
FILES	R2 Bucket	General file uploads
AI	Workers AI	AI model inference

Project Structure

src/
├── client/                 # React frontend
│   ├── components/         # UI components
│   ├── hooks/              # Custom hooks + TanStack Query
│   ├── pages/              # Route pages
│   ├── lib/                # Utilities (auth client, etc.)
│   └── main.tsx            # App entry point
├── server/                 # Hono backend
│   ├── index.ts            # Worker entry point
│   ├── routes/             # API routes
│   ├── middleware/          # Auth, CORS, etc.
│   └── db/                 # Drizzle schema + queries
└── shared/                 # Shared types between client/server

Key Commands

Command	Purpose
pnpm dev	Start local dev server
pnpm build	Production build
pnpm deploy	Deploy to Cloudflare
pnpm db:migrate:local	Apply migrations locally
pnpm db:migrate:remote	Apply migrations to production
pnpm db:generate	Generate migration from schema changes

Workflow

Step 1: Gather Project Info

Ask for:

Required	Optional
Project name (kebab-case)	Admin email
Description (1 sentence)	Google OAuth credentials
Cloudflare account	Custom domain

Step 2: Clone and Configure

2a. Clone and clean

git clone https://github.com/jezweb/vite-flare-starter.git PROJECT_DIR --depth 1
cd PROJECT_DIR
rm -rf .git
git init

2b. Find-replace targets

Replace vite-flare-starter with the project name in these locations:

File	Target	Replace with
wrangler.jsonc	"vite-flare-starter" (worker name)	"PROJECT_NAME"
wrangler.jsonc	vite-flare-starter-db	PROJECT_NAME-db
wrangler.jsonc	vite-flare-starter-avatars	PROJECT_NAME-avatars
wrangler.jsonc	vite-flare-starter-files	PROJECT_NAME-files
package.json	"name": "vite-flare-starter"	"name": "PROJECT_NAME"
package.json	vite-flare-starter-db	PROJECT_NAME-db
index.html	<title> content	App display name (Title Case)

Also in wrangler.jsonc:

• Remove hardcoded account_id line (let wrangler prompt or use env var)
• Replace database_id value with REPLACE_WITH_YOUR_DATABASE_ID

Reset package.json version to "0.1.0".

Use the Edit tool for replacements (preferred over sed to avoid macOS/GNU differences).

2c. Generate auth secret

BETTER_AUTH_SECRET=$(openssl rand -hex 32 2>/dev/null || python3 -c "import secrets; print(secrets.token_hex(32))")

2d. Create .dev.vars

Convert kebab-case project name: my-cool-app becomes Display My Cool App, ID my_cool_app.

# Local Development Environment Variables
# DO NOT COMMIT THIS FILE TO GIT

# Authentication (better-auth)
BETTER_AUTH_SECRET=<generated>
BETTER_AUTH_URL=http://localhost:5173

# Google OAuth (optional)
GOOGLE_CLIENT_ID=
GOOGLE_CLIENT_SECRET=

# Email Auth Control (disabled by default)
# ENABLE_EMAIL_LOGIN=true
# ENABLE_EMAIL_SIGNUP=true

# Application Configuration
APP_NAME=<Display Name>
VITE_APP_NAME=<Display Name>
VITE_APP_ID=<app_id>
VITE_TOKEN_PREFIX=<app_id>_
VITE_GITHUB_URL=
VITE_FOOTER_TEXT=

NODE_ENV=development

2e. Create Cloudflare resources (optional)

npx wrangler d1 create PROJECT_NAME-db
# Extract database_id from output, update wrangler.jsonc

npx wrangler r2 bucket create PROJECT_NAME-avatars
npx wrangler r2 bucket create PROJECT_NAME-files

2f. Install and migrate

pnpm install
pnpm run db:migrate:local

2g. Initial commit

git add -A
git commit -m "Initial commit from vite-flare-starter"

Step 3: Manual Configuration

1. Google OAuth (if using): Go to Google Cloud Console, create OAuth 2.0 Client ID, add redirect URI http://localhost:5173/api/auth/callback/google, copy Client ID and Secret to .dev.vars
2. Favicon: Replace public/favicon.svg
3. CLAUDE.md: Update project description, remove vite-flare-starter references
4. index.html: Update <title> and meta description

Step 4: Verify Locally

pnpm dev

Check: http://localhost:5173 loads, shows YOUR app name, sign-up/sign-in works (if OAuth configured).

Step 5: Deploy to Production

# Set production secrets
openssl rand -base64 32 | npx wrangler secret put BETTER_AUTH_SECRET
echo "https://PROJECT_NAME.SUBDOMAIN.workers.dev" | npx wrangler secret put BETTER_AUTH_URL
echo "http://localhost:5173,https://PROJECT_NAME.SUBDOMAIN.workers.dev" | npx wrangler secret put TRUSTED_ORIGINS

# If using Google OAuth
echo "your-client-id" | npx wrangler secret put GOOGLE_CLIENT_ID
echo "your-client-secret" | npx wrangler secret put GOOGLE_CLIENT_SECRET

# Migrate remote database
pnpm run db:migrate:remote

# Build and deploy
pnpm run build && pnpm run deploy

Critical: After first deploy, update BETTER_AUTH_URL with your actual Worker URL. Add the production URL to Google OAuth redirect URIs.

Security Fingerprints

Change all of these so attackers cannot identify your site uses this starter:

Location	Default Value	How to Change
Page title	"Vite Flare Starter"	index.html
App name in UI	"Vite Flare Starter"	VITE_APP_NAME env var
localStorage keys	vite-flare-starter-theme	VITE_APP_ID env var
API tokens	vfs_ prefix	VITE_TOKEN_PREFIX env var
GitHub links	starter repo	VITE_GITHUB_URL (set empty to hide)
Worker name	vite-flare-starter	wrangler.jsonc
Database name	vite-flare-starter-db	wrangler.jsonc
R2 buckets	vite-flare-starter-*	wrangler.jsonc

Environment Variables

Branding (VITE_ prefix = available in frontend)

Variable	Purpose	Example
VITE_APP_NAME	Display name in UI	"My Cool App"
VITE_APP_ID	localStorage prefix, Sentry	"mycoolapp"
VITE_TOKEN_PREFIX	API token prefix	"mca_"
VITE_GITHUB_URL	GitHub link (empty = hidden)	""
VITE_FOOTER_TEXT	Footer copyright text	"2026 My Company"
APP_NAME	Server-side app name	"My Cool App"

Auth

Variable	Purpose	Notes
BETTER_AUTH_SECRET	Session encryption	openssl rand -hex 32
BETTER_AUTH_URL	Auth base URL	Must match actual URL exactly
TRUSTED_ORIGINS	Allowed origins	Comma-separated, include localhost + prod
GOOGLE_CLIENT_ID	Google OAuth	From Google Cloud Console
GOOGLE_CLIENT_SECRET	Google OAuth	From Google Cloud Console
ENABLE_EMAIL_LOGIN	Enable email/password	"true" to enable
ENABLE_EMAIL_SIGNUP	Enable email signup	Requires ENABLE_EMAIL_LOGIN

Email (Optional)

Variable	Purpose	Notes
EMAIL_FROM	Sender address	For verification/password reset
EMAIL_API_KEY	Email service API key	Resend recommended

Common Customisations

Adding a New Database Table

1. Add schema in src/server/db/schema.ts
2. Generate migration: pnpm db:generate
3. Apply locally: pnpm db:migrate:local
4. Apply to production: pnpm db:migrate:remote

Adding a New API Route

1. Create route file in src/server/routes/
2. Register in src/server/index.ts
3. Add TanStack Query hook in src/client/hooks/

Changing Auth Providers

Edit src/server/auth.ts: add provider to socialProviders, add credentials to .dev.vars and production secrets, update client-side login buttons.

Feature Flags

Control features via environment variables: VITE_FEATURE_STYLE_GUIDE=true, VITE_FEATURE_COMPONENTS=true. Add your own in src/client/lib/features.ts.

Troubleshooting

Symptom	Cause	Fix
Auth redirects to homepage silently	Missing TRUSTED_ORIGINS	Set TRUSTED_ORIGINS with all valid URLs
"Not authorized" on deploy	Wrong account_id	Remove account_id from wrangler.jsonc or set yours
Database 500 errors	Missing migrations	Run pnpm db:migrate:local and pnpm db:migrate:remote
localStorage shows "vite-flare-starter"	Missing VITE_APP_ID	Set VITE_APP_ID=yourapp in .dev.vars
Auth fails in production only	BETTER_AUTH_URL mismatch	Must match actual Worker URL exactly (https, no trailing slash)
"redirect_uri_mismatch" on Google sign-in	OAuth redirect URI missing	Add production URL to Google Cloud Console OAuth redirect URIs
Secret changes have no effect	Not redeployed	wrangler secret put does NOT redeploy. Run pnpm deploy after

Production Deployment Checklist

• BETTER_AUTH_SECRET set (different from dev!)
• BETTER_AUTH_URL matches actual Worker URL
• TRUSTED_ORIGINS includes all valid URLs
• Google OAuth redirect URI includes production URL
• Remote database migrated (pnpm db:migrate:remote)
• No vite-flare-starter references in config files
• Favicon replaced
• CLAUDE.md updated
• .dev.vars is NOT committed (check .gitignore)