better-auth-cloudflare

When geolocationTracking is set to true within the withCloudflare configuration, the plugin automatically enriches user sessions with location data derived from Cloudflare's edge headers.

This data is available in the session and includes:

• timezone: User's timezone
• city: User's city
• country: User's country
• region: User's region/state
• regionCode: Region code
• colo: Cloudflare colo data center
• latitude: Latitude coordinates
• longitude: Longitude coordinates

If you prefer not to use Drizzle ORM, you can pass a D1 binding directly to withCloudflare using the d1Native key. This uses Better Auth's built-in Kysely D1 dialect.

Trade-offs:

• Pros: Smaller bundle size, simpler setup.
• Cons: No type-safe queries via Drizzle, manual SQL/CLI schema management required.

Example:

const auth = betterAuth({
    ...withCloudflare({
        d1Native: env.DATABASE, // D1Database binding from wrangler.toml
        kv: env.KV,
    }, {
        // auth options
    }),
});

import { betterAuth } from "better-auth";
import { withCloudflare } from "better-auth-cloudflare";

const auth = betterAuth({
    ...withCloudflare(
        {
            d1Native: env.DATABASE, 
            kv: env.KV,
        },
        {
            // your auth options...
        }
    ),
});

The withCloudflare wrapper returns a merged configuration where certain keys take precedence over your provided authOptions. You should omit these keys from your authOptions to avoid confusion:

• database: Set automatically from your d1, d1Native, postgres, or mysql option.
• secondaryStorage: Set to createKVStorage(kv) if kv is provided.
• plugins: The cloudflare() plugin is automatically prepended to your plugins array.
• advanced: Merges your options with IP detection headers if autoDetectIpAddress is enabled.
• session: Merges your options and forces storeSessionInDatabase: true if geolocationTracking is enabled.

Lifecycle hooks allow you to inject business logic at specific points in the file lifecycle. Returning null from a before hook will block the operation (upload, download, or delete).

Available hook categories:

• upload: Contains before and after hooks.
• download: Contains before and after hooks.
• delete: Contains before and after hooks.

const r2Config = {
    bucket: env.R2_BUCKET,
    hooks: {
        upload: {
            before: async (file, ctx) => { /* logic */ },
            after: async (file, ctx) => { /* logic */ },
        },
        download: {
            before: async (file, ctx) => { /* logic */ },
        },
        delete: {
            before: async (file, ctx) => { /* logic */ },
        },
    },
};

Install the package using your preferred package manager:

npm install better-auth-cloudflare
# or
yarn add better-auth-cloudflare
# or
pnpm add better-auth-cloudflare
# or
bun add better-auth-cloudflare

You must create API routes to handle authentication requests. The auth.handler(req) method processes the incoming request.

Example (Next.js App Router style):

import { initAuth } from "@/auth";

export async function POST(req: Request) {
    const auth = await initAuth();
    return auth.handler(req);
}

export async function GET(req: Request) {
    const auth = await initAuth();
    return auth.handler(req);
}

// Example: src/app/api/auth/[...all]/route.ts
import { initAuth } from "@/auth";

export async function POST(req: Request) {
    const auth = await initAuth();
    return auth.handler(req);
}

export async function GET(req: Request) {
    const auth = await initAuth();
    return auth.handler(req);
}

Use the generate command to create a complete Better Auth Cloudflare project. This command scaffolds Hono or Next.js (OpenNext.js) applications, sets up TypeScript configurations, package.json scripts, API routes, and database adapters. It also handles Cloudflare resource creation (D1, KV, R2, Hyperdrive) and runs initial migrations.

Interactive Mode: Run the command without arguments to be prompted for configuration:

npx @better-auth-cloudflare/cli generate

Non-interactive Mode: Pass arguments to automate the setup:

npx @better-auth-cloudflare/cli generate \
  --app-name=my-auth-app \
  --template=hono \
  --database=d1 \
  --kv=true \
  --r2=false \
  --apply-migrations=dev

npx @better-auth-cloudflare/cli generate --app-name=my-auth-app --template=hono --database=d1 --kv=true --r2=false --apply-migrations=dev

When you modify your authentication configuration, use the migrate command to streamline schema updates. It automatically detects your database configuration from wrangler.toml and performs the following workflow:

1. Generates the updated auth schema.
2. Creates Drizzle migrations.
3. Optionally applies the migrations.

Interactive Mode:

npx @better-auth-cloudflare/cli migrate

Non-interactive Mode:

npx @better-auth-cloudflare/cli migrate --migrate-target=dev

Supported Targets:

• D1 databases: Supports dev or remote migration targets.
• Hyperdrive databases: Displays an informational message (migrations are not applied via this command for Hyperdrive).
• Multiple databases: If multiple D1 databases are detected, you will be prompted to choose which one to migrate.

The Better Auth CLI can automatically generate the Drizzle schema required for authentication tables (users, sessions, etc.). This schema should be imported into your main Drizzle schema file to ensure all tables are managed together.

Command: npx @better-auth/cli@latest generate

Recommended usage with explicit paths: npx @better-auth/cli@latest generate --config src/auth/index.ts --output src/db/auth.schema.ts -y

Workflow:

1. Run the command to create src/db/auth.schema.ts.
2. Import authSchema into your main src/db/schema.ts.
3. Use Drizzle Kit to create and apply migrations to your database.