Overview

Verge Kit is a toolkit for building web applications using Astro and the Cloudflare Workers ecosystem. Its pre-wired stack provides a reliable, understandable starting point with minimal boilerplate.

The toolkit covers database access, UI components, schema validation, tests, deployment configuration, and transactional email. It also supplies middleware, basic authentication flows, route protection, user roles, and permissions.

A boilerplate with consistent project structure and clear conventions helps LLM-based coding agents produce reliable output.

The Stack

• Astro - SSR with strict TypeScript and Cloudflare Workers adapter
• Cloudflare D1 - default SQLite database
• Drizzle - ORM, schema, migrations (w/ Drizzle Kit)
• Better Auth w/ admin plugin
• Tailwind - CSS utility classes
• bejamas/ui components (based on shadcn/ui)
• Lucide icons
• astro-favicons - simplified favicon generation
• React Email components and templates
• VK Core utilites & runtime helpers
• Zod schema validation
• Vitest, happy-dom, oxlint, and integrated npm verification scripts

The Boilerplate

• Lazy auth middleware with typed, request-scoped Astro.locals
• Basic authentication flows with requisite email notifications
• Public-by-default route authorization with opt-in protected pages and APIs
• CSRF origin checks through Astro config
• Custom 404 and 500 error pages
• Drizzle schema, migrations, and typed database client for the default D1 preset
• Configurable user roles and permissions for admin, moderator, user, and banned
• Transactional email providers for console output, Resend, Mailgun, and Cloudflare Email
• Verification and helper scripts exposed through npm scripts

Application Structure

./
├── src/
│   ├── actions/          # Astro Actions
│   ├── components/
│   │   ├── auth/         # shared authentication UI
│   │   └── ui/           # local bejamas/ui components
│   ├── config/           # app, auth, email, and database schema
│   ├── email/            # React Email templates
│   ├── layouts/          # base and authenticated page shells
│   ├── lib/              # shared application utilities
│   ├── pages/
│   │   ├── api/          # auth, health, and debug endpoints
│   │   └── auth/         # verification and password recovery
│   ├── styles/           # global Tailwind styles
│   ├── db.ts             # typed Drizzle D1 boundary
│   ├── env.d.ts          # Astro locals and Worker binding types
│   ├── middleware.ts     # request auth and route protection
│   └── runtime.ts        # request-scoped Cloudflare runtime access
├── cli/                  # operational scripts, including init-admin
├── migrations/           # generated SQL and Drizzle metadata
├── tests/                # auth, database, email, HTTP, and config tests
├── astro.config.mjs      # Astro and Cloudflare adapter configuration
├── drizzle.config.ts     # Drizzle Kit configuration
└── wrangler.jsonc        # Worker bindings and non-secret runtime values

Command Scripts

Run npm run verify before you merge or deploy a change.

npm run dev                 # local Astro dev server
npm run build               # production build
npm run preview             # local preview of the production build
npm run check               # Astro and TypeScript checks
npm run lint                # oxlint
npm run test                # Vitest
npm run test:watch          # Vitest watch mode
npm run verify              # runs 'check', 'lint', 'test', and 'build'
npm run email               # React Email template preview
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