react-router-cloudflare-boilerplate

KO | EN

gitlite — search

#javascript #python #hacktoberfest #react #ai #typescript #llm #go #golang #android #machine-learning #rust #deep-learning #linux

react-router-cloudflare-boilerplate

★ 9 Open GitHub ↗

Full-stack boilerplate with React Router, Cloudflare, Drizzle ORM, Tailwind, and better-auth.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# React Router + Cloudflare Boilerplate

A starting point for full-stack React applications on Cloudflare: React Router
v8 with server-side rendering on Workers, D1 + Drizzle ORM for data, and
`better-auth` for OAuth sign-in.

## Stack

| Area | Choice |
|---|---|
| Framework | [React Router v8](https://reactrouter.com/) (framework mode, SSR) |
| Platform | [Cloudflare Workers](https://developers.cloudflare.com/workers/) + [D1](https://developers.cloudflare.com/d1/) |
| ORM | [Drizzle ORM](https://orm.drizzle.team/) |
| Auth | [better-auth](https://www.better-auth.com/) — GitHub and Google OAuth |
| Forms | [Conform](https://conform.guide/) + [Zod 4](https://zod.dev/) |
| UI | [Tailwind CSS v4](https://tailwindcss.com/), [shadcn/ui](https://ui.shadcn.com/), [Lucide](https://lucide.dev/) |
| Tooling | [Vite 8](https://vite.dev/), [Biome](https://biomejs.dev/) via [Ultracite](https://www.ultracite.ai/), [Vitest 4](https://vitest.dev/) |

Requires Node.js 22 or newer.

## Getting started

### 1. Install

```bash
npm install
```

npm 11 skips install scripts unless a package lists them, so `package.json`
carries an `allowScripts` block for `esbuild` and `workerd` — without it the
build fails on a missing binary. The keys are exact versions; after bumping
either dependency, run `npm approve-scripts --allow-scripts-pending` and commit
the updated block.

### 2. Environment variables

Two files are needed, both derived from `.env.example`. Wrangler reads
`.dev.vars`; Drizzle Kit reads `.env`.

```bash
cp .env.example .dev.vars
cp .env.example .env
```

For local development you only need `BETTER_AUTH_SECRET` (generate one with
`openssl rand -hex 32`) plus the OAuth client id/secret of whichever provider
you want to sign in with. The `CLOUDFLARE_*` values are only read by Drizzle
Kit's own `migrate`/`push`/`studio` commands, which this template does not
use — migrations go through wrangler.

### 3. Database

```bash
npm run db:migrate
```

This applies the committed migrations to a local D1 database managed by
Miniflare. `wrangler.jsonc` ships with placeholder D1 values, which are fine
locally — see [Deployment](#deployment) for real ones.

### 4. Run

```bash
npm run dev
```

The app is served at http://localhost:5173.

## Scripts

| Script | What it does |
|---|---|
| `dev` | Dev server with HMR (regenerates Worker types first) |
| `build` | Production build |
| `preview` | Serve the production build locally |
| `deploy` | Build and deploy to Cloudflare |
| `test` | Run the test suite once, inside workerd |
| `test:watch` | Same, in watch mode |
| `check` | Typecheck + Biome — the gate CI enforces |
| `biome:check` | Lint and format only |
| `cf-typegen` | Regenerate `worker-configuration.d.ts` from `wrangler.jsonc` |
| `db:generate` | Generate a migration from schema changes |
| `db:migrate` | Apply migrations to the local D1 database |
| `db:migrate-production` | Apply migrations to the remote D1 database |
| `auth:db:generate` | Regenerate `database/auth-schema.ts` from `auth.ts` |

## Project layout

```
app/
  components/       shared components (ui/ is shadcn-generated)
  lib/auth/         auth server and client helpers
  routes/           flat file-based routes
  root.tsx          document shell, providers, error boundary
database/           schema.ts (yours) + auth-schema.ts (generated)
drizzle/            generated SQL migrations — do not hand-edit
workers/app.ts      Worker entry; builds the request context
scripts/            maintenance scripts
test/               test suite, runs against a real D1 binding
.claude/rules/      area-specific notes for AI agents
```

## Database workflow

1. Edit `database/schema.ts`.
2. `npm run db:generate` — read the SQL it produces. SQLite cannot alter
   constraints in place, so Drizzle rewrites the whole table.
3. `npm run db:migrate` to apply locally, and commit the migration alongside the
   schema change.
4. `npm run db:migrate-production` when the change ships.

Both scripts run `wrangler d1 migrations apply`, so local and production agree
on what has been applied. `drizzle-kit migrate` keeps its own separate record
and would replay migrations wrangler has already run — do not mix the two.

`npm run db:generate` is interactive when a table disappears and another
appears in the same diff, because it cannot tell a rename from a drop and a
create. That happens on the first schema change of a new project, where the
sample `guestBook` table goes away as the real tables arrive: run it in a real
terminal, or delete `drizzle/` and generate one fresh baseline while nothing is
deployed yet.

`database/auth-schema.ts` is generated from the better-auth config, not written
by hand. After changing `auth.ts`, run `npm run auth:db:generate` and then
`npm run db:generate`.

## Authentication

`better-auth` is configured in `app/lib/auth/auth.server.ts`, which is the
single source of truth for both the Worker runtime and the schema-generation
CLI. Email/password sign-in is disabled; GitHub and Google OAuth are wired up.

| File | Role |
|---|---|
| `app/lib/auth/auth.server.ts` | `createBetterAuth` / `getAuth` |
| `app/lib/auth/auth-client.ts` | Browser-side client |
| `app/routes/api.auth.$/` | Callback and API routes |
| `auth.ts` | Used **only** by the schema-generation CLI |

Register the callback URL `http://localhost:5173/api/auth/callback/<provider>`
with your OAuth app for local development.

## Forms

Server-side validation uses Conform with Zod 4. Import from the version-specific
entry point — the package default still targets Zod 3:

```ts
import { parseWithZod } from "@conform-to/zod/v4";
```

`test/form-validation.test.ts` is a worked example. `app/components/conform/`
holds inputs pre-wired to Conform field metadata.

## Testing

Tests run inside workerd through `@cloudflare/vitest-pool-workers`, so the D1
binding is real and the schema is built by applying `drizzle/`:

```bash
npm run test
```

Because the database is real, a schema change without a matching migration
fails the suite.

## Deployment

### 1. Create a D1 database

```bash
npx wrangler d1 create <your-database-name>
```

### 2. Point `wrangler.jsonc` at it

Replace the placeholder `database_name` and `database_id`, and set `name` to
your Worker's name.

### 3. Apply migrations remotely

```bash
npm run db:migrate-production
```

This authenticates through `wrangler login`, so no API token is needed.

### 4. Set secrets and deploy

Production secrets are not read from `.dev.vars`:

```bash
npx wrangler secret put BETTER_AUTH_SECRET
npx wrangler secret put OAUTH_GITHUB_CLIENT_ID
# ...and the remaining OAUTH_* values

npm run deploy
```

Worker logs are available in the Cloudflare dashboard — observability is
enabled in `wrangler.jsonc`.

### 5. Continuous deployment (optional)

`.github/workflows/deploy.yml` deploys every push to `main`, but only once a
project opts in — it is inert until the repository variable `DEPLOY_ON_MAIN`
is set to `true`. Add the secrets `CLOUDFLARE_API_TOKEN` (Workers Scripts →
Edit, plus D1 → Read) and `CLOUDFLARE_ACCOUNT_ID`.

Migrations stay manual on purpose, so a table rewrite never runs unattended.
The workflow reads the remote migration state first and refuses to deploy while
the database is behind, which turns "I forgot to migrate" into a failed deploy
rather than a broken production app.

## Styling

Tailwind CSS v4 with shadcn/ui. Add components with:

```bash
npx shadcn@latest add <component-name>
```

Generated components land in `app/components/ui/`, which is excluded from
linting so upstream output stays untouched.

## Versioning

The template's own version stays in the `0.0.x` range and never reaches 1.0.
Only the patch component moves, via the manual **Version Bump** workflow — the
number tracks template updates, nothing more.

**After generating a project from this template**, take the number out of the
way so it cannot be mistaken for your app's version:

1. Set `version` to your own starting point (or `0.0.0`) in `package.json` and
   `package-lock.json`.
2. Empty `CHANGELOG.md` — the entries in it describe the template, not your app.

## Working with AI agents

`CLAUDE.md` covers project-wide commands and conventions. `.claude/rules/`
holds area-specific notes (Workers, Drizzle/D1, better-auth, routes, tests) that
load automatically when the matching files are touched.

---

Built with React Router and Cloudflare.

react-router-cloudflare-boilerplate

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README