Vite Flare Starter

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 | `` 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=
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=
VITE_APP_NAME=
VITE_APP_ID=
VITE_TOKEN_PREFIX=_
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 `` 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 BETTERAUTHURL 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 ENABLEEMAILLOGIN |

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 TRUSTEDORIGINS | Set TRUSTEDORIGINS with all valid URLs | | "Not authorized" on deploy | Wrong accountid | Remove accountid 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 VITEAPPID | Set VITE_APP_ID=yourapp in .dev.vars | | Auth fails in production only | BETTERAUTHURL mismatch | Must match actual Worker URL exactly (https, no trailing slash) | | "redirecturimismatch" 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)

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: jezweb
• Source: jezweb/claude-skills
• License: MIT
• Homepage: https://jezweb.com.au

Install and usage instructions live in the source repository linked above.