Verge Kit projects follow a small loop: configure runtime values, migrate D1, run server-first development locally, verify, then deploy through Cloudflare Workers.

1. Configure

Use src/config for source-level app defaults and auth policy. Use wrangler.jsonc for committed non-secret Worker runtime values:

{
  "vars": {
    "EMAIL_PROVIDER": "console",
  },
}

Use .dev.vars for local secrets and local-only overrides:

BETTER_AUTH_SECRET=your-local-secret
BETTER_AUTH_URL=http://localhost:4321

Use Wrangler secrets for deployed secrets.

2. Migrate

Apply migrations before testing auth or database-backed pages:

npm run db:migrate:local

After schema changes, generate a migration and apply it locally:

npm run db:generate
npm run db:migrate:local

3. Initialize

Create a verified local user with the admin role when the app needs an initial login:

npm run init:admin

The script writes directly to D1 through Wrangler and does not need the dev server to be running.

4. Develop

Start Astro in server mode:

npm run dev

Keep writes, auth, email, and validation on the server. Use Astro pages, API routes, Actions, middleware, and the local src/db and src/email modules before adding new app-specific abstractions.

5. Verify

Run the full verification command before merging or deploying:

npm run verify

Use narrower commands while iterating:

npm run check
npm run lint
npm run test
npm run build

For production, create the remote D1 database, set deployed secrets, apply remote migrations, optionally create a remote user with the admin role, then deploy through the project Cloudflare workflow.

Common Commands

npm run dev                 # local Astro dev server
npm run build               # production build
npm run check               # Astro and TypeScript checks
npm run lint                # oxlint
npm run test                # Vitest
npm run verify              # check, lint, tests, build
npm run db:generate         # generate Drizzle migrations
npm run db:studio           # open Drizzle Studio for D1 HTTP
npm run db:migrate:local    # apply D1 migrations locally
npm run db:migrate:remote   # apply D1 migrations remotely
npm run init:admin          # create a verified D1 user with the admin role

Workflow Overview