DEV Community: Atman

Setup Better Auth with React Router & Cloudflare D1

Atman — Thu, 10 Jul 2025 12:54:57 +0000

This document outlines the steps to set up better-auth for authentication in a React Router project running on Cloudflare Workers with D1 as the database.

1. Prerequisites

Before you begin, make sure you have the following ready:

A Cloudflare account with a D1 database configured.
A GitHub OAuth application.
A working setup of a full-stack app using React Router and Cloudflare Workers, based on this boilerplate.

This guide assumes that your project is already set up with React Router and deployed on Cloudflare Workers, following the steps in the article linked above.

2. Install Dependencies

First, you need to add the required packages for better-auth, its CLI, and its database dependencies.

npm install better-auth kysely kysely-d1
npm install -D @better-auth/cli

3. Environment Variables

Create a .env file for local development and a .dev.vars for wrangler. Configure your secrets in the Cloudflare dashboard for production. The following variables are required:

CLOUDFLARE_D1_ID: Your Cloudflare D1 Database ID.
BETTER_AUTH_SECRET: A long, random string for signing tokens. You can generate one with openssl rand -hex 32.
BETTER_AUTH_URL: The base URL of your application (e.g., http://localhost:5173 for local development).
OAUTH_GITHUB_CLIENT_ID: Your GitHub OAuth application's Client ID.
OAUTH_GITHUB_CLIENT_SECRET: Your GitHub OAuth application's Client Secret.

4. Configure Auth Helpers

Before generating the database schema, we need to configure the core authentication logic.

Server-side Auth

Create app/lib/auth/auth.server.ts to initialize better-auth on the server. It uses Kysely with the D1 dialect to communicate with the database.

// app/lib/auth/auth.server.ts
import type { BetterAuthOptions } from "better-auth";
import { betterAuth } from "better-auth";
import { CamelCasePlugin, Kysely } from "kysely";
import { D1Dialect } from "kysely-d1";
import type { AppLoadContext } from "react-router";

let authInstance: ReturnType<typeof betterAuth>;

// Note: This has been updated to export `createBetterAuth`
// to be used in the CLI config.
export function createBetterAuth(
  database: BetterAuthOptions["database"],
  env: {
    BETTER_AUTH_SECRET: string;
    OAUTH_GITHUB_CLIENT_ID: string;
    OAUTH_GITHUB_CLIENT_SECRET: string;
  },
) {
  if (!authInstance) {
    authInstance = betterAuth({
      database,
      emailAndPassword: {
        enabled: false,
      },
      secret: env.BETTER_AUTH_SECRET,
      socialProviders: {
        github: {
          clientId: env.OAUTH_GITHUB_CLIENT_ID,
          clientSecret: env.OAUTH_GITHUB_CLIENT_SECRET,
        },
      },
    });
  }

  return authInstance;
}


export function getAuth(ctx: AppLoadContext) {
  if (!authInstance) {
    authInstance = createBetterAuth(
      {
        db: new Kysely({
          dialect: new D1Dialect({
            database: ctx.cloudflare.env.DB,
          }),
          plugins: [
            new CamelCasePlugin(),
          ],
        }),
        type: "sqlite",
      },
      ctx.cloudflare.env,
    );
  }

  return authInstance;
}

Client-side Auth

Create app/lib/auth/auth-client.ts for client-side interactions.

// app/lib/auth/auth-client.ts
import { createAuthClient } from "better-auth/react";

let authClient: ReturnType<typeof createAuthClient>;

export function getAuthClient({ baseURL = "http://localhost:5173" }: { baseURL?: string }) {
  if (!authClient) {
    authClient = createAuthClient({
      baseURL,
    });
  }
  return authClient;
}

5. Create Auth Config for CLI

The @better-auth/cli needs a configuration file to generate the database schema. Create auth.ts in the project root. This file imports your server-side auth configuration.

// auth.ts
// This file is *ONLY* used by the CLI!
import { drizzleAdapter } from "better-auth/adapters/drizzle";
import { drizzle } from "drizzle-orm/better-sqlite3";

import { createBetterAuth } from "./app/lib/auth/auth.server";
import { schema } from "./database/schema";

const db = drizzle({ connection: { source: process.env.LOCAL_DB_PATH } });
const database = drizzleAdapter(db, {
  schema,
  provider: "sqlite",
  usePlural: false,
});

export const auth = createBetterAuth(database, {
  BETTER_AUTH_SECRET: process.env.BETTER_AUTH_SECRET,
  OAUTH_GITHUB_CLIENT_ID: process.env.OAUTH_GITHUB_CLIENT_ID,
  OAUTH_GITHUB_CLIENT_SECRET: process.env.OAUTH_OAUTH_GITHUB_CLIENT_SECRET,
} as {
  BETTER_AUTH_SECRET: string;
  OAUTH_GITHUB_CLIENT_ID: string;
  OAUTH_GITHUB_CLIENT_SECRET: string;
});

6. Database Schema Generation

Instead of writing the schema manually, we use the CLI to generate it.

Add Generation Script

Add the auth:db:generate script to your package.json. This script finds the local D1 database file and uses it to generate the schema.

// package.json
{
  "scripts": {
    "auth:db:generate": "LOCAL_DB_PATH=$(find .wrangler/state/v3/d1/miniflare-D1DatabaseObject -type f -name '*.sqlite' -print -quit) npx env-cmd -f .dev.vars -- npx @better-auth/cli generate --output=\"database/auth-schema.ts\" --y && biome format database/auth-schema.ts --write"
  }
}

Generate and Apply Migrations

Now, run the scripts to generate the auth schema and then the Drizzle migration.

# 1. Generate the auth schema from your config
npm run auth:db:generate

# 2. Generate the Drizzle migration file
# "db:generate": "dotenv -- drizzle-kit generate"
npm run db:generate

# 3. Apply migration to your local database
# "db:migrate": "wrangler d1 migrations apply --local DB"
npm run db:migrate

# 4. Apply migration to your remote D1 database
# "db:migrate-production": "dotenv -- drizzle-kit migrate"
npm run db:migrate-production

After running auth:db:generate, the file database/auth-schema.ts will be created. Then, drizzle-kit will generate a migration file based on this schema.

7. Create API Route

better-auth handles various authentication flows (login, logout, callbacks) through a single API route. Create a splat route at app/routes/api.auth.$.ts.

// app/routes/api.auth.$.ts
import { getAuth } from "~/lib/auth/auth.server";
import type { Route } from "./+types/route";

export async function loader({ context, request }: Route.LoaderArgs) {
  const auth = getAuth(context);
  return auth.handler(request);
}

export async function action({ context, request }: Route.ActionArgs) {
  const auth = getAuth(context);
  return auth.handler(request);
}

8. Integrate into UI

Finally, use the auth helpers in your UI components. Here is an example of a login page at app/routes/_.demo.auth/route.tsx:

// app/routes/_.demo.auth/route.tsx
import { getAuthClient } from "~/lib/auth/auth-client";
import { getAuth } from "~/lib/auth/auth.server";
import type { Route } from './+types/route';

export async function loader({ context, request }: Route.LoaderArgs) {
  const auth = getAuth(context);
  const session = await auth.api.getSession({ headers: request.headers });

  return {
    baseURL: context.cloudflare.env.BETTER_AUTH_URL,
    user: session?.user,
  };
}

export default function DemoAuth({ loaderData }: Route.ComponentProps) {
  const { signIn } = getAuthClient({ baseURL: loaderData.baseURL });

  const signInGitHub = async () => {
    await signIn.social({
      provider: "github",
    });
  };

  return (
    <div>
      <h1>Better Auth Example</h1>
      {loaderData.user ? (
        <div>
          <pre>{JSON.stringify(loaderData.user, null, 2)}</pre>
        </div>
      ) : (
        <button onClick={() => signInGitHub()}>
          Login with GitHub
        </button>
      )}
    </div>
  );
}

This completes the setup of better-auth in your application.

From Zero to Deployed: A Step-by-Step Guide to Building a Full-Stack App with React Router and Cloudflare

Atman — Thu, 10 Jul 2025 12:49:51 +0000

Building a modern full-stack application involves juggling many moving parts: client-side rendering, server logic, database management, and deployment. This guide will walk you through creating a robust boilerplate using a powerful stack: React Router for routing, Cloudflare for infrastructure (including the D1 database), and Drizzle as our ORM.

By the end of this tutorial, you'll have a solid foundation for your next project, complete with a supercharged development environment featuring Biome, Vitest, and Husky.

Prerequisites

Before we begin, make sure you have the following installed:

Node.js (v18 or later)
npm
A Cloudflare account

Step 1: Project Initialization

We'll start by creating a new project using the official React Router template for Cloudflare D1. This gives us a great starting point with all the necessary configurations.

Open your terminal and run the following command:

npx create-react-router@latest react-router-cloudflare-boilerplate --template remix-run/react-router-templates/cloudflare-d1

This command scaffolds a new project in a directory named react-router-cloudflare-boilerplate.

Step 2: Setting Up Cloudflare D1

Next, let's set up our database on Cloudflare. We'll use D1, Cloudflare's native serverless SQL database.

Create the D1 Database

Run this command to create a new D1 database. Feel free to replace d1-app-test-db with your preferred name.

npx wrangler d1 create d1-app-test-db

Upon successful creation, you'll get a confirmation message with the binding information.

✅ Successfully created DB 'd1-app-test-db' in region APAC

Created your new D1 database.
{
  "d1_databases": [
    {
      "binding": "DB",
      "database_name": "d1-app-test-db",
      "database_id": "***************"
    }
  ]
}

Configure Wrangler

Now, open wrangler.jsonc in your project and add the d1_databases block you received from the previous command. This tells Wrangler how to connect to your D1 database.

{
  // ... other configurations
  "d1_databases": [
    {
      "binding": "DB",
      "database_name": "d1-app-test-db",
      "database_id": "***************",
      "migrations_dir": "drizzle"
    }
  ]
}

Set Up Environment Variables

For Drizzle to communicate with your D1 database from your local machine (for production migrations), you need to set up some environment variables. Create a .env file in your project root.

CLOUDFLARE_D1_ID="<your-database-id>"
CLOUDFLARE_ACCOUNT_ID="<your-account-id>"
CLOUDFLARE_TOKEN="<your-api-token>"

CLOUDFLARE_D1_ID: The database_id from the previous step.
CLOUDFLARE_ACCOUNT_ID: Find this on your Cloudflare dashboard under Workers & Pages.
CLOUDFLARE_TOKEN: Create a new API token from your Cloudflare dashboard > Manage Account > API Tokens. Use the "Create Custom Token" option with "Account > D1 > Edit" permissions.

Configure Drizzle

Finally, let's tell Drizzle how to connect to our D1 database for production migrations. Update drizzle.config.ts with your environment variables.

import type { Config } from "drizzle-kit";

export default {
  out: "./drizzle",
  schema: "./database/schema.ts",
  dialect: "sqlite",
  driver: "d1-http",
  dbCredentials: {
    databaseId: process.env.CLOUDFLARE_D1_ID!,
    accountId: process.env.CLOUDFLARE_ACCOUNT_ID!,
    token: process.env.CLOUDFLARE_TOKEN!,
  },
} satisfies Config;

Step 3: Database Migration and Deployment

With our configuration in place, we can now migrate our schema and deploy the application.

Run Production Migration

This command applies your schema (database/schema.ts) to the production D1 database.

npm run db:migrate-production

Deploy to Production

Deploy your application to Cloudflare Pages.

npm run deploy

Once deployed, you can visit the URL and interact with your live application. You can verify the data in your D1 database via the Cloudflare dashboard.

Step 4: Setting Up the Local Development Environment

For local development, Wrangler creates a local SQLite file to simulate D1.

Run Local Migration

Apply the schema to your local database.

npm run db:migrate

This creates a .sqlite file inside the .wrangler/ directory, allowing you to develop offline.

Start the Dev Server

Launch the development server with Hot Module Replacement (HMR).

npm run dev

Step 5: Enhancing the Development Environment

Let's add some modern tooling to improve code quality and development experience.

Biome for Linting and Formatting

Install Biome, an all-in-one tool for linting, formatting, and more.

npm install --save-dev --save-exact @biomejs/biome
npx @biomejs/biome init

You can customize the generated biome.json to fit your needs.

Vitest for Testing

Install Vitest, a fast and modern testing framework.

npm i -D vitest

To enable global imports for tests, modify vite.config.ts and tsconfig.cloudflare.json.

// ...
export default defineConfig(({ mode }) => ({
  // ...
  test: {
    globals: true,
    setupFiles: ['./test/setup.ts'],    
  },
}));

{
  "compilerOptions": {
    // ...
    "types": [
      // ...
      "vitest/globals"
    ],
  }
}

Create an empty test/setup.ts file, which you can use for test-wide setup later.

File-based Routing

Install @react-router/fs-routes to enable conventional file-based routing.

npm i @react-router/fs-routes

Update app/routes.ts to use it:

import type { RouteConfig } from "@react-router/dev/routes";
import { flatRoutes } from "@react-router/fs-routes";

const routes: RouteConfig = flatRoutes();
export default routes;

shadcn/ui for Components

Initialize shadcn/ui to easily add beautiful and accessible components.

npx shadcn-ui@latest init

This command will guide you through the setup process. It may ask you to configure path aliases in tsconfig.json.

Husky for Pre-commit Hooks

Install Husky to run scripts automatically before you commit.

npm i -D husky
npx husky init

Now, edit .husky/pre-commit to automatically lint and format your staged files.

npx biome check --staged --fix --no-errors-on-unmatched
git update-index --again

This ensures that your code is always clean before it gets committed.

Conclusion

Congratulations! You've successfully built and deployed a full-stack application with a powerful and modern tech stack. This boilerplate provides a solid foundation with a first-class development experience, allowing you to focus on building features instead of wrestling with configuration.

You can find the source code for this project here: [Link to your GitHub repository]

Happy coding!