Better Auth Cloudflare

https://github.com/zpg6/better-auth-cloudflare
Admin
Seamlessly integrate better-auth with Cloudflare Workers, D1, KV, and geolocation services....
Tokens:60,605
Snippets:437
Trust Score:7.5
License:MIT
Update:3 weeks ago
Show doc for...
Tokens:
Raw
### Navigate to example directory

Source: https://github.com/zpg6/better-auth-cloudflare/blob/main/examples/hono/README.md

Change into the example directory to begin setup.

```bash
cd examples/hono
```

--------------------------------

### Install dependencies with pnpm

Source: https://github.com/zpg6/better-auth-cloudflare/blob/main/examples/hono/README.md

Install the required dependencies for the example project.

```bash
pnpm install
```

--------------------------------

### Generate project interactively with CLI

Source: https://github.com/zpg6/better-auth-cloudflare/blob/main/README.md

Run this command to start the interactive setup, which asks questions and provides helpful defaults for generating a complete project on Cloudflare.

```bash
npx @better-auth-cloudflare/cli@latest generate
```

--------------------------------

### CLI usage examples for generate and migrate commands

Source: https://github.com/zpg6/better-auth-cloudflare/blob/main/_autodocs/api-reference/cli.md

Examples of using the @better-auth-cloudflare CLI for interactive generation, simple D1 app setup, Next.js with Hyperdrive, CI scaffolding, and migration workflows. The migrate command supports --migrate-target and --verbose arguments.

```bash
# Interactive
npx @better-auth-cloudflare/cli generate
```

```bash
# Simple D1 app with KV, applied and deployed
npx @better-auth-cloudflare/cli generate \
  --app-name=my-auth-app --template=hono --database=d1 \
  --kv=true --r2=false --apply-migrations=prod
```

```bash
# Next.js with Postgres via Hyperdrive (non-interactive requires the connection string)
npx @better-auth-cloudflare/cli generate --app-name=my-next-app --template=nextjs \
  --database=hyperdrive-postgres --hd-connection-string=postgres://user:pass@host:5432/db
```

```bash
# CI: scaffold without touching the Cloudflare account
npx @better-auth-cloudflare/cli generate --app-name=ci-app --skip-cloudflare-setup=true
```

```bash
# Migration workflow
npx @better-auth-cloudflare/cli migrate
npx @better-auth-cloudflare/cli migrate --migrate-target=dev
```

--------------------------------

### Basic client setup with cloudflareClient

Source: https://github.com/zpg6/better-auth-cloudflare/blob/main/_autodocs/api-reference/client.ts.md

Basic setup for the client plugin. Import cloudflareClient from "better-auth-cloudflare/client" and add it to the plugins array in createAuthClient. The baseURL is set to "/api/auth".

```ts
import { createAuthClient } from "better-auth/client";
import { cloudflareClient } from "better-auth-cloudflare/client";

const authClient = createAuthClient({
    baseURL: "/api/auth",
    plugins: [cloudflareClient()],
});

export default authClient;
```

--------------------------------

### Manual Wiring Example

Source: https://github.com/zpg6/better-auth-cloudflare/blob/main/_autodocs/api-reference/index.ts.md

Demonstrates how to initialize Better Auth with the KV storage adapter, suitable for versions 1.5 and 1.6.

```ts
import { createKVStorage } from "better-auth-cloudflare";

const auth = betterAuth({
    database: myDatabase,
    secondaryStorage: createKVStorage(env.KV),
    plugins: [cloudflare({ cf: request.cf })],
});
```

--------------------------------

### Install better-auth-cloudflare package

Source: https://github.com/zpg6/better-auth-cloudflare/blob/main/README.md

Install the package using your preferred package manager. The commands are equivalent alternatives for adding the dependency.

```bash
npm install better-auth-cloudflare
```

```bash
yarn add better-auth-cloudflare
```

```bash
pnpm add better-auth-cloudflare
```

```bash
bun add better-auth-cloudflare
```

--------------------------------

### Basic usage of withCloudflare

Source: https://github.com/zpg6/better-auth-cloudflare/blob/main/_autodocs/api-reference/index.ts.md

Example demonstrating how to initialize Better Auth with Cloudflare D1, KV, and automatic IP/geolocation tracking.

```ts
import { betterAuth } from "better-auth";
import { drizzle } from "drizzle-orm/d1";
import { withCloudflare } from "better-auth-cloudflare";

const auth = betterAuth({
    ...withCloudflare(
        {
            autoDetectIpAddress: true,
            geolocationTracking: true,
            cf: request.cf, // IncomingRequestCfProperties
            d1: { db: drizzle(env.DATABASE, { schema }), options: { usePlural: true } },
            kv: env.KV,
        },
        {
            emailAndPassword: { enabled: true },
            verification: { storeInDatabase: true }, // required with KV + Better Auth 1.7
            rateLimit: { enabled: true, storage: "database" },
        }
    ),
});
```

--------------------------------

### Run the development server

Source: https://github.com/zpg6/better-auth-cloudflare/blob/main/examples/opennextjs/README.md

Starts the development server for the Next.js application. The output can be viewed at http://localhost:3000.

```bash
npm run dev
# or
yarn dev
# or
pnpm dev
# or
bun dev
```

--------------------------------

### Skip Cloudflare setup and deployment

Source: https://github.com/zpg6/better-auth-cloudflare/blob/main/cli/README.md

Skips Cloudflare setup and deployment, useful for CI/CD. Only generates project files.

```bash
npx @better-auth-cloudflare/cli generate --app-name=ci-app --skip-cloudflare-setup=true
# Only generates project files, no Cloudflare resources or deployment
```

--------------------------------

### Usage example — same object without the helper (untyped hooks)

Source: https://github.com/zpg6/better-auth-cloudflare/blob/main/_autodocs/api-reference/types.ts.md

Contrasts with the typed example: without `createR2Config`, hook parameters are typed from `R2Config` directly, so `file.category` is `unknown` and `file` is `FileMetadata & Record<string, unknown>`. Use this when you don't need full hook typing.

```ts
const untyped = {
    bucket: env.R2_BUCKET,
    additionalFields: { category: { type: "string" } },
    hooks: {
        delete: {
            after: (file, ctx) => {
                // `file.category` is `unknown` here — hooks are typed from R2Config directly
                file; // FileMetadata & Record<string, unknown>
            },
        },
    },
} satisfies R2Config;
```

--------------------------------

### withCloudflare(cloudflareOptions, options)

Source: https://github.com/zpg6/better-auth-cloudflare/blob/main/_autodocs/api-reference/index.ts.md

Documentation for the withCloudflare function, including parameters, return value, thrown errors, and usage examples.

```APIDOC
## withCloudflare(cloudflareOptions, options)

### Description
Enhances `BetterAuthOptions` with Cloudflare-specific database, storage, IP-detection, and geolocation configuration. Do not also add `cloudflare()` to the `plugins` array — it is prepended automatically.

### Method
Function

### Signature
```ts
export const withCloudflare = <T extends BetterAuthOptions>(
    cloudFlareOptions: WithCloudflareOptions,
    options: T
): WithCloudflareAuth<T> => {
```

### Parameters
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `cloudFlareOptions` | `WithCloudflareOptions` | yes | — | Cloudflare options (`d1`, `d1Native`, `postgres`, `mysql`, `kv`, `cf`, `r2`, `autoDetectIpAddress`, `geolocationTracking`). |
| `options` | `T extends BetterAuthOptions` | yes | — | The base Better Auth options object to enhance. |

### Return Value
`WithCloudflareAuth<T>` — `Omit<T, "plugins"> & { plugins: [CloudflarePlugin, ...T["plugins"]] }` where `CloudflarePlugin = ReturnType<typeof cloudflare>`. The returned object:

| Key | Behavior |
| --- | --- |
| `database` | Set from `cloudFlareOptions.d1Native`, else `postgres` (adapter provider `"pg"`), else `mysql` (provider `"mysql"`), else `d1` (provider `"sqlite"`). When none provided, preserves `options.database`. |
| `secondaryStorage` | `createKVStorage(cloudFlareOptions.kv)` when `kv` is provided, else `options.secondaryStorage`. |
| `plugins` | `[createCloudflarePlugin(cloudFlareOptions, true), ...(options.plugins ?? [])]` — note the `validateStorage = true` flag. |
| `advanced` | When `autoDetectIpAddress` is enabled (default), `advanced.ipAddress.ipAddressHeaders` becomes `["cf-connecting-ip", "x-real-ip", ...existing]`. |
| `session` | When `geolocationTracking` is enabled (default), `session.storeSessionInDatabase` is forced to `true`. |

### Throws
| Condition | Error message |
| --- | --- |
| `autoDetectIpAddress` or `geolocationTracking` enabled (defaults) and `cf` is missing | `"Cloudflare context is required for geolocation or IP detection features. Be sure to pass the \`cf\` option to the withCloudflare function."` |
| More than one of `postgres`, `mysql`, `d1`, `d1Native` provided | `"Only one database configuration can be provided. Please provide only one of postgres, mysql, d1, or d1Native."` |
| Both `kv` and `options.secondaryStorage` provided | `"Configure either withCloudflare({ kv }) or authOptions.secondaryStorage, not both."` |

Additionally, because the plugin is created with `validateStorage = true`, the plugin's `init` runs `assertAtomicStorageCompatibility` — which can throw for Better Auth ≥ 1.7 configs where verification/rate limiting depend on atomic storage operations.

### Usage Example — Basic
```ts
import { betterAuth } from "better-auth";
import { drizzle } from "drizzle-orm/d1";
import { withCloudflare } from "better-auth-cloudflare";

const auth = betterAuth({
    ...withCloudflare(
        {
            autoDetectIpAddress: true,
            geolocationTracking: true,
            cf: request.cf, // IncomingRequestCfProperties
            d1: { db: drizzle(env.DATABASE, { schema }), options: { usePlural: true } },
            kv: env.KV,
        },
        {
            emailAndPassword: { enabled: true },
            verification: { storeInDatabase: true }, // required with KV + Better Auth 1.7
            rateLimit: { enabled: true, storage: "database" },
        }
    ),
});
```

### Usage Example — Per-request `cf` resolver and error handling
```ts
import { betterAuth } from "better-auth";
import { withCloudflare } from "better-auth-cloudflare";

// One auth instance serves many requests: resolve cf lazily per request
const auth = betterAuth({
    ...withCloudflare(
        {
            cf: () => getCloudflareContext().cf, // function form
            d1Native: env.DATABASE,
        },
        { emailAndPassword: { enabled: true } }
    ),
});

// Startup validation:
try {
    const bad = withCloudflare({ autoDetectIpAddress: true }, {}); // throws: cf missing
} catch (err) {
    console.error(err instanceof Error ? err.message : err);
    // "Cloudflare context is required for geolocation or IP detection features..."
}
```
```

--------------------------------

### Usage example — typed hooks with createR2Config

Source: https://github.com/zpg6/better-auth-cloudflare/blob/main/_autodocs/api-reference/types.ts.md

Shows how to use `createR2Config` to get fully typed hook callbacks. The `file` parameter in `after` hooks has typed `category` and `priority` fields. Returning `null` from a `before` hook blocks the operation (upload, download, or list).

```ts
import { createR2Config } from "better-auth-cloudflare";

const r2Config = createR2Config({
    bucket: env.R2_BUCKET,
    maxFileSize: 10 * 1024 * 1024,
    additionalFields: {
        category: { type: "string" },
        isPublic: { type: "boolean" },
        priority: { type: "number" },
    },
    hooks: {
        upload: {
            before: (file, ctx) => {
                if (file.metadata.category === "restricted") return null; // blocks upload
            },
            after: (file, ctx) => {
                file.category; // string — fully typed
                file.priority; // number — fully typed
            },
        },
        download: {
            before: (file, ctx) => {
                if (!file.isPublic && file.userId !== ctx.session?.userId) return null; // blocks download
            },
        },
        list: {
            before: (userId, ctx) => {
                if (!userHasPermission(userId, "list_files")) return null; // blocks listing
            },
        },
    },
});
```

--------------------------------

### Check version and get help

Source: https://github.com/zpg6/better-auth-cloudflare/blob/main/cli/README.md

Check the CLI version and display help. The first three commands show the version in different formats, and the last command shows help with version information.

```bash
npx @better-auth-cloudflare/cli --version    # Show version
npx @better-auth-cloudflare/cli -v           # Show version (short)
npx @better-auth-cloudflare/cli version      # Show version (command)
npx @better-auth-cloudflare/cli              # Show help with version
```

--------------------------------

### Usage example for createFileValidator

Source: https://github.com/zpg6/better-auth-cloudflare/blob/main/_autodocs/api-reference/r2.ts.md

Example of creating a validator with a bucket, maxFileSize, and allowedTypes, then using validateFile and validateMetadata. Shows error handling with v.code and v.error.

```typescript
import { createFileValidator, type R2Config } from "better-auth-cloudflare";

const validator = createFileValidator({
    bucket: env.R2_BUCKET,
    maxFileSize: 1024 * 1024,
    allowedTypes: [".jpg", ".png"],
});

const v = validator.validateFile(someFile);
if (!v.success) {
    console.log(v.code, v.error); // e.g. "INVALID_FILE_TYPE" "File type not supported..."
}

const m = validator.validateMetadata({ category: "documents" });
if (m.success && m.data) {
    // validated metadata object (only known fields)
}
```

--------------------------------

### Direct usage of createR2Storage

Source: https://github.com/zpg6/better-auth-cloudflare/blob/main/_autodocs/api-reference/r2.ts.md

Direct usage example of createR2Storage. It creates storage with a bucket and allowedTypes, then uploads a file with custom metadata. The r2Key is logged, and errors are caught and printed.

```ts
import { createR2Storage } from "better-auth-cloudflare";

const storage = createR2Storage(
    { bucket: env.R2_BUCKET, allowedTypes: [".pdf"] },
    ({ model }) => `${model}-${crypto.randomUUID()}`
);

try {
    const meta = await storage.uploadFile(file, file.name, "user_123", authContext, {
        category: "contracts",
    });
    console.log(meta.r2Key); // user-files/user_123/<id>-<sanitized-name>
} catch (err) {
    console.error(err instanceof Error ? err.message : err); // e.g. "File type not supported..."
}
```

--------------------------------

### Set environment variables and authenticate Wrangler

Source: https://github.com/zpg6/better-auth-cloudflare/blob/main/cli/tests/integration/README.md

Required before running integration tests. Sets CLOUDFLARE_ACCOUNT_ID and DATABASE_URL (a cloud-hosted PostgreSQL connection string), installs Wrangler globally, and logs in.

```bash
# Required environment variables
export CLOUDFLARE_ACCOUNT_ID="your-cloudflare-account-id"
export DATABASE_URL="postgresql://user:password@host:port/database?sslmode=require"

# Install and authenticate Wrangler CLI
npm install -g wrangler
wrangler auth login
```

--------------------------------

### Generate project non-interactively with arguments

Source: https://github.com/zpg6/better-auth-cloudflare/blob/main/cli/README.md

Generate a simple D1 app with KV in non-interactive mode. The example uses a Hono template, enables KV, disables R2, and applies migrations to the dev environment.

```bash
# Simple D1 app with KV (ready to run)
npx @better-auth-cloudflare/cli generate \
  --app-name=my-auth-app \
  --template=hono \
  --database=d1 \
  --kv=true \
  --r2=false \
  --apply-migrations=dev
```

--------------------------------

### Inferred file-management actions (list, download, delete, get)

Source: https://github.com/zpg6/better-auth-cloudflare/blob/main/_autodocs/api-reference/client.ts.md

Demonstrates the inferred file-management actions: files.list with pagination, files.download returning a raw Response, files.delete, and files.get for metadata. These methods are inferred by Better Auth from the server plugin's endpoints.

```ts
import authClient from "@/lib/authClient";

// List with pagination
const listResult = await authClient.files.list({ limit: 20, cursor: undefined });
if (listResult.data) {
    const { files, nextCursor, hasMore } = listResult.data;
}

// Download (result.data is the raw Response)
const downloadResult = await authClient.files.download({ fileId: "file_1" });
if (downloadResult.data) {
    const blob = downloadResult.data instanceof Response ? await downloadResult.data.blob() : downloadResult.data;
}

// Delete and metadata lookup
await authClient.files.delete({ fileId: "file_1" });
const meta = await authClient.files.get({ fileId: "file_1" });
```

--------------------------------

### Generate project non-interactively with CLI

Source: https://github.com/zpg6/better-auth-cloudflare/blob/main/README.md

Use this command to generate a project without prompts, specifying the app name, template, database, and resources. This example creates a simple D1 app with KV and fully deploys to Cloudflare.

```bash
# Simple D1 app with KV (fully deployed to Cloudflare)
npx @better-auth-cloudflare/cli@latest generate \
  --app-name=my-auth-app \
  --template=hono \
  --database=d1 \
  --kv=true \
  --r2=false \
  --apply-migrations=prod
```

--------------------------------

### Direct call usage example

Source: https://github.com/zpg6/better-auth-cloudflare/blob/main/_autodocs/api-reference/schema.ts.md

Shows how to call the `schema` function directly with geolocation tracking enabled and an R2 bucket with additional fields. Comments illustrate the resulting field definitions for the session and userFile models.

```typescript
import { schema } from "better-auth-cloudflare";

const dbSchema = schema({
    geolocationTracking: true,
    r2: {
        bucket: {} as any, // bucket only affects runtime, not schema
        additionalFields: { category: { type: "string", required: false } },
    },
});

// dbSchema.session.fields.city        -> { type: "string", required: false, input: false }
// dbSchema.userFile.fields.category   -> { type: "string", required: false }
// dbSchema.userFile.fields.r2Key      -> { type: "string", required: true, input: false }
```

--------------------------------

### GET /cloudflare/geolocation - Example Response Body

Source: https://github.com/zpg6/better-auth-cloudflare/blob/main/_autodocs/endpoints.md

Example response body for a successful 200 OK request to the geolocation endpoint. Shows the normalized CloudflareGeolocation fields, each as a string or undefined. The example includes 'Europe/Berlin' timezone and 'FRA' colo.

```json
{
  "timezone": "Europe/Berlin",
  "city": "Berlin",
  "country": "DE",
  "region": "Berlin",
  "regionCode": "BE",
  "colo": "FRA",
  "latitude": "52.52437",
  "longitude": "13.41053"
}
```

--------------------------------

### GET /files/list 200 OK response

Source: https://github.com/zpg6/better-auth-cloudflare/blob/main/_autodocs/endpoints.md

Example response body for the GET /files/list endpoint. Shows the files array, nextCursor, and hasMore fields. nextCursor is the last returned file's id when hasMore is true, otherwise null.

```json
{
  "files": [ { "id": "...", "userId": "...", "filename": "...", "originalName": "...", "contentType": "...", "size": 123, "r2Key": "...", "uploadedAt": "..." } ],
  "nextCursor": "userFile_xxx",
  "hasMore": true
}
```

--------------------------------

### Generate and deploy in one command

Source: https://github.com/zpg6/better-auth-cloudflare/blob/main/cli/README.md

Default behavior: creates resources, runs migrations, and deploys automatically.

```bash
npx @better-auth-cloudflare/cli generate --app-name=my-app
# Creates resources, runs migrations, and deploys automatically
```

--------------------------------

### Better Auth API route handler for Next.js App Router

Source: https://github.com/zpg6/better-auth-cloudflare/blob/main/README.md

Example of setting up API routes for Better Auth in a Next.js App Router project. Handles POST and GET requests by initializing auth and delegating to its handler. Adjust the import path to your auth/index.ts file.

```typescript
// Example: src/app/api/auth/[...all]/route.ts
// Adjust the path based on your project structure (e.g., Next.js App Router)

import { initAuth } from "@/auth"; // Adjust path to your auth/index.ts

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);
}

// You can also add handlers for PUT, DELETE, PATCH if needed by your auth flows
```

--------------------------------

### Run integration, unit, and all tests

Source: https://github.com/zpg6/better-auth-cloudflare/blob/main/cli/tests/integration/README.md

Commands to run the test suites: integration tests, unit tests, or all tests. Use bun as the package manager.

```bash
# All integration tests
bun run test:integration

# Unit tests only
bun run test:unit

# All tests
bun run test
```

--------------------------------

### Wrangler configuration with all binding types

Source: https://github.com/zpg6/better-auth-cloudflare/blob/main/docs/configuration.md

Complete Wrangler configuration example showing all supported binding types: D1, KV, R2, Hyperdrive (commented out), and vars. Includes observability and smart placement settings. Use only the bindings you need; create each resource with the commented wrangler commands.

```toml
name = "my-auth-app"
main = "src/index.ts"
compatibility_date = "2025-04-01"
compatibility_flags = ["nodejs_compat"]

[observability]
enabled = true

[placement]
mode = "smart"

# D1 — Create with: wrangler d1 create my-auth-db
[[d1_databases]]
binding = "DATABASE"
database_name = "my-auth-db"
database_id = "<your-database-id>"
migrations_dir = "drizzle"

# KV — Create with: wrangler kv namespace create KV
[[kv_namespaces]]
binding = "KV"
id = "<your-kv-namespace-id>"

# R2 (optional) — Create with: wrangler r2 bucket create my-files
[[r2_buckets]]
binding = "R2_BUCKET"
bucket_name = "my-files"

# Hyperdrive (optional) — Create with: wrangler hyperdrive create my-hd --connection-string="..."
# [[hyperdrive]]
# binding = "HYPERDRIVE"
# id = "<your-hyperdrive-id>"

[vars]
BETTER_AUTH_URL = "https://your-app.example.com"
BETTER_AUTH_TRUSTED_ORIGINS = "https://your-app.example.com"
```

--------------------------------

### Apply database migrations

Source: https://github.com/zpg6/better-auth-cloudflare/blob/main/examples/hono/README.md

Run the production database migration script.

```bash
pnpm run db:migrate:prod
```

--------------------------------

### Usage example for ValidationResult helpers

Source: https://github.com/zpg6/better-auth-cloudflare/blob/main/_autodocs/api-reference/r2.ts.md

Shows how to use the `success` and `error` helpers with a custom validation function. The example returns an error with code `FILE_TOO_LARGE` when the input exceeds 1024 bytes, and logs the error code and message when validation fails.

```ts
import { success, error, type ValidationResult } from "better-auth-cloudflare";

function checkSize(bytes: number): ValidationResult<number> {
    if (bytes > 1024) return error("Too large", "FILE_TOO_LARGE");
    return success(bytes);
}

const r = checkSize(2048);
if (!r.success) {
    console.log(r.code, r.error); // "FILE_TOO_LARGE" "Too large"
}
```

--------------------------------

### POST /files/delete success response

Source: https://github.com/zpg6/better-auth-cloudflare/blob/main/_autodocs/endpoints.md

Example response body returned by the POST /files/delete endpoint on success.

```json
{ "message": "File deleted successfully", "fileId": "userFile_xxx" }
```

--------------------------------

### GET /files/list

Source: https://github.com/zpg6/better-auth-cloudflare/blob/main/_autodocs/endpoints.md

Lists files stored in Cloudflare R2. This endpoint is only mounted when the `r2` feature is configured.

```APIDOC
## GET /files/list

### Description
Lists files stored in Cloudflare R2. This endpoint is only mounted when the `r2` feature is configured.

### Method
GET

### Endpoint
`/api/auth/files/list`

### Parameters
No parameters are documented in the source.

### Response
No response schema is documented in the source.
```

--------------------------------

### GET /files/list

Source: https://github.com/zpg6/better-auth-cloudflare/blob/main/docs/r2.md

Lists the user's files with pagination, returning file objects and pagination metadata.

```APIDOC
## GET /files/list

### Description
List the user's files with pagination support.

### Method
GET

### Endpoint
/files/list

### Parameters
#### Query Parameters
- **limit** (number) - Optional - Maximum number of files to return.
- **cursor** (string) - Optional - Pagination cursor for fetching the next page.

### Response
#### Success Response (200)
- **files** (array of File) - The list of files.
- **nextCursor** (string or null) - Cursor for the next page, or null if no more pages.
- **hasMore** (boolean) - Indicates whether more files are available.

#### Response Example
{
  "files": [],
  "nextCursor": null,
  "hasMore": false
}

```

--------------------------------

### Initialize Better Auth Client with Cloudflare Plugin

Source: https://github.com/zpg6/better-auth-cloudflare/blob/main/README.md

Sets up the Better Auth client with the Cloudflare plugin for front-end use. Includes geolocation and R2 file features if configured.

```typescript
// Example: src/lib/authClient.ts or similar client-side setup file

import { createAuthClient } from "better-auth/client";
import { cloudflareClient } from "better-auth-cloudflare/client";

const authClient = createAuthClient({
    plugins: [cloudflareClient()], // includes geolocation and R2 file features (if configured)
});

export default authClient;
```

--------------------------------

### withCloudflare(cloudflareOptions, options)

Source: https://github.com/zpg6/better-auth-cloudflare/blob/main/_autodocs/api-reference/index.ts.md

Documentation for the withCloudflare wrapper function.

```APIDOC
## withCloudflare(cloudflareOptions, options)

### Description
Creates a Better Auth plugin with stricter validation for Cloudflare environments.

### Method
function

### Signature
```ts
export const withCloudflare = (cloudflareOptions: CloudflarePluginOptions, options: BetterAuthOptions) => BetterAuthPlugin;
```

### Parameters
- `cloudflareOptions` (CloudflarePluginOptions) - Required - Plugin configuration.
- `options` (BetterAuthOptions) - Required - Better Auth options.

### Return Value
A BetterAuthPlugin that includes atomic storage compatibility validation and stricter behavior (e.g., throws if cf is missing).
```

--------------------------------

### Run migration workflow interactively

Source: https://github.com/zpg6/better-auth-cloudflare/blob/main/cli/README.md

Runs the migration workflow interactively.

```bash
npx @better-auth-cloudflare/cli migrate
```

--------------------------------

### GET /files/list

Source: https://github.com/zpg6/better-auth-cloudflare/blob/main/_autodocs/endpoints.md

Lists the current user's files with cursor pagination, most recent first. Requires session authentication.

```APIDOC
## GET /files/list

### Description
Lists the current user's files with cursor pagination, most recent first.

### Method
GET

### Endpoint
/files/list

### Parameters
#### Query Parameters
- **limit** (number) - Optional - Page size, clamped to max `100` (actual fetch is `min(limit, 100) + 1` to detect `hasMore`). Default: `50`.
- **cursor** (string) - Optional - `FileMetadata.id` to resume after. Filtering is applied client-side on the fetched page.

### Response
#### Success Response (200)
- **files** (array) - List of file metadata objects.
- **nextCursor** (string) - Last returned file's `id` when `hasMore`, else `null`.
- **hasMore** (boolean) - Indicates if more files are available.

#### Response Example
```json
{
  "files": [ { "id": "...", "userId": "...", "filename": "...", "originalName": "...", "contentType": "...", "size": 123, "r2Key": "...", "uploadedAt": "..." } ],
  "nextCursor": "userFile_xxx",
  "hasMore": true
}
```

### Errors
| Status | Code | Message | Condition |
| --- | --- | --- | --- |
| `401` | `UNAUTHORIZED` | (session middleware default) | No session. |
| `500` | `INTERNAL_SERVER_ERROR` | `"Service temporarily unavailable. Please try again later"` | `validateAuthContext` failed. |
| `500` | `INTERNAL_SERVER_ERROR` | `"File storage is temporarily unavailable. Please try again later"` | R2 storage not initialized. |
| `500` | `INTERNAL_SERVER_ERROR` | `"Unable to load your files. Please refresh the page"` | Any DB query failure. |
```

--------------------------------

### R2 Server Configuration with withCloudflare

Source: https://github.com/zpg6/better-auth-cloudflare/blob/main/docs/r2.md

Configures the r2 option in the server setup. Includes bucket from Cloudflare context, maxFileSize, allowedTypes, additionalFields, and upload/download hooks. The upload.before hook blocks uploads for unauthenticated users (ctx.session === null returns null) and non-paid users. The download.before hook blocks download unless the file is public or belongs to the current user.

```typescript
import { withCloudflare } from "better-auth-cloudflare";

export const auth = betterAuth(
    withCloudflare(
        {
            r2: {
                bucket: getCloudflareContext().env.R2_BUCKET,
                maxFileSize: 2 * 1024 * 1024, // 2MB
                allowedTypes: [".jpg", ".jpeg", ".png", ".gif"],
                additionalFields: {
                    category: { type: "string", required: false },
                    isPublic: { type: "boolean", required: false },
                    description: { type: "string", required: false },
                },
                hooks: {
                    upload: {
                        before: async (file, ctx) => {
                            // Only allow authenticated users to upload files
                            if (ctx.session === null) {
                                return null; // Blocks upload
                            }

                            // Only allow paid users to upload files (for example)
                            const isPaidUser = (userId: string) => true; // example
                            if (isPaidUser(ctx.session.user.id) === false) {
                                return null; // Blocks upload
                            }

                            // Allow upload
                        },
                        after: async (file, ctx) => {
                            // Track your analytics (for example)
                            console.log("File uploaded:", file);
                        },
                    },
                    download: {
                        before: async (file, ctx) => {
                            // Only allow user to access their own files (by default all files are public)
                            if (file.isPublic === false && file.userId !== ctx.session?.user.id) {
                                return null; // Blocks download
                            }
                            // Allow download
                        },
                    },
                },
            },
            // ... other config
        },
        {
            // ... your auth config
        }
    )
);
```

--------------------------------

### Get File Metadata with authClient.files.get

Source: https://github.com/zpg6/better-auth-cloudflare/blob/main/docs/r2.md

Retrieves file metadata by ID using authClient.files.get(). Logs the metadata if the request succeeds.

```typescript
// Get file metadata by ID
const result = await authClient.files.get({ fileId });
if (result.data) {
    console.log("File metadata:", result.data);
}
```

--------------------------------

### cloudflareClient() and uploadFile

Source: https://github.com/zpg6/better-auth-cloudflare/blob/main/_autodocs/api-reference/client.ts.md

Documentation for the cloudflareClient() plugin and its uploadFile action, plus inferred file management actions.

```APIDOC
## cloudflareClient()

### Description
Creates a Better Auth client plugin for Cloudflare integration. It adds an `uploadFile` action and enables type inference for file management actions.

### Method
Function call

### Endpoint
N/A (client-side plugin factory)

### Parameters
None.

### Return Value
A `BetterAuthClientPlugin` object with the following properties:
- `id` (string) - Plugin identifier, must match the server plugin's `id`.
- `$InferServerPlugin` (object) - Type-level bridge for client-server type inference.
- `getActions($fetch)` (function) - Returns an object with the `uploadFile` action.

### Usage Example
```ts
import { createAuthClient } from "better-auth/client";
import { cloudflareClient } from "better-auth-cloudflare/client";

const authClient = createAuthClient({
    baseURL: "/api/auth",
    plugins: [cloudflareClient()],
});

export default authClient;
```

## uploadFile(file, metadata?)

### Description
Uploads a file by sending it directly as the request body with metadata in headers. This action is added by the `cloudflareClient()` plugin.

### Method
POST

### Endpoint
`/files/upload-raw`

### Parameters
#### Request Body
- `file` (File) - Required - The file to upload, sent as the raw request body.

#### Headers
- `x-filename` (string) - Required - The file's name, sanitized to ASCII.
- `x-file-metadata` (string) - Optional - JSON string of metadata, only set if metadata has keys.

### Request Example
```ts
const result = await authClient.uploadFile(file, {
    category: "documents",
    isPublic: false,
    description: "Important document",
});
```

### Response
#### Success Response
- `result.data` - The uploaded file data.

#### Error Response
- `result.error` - An error object with a `message` property.

### Notes
- Non-ASCII characters in filenames are replaced with `"?"` in headers to avoid Cloudflare Workers ByteString errors.

## Inferred File Management Actions

### Description
Better Auth infers additional file management actions from the server plugin's endpoints. These are available on the client as `authClient.files.*`.

### Methods
- `files.list({ limit, cursor })` - Lists files with pagination.
- `files.download({ fileId })` - Downloads a file, returns a raw `Response`.
- `files.delete({ fileId })` - Deletes a file.
- `files.get({ fileId })` - Gets file metadata.

### Usage Example
```ts
// List with pagination
const listResult = await authClient.files.list({ limit: 20, cursor: undefined });
if (listResult.data) {
    const { files, nextCursor, hasMore } = listResult.data;
}

// Download (result.data is the raw Response)
const downloadResult = await authClient.files.download({ fileId: "file_1" });
if (downloadResult.data) {
    const blob = downloadResult.data instanceof Response ? await downloadResult.data.blob() : downloadResult.data;
}

// Delete and metadata lookup
await authClient.files.delete({ fileId: "file_1" });
const meta = await authClient.files.get({ fileId: "file_1" });
```
```
Tokens:
Raw