{"id":16598,"library":"better-auth-cloudflare","title":"better-auth-cloudflare","description":"better-auth-cloudflare is a plugin designed to seamlessly integrate the Better Auth library with the Cloudflare ecosystem, including Workers, D1, Hyperdrive, KV, R2, and geolocation services. It is currently at version 0.3.0 and actively maintained with a continuous release cadence, addressing new features and compatibility updates. This library differentiates itself by providing out-of-the-box support for Cloudflare's serverless offerings, allowing developers to leverage D1 (SQLite), Postgres, and MySQL (via Drizzle ORM or native D1), KV for session caching, and R2 for file storage. It also automatically enriches user sessions with Cloudflare's geolocation and IP detection data, offering a comprehensive solution for authentication in Cloudflare environments without extensive manual setup, making it ideal for Hono, OpenNextJS, and other Worker-compatible frameworks.","status":"active","version":"0.3.0","language":"javascript","source_language":"en","source_url":"https://github.com/zpg6/better-auth-cloudflare","tags":["javascript","better-auth","auth","plugin","cloudflare","workers","kv","d1","r2","typescript"],"install":[{"cmd":"npm install better-auth-cloudflare","lang":"bash","label":"npm"},{"cmd":"yarn add better-auth-cloudflare","lang":"bash","label":"yarn"},{"cmd":"pnpm add better-auth-cloudflare","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core authentication library that this package extends and integrates with Cloudflare services.","package":"better-auth","optional":false},{"reason":"Required when using Drizzle-based database options (D1, Postgres, MySQL) since v0.3.0.","package":"@better-auth/drizzle-adapter","optional":true},{"reason":"Provides TypeScript types for Cloudflare Worker environments, essential for development.","package":"@cloudflare/workers-types","optional":false}],"imports":[{"note":"This package is primarily designed for ESM environments, especially in Cloudflare Workers. CommonJS 'require' will result in an ERR_REQUIRE_ESM error.","wrong":"const { withCloudflare } = require('better-auth-cloudflare');","symbol":"withCloudflare","correct":"import { withCloudflare } from 'better-auth-cloudflare';"},{"note":"Import as a type only, 'CloudflareSession' is a TypeScript interface for session data, not a runtime value.","wrong":"import { CloudflareSession } from 'better-auth-cloudflare';","symbol":"CloudflareSession","correct":"import type { CloudflareSession } from 'better-auth-cloudflare';"},{"note":"Import as a type only for configuring the Cloudflare integration options.","wrong":"import { BetterAuthCloudflareOptions } from 'better-auth-cloudflare';","symbol":"BetterAuthCloudflareOptions","correct":"import type { BetterAuthCloudflareOptions } from 'better-auth-cloudflare';"}],"quickstart":{"code":"import { withCloudflare } from 'better-auth-cloudflare';\nimport { BetterAuth } from 'better-auth';\nimport { Hono } from 'hono';\nimport { Env } from './env'; // Assume a types file for Cloudflare Bindings\n\n// Initialize the core BetterAuth instance\nconst auth = new BetterAuth({\n    secret: process.env.AUTH_SECRET ?? 'super-secret-key-please-change',\n    // ... other better-auth configuration like adapters, providers\n});\n\n// Create a Hono app, assuming it's your Cloudflare Worker entry point\nconst app = new Hono<{ Bindings: Env }>();\n\n// Integrate BetterAuth with Cloudflare services using `withCloudflare`\nconst cloudflareAuth = withCloudflare(auth, {\n    // Use the D1Database binding directly (new in v0.3.0)\n    d1Native: (env) => env.D1_DATABASE,\n    // Optional: Cloudflare KV for secondary storage/caching\n    kv: (env) => env.KV_STORAGE,\n    // Optional: Cloudflare R2 for file storage\n    r2: (env) => env.R2_BUCKET,\n    // Cloudflare-specific configurations are passed here\n});\n\n// Mount the better-auth routes to your Hono application\napp.route('/auth', cloudflareAuth.router);\n\n// Example route demonstrating session and geolocation access\napp.get('/', (c) => {\n    const session = cloudflareAuth.getSession(c);\n    const user = session?.user;\n    const geolocation = session?.geolocation;\n\n    const message = user\n        ? `Hello ${user.name} from ${geolocation?.city}, ${geolocation?.country}!`\n        : 'Hello, guest! Please log in.';\n\n    return c.text(message);\n});\n\n// Export the Hono app for Cloudflare Workers\nexport default app;\n","lang":"typescript","description":"This example demonstrates how to integrate `better-auth-cloudflare` into a Cloudflare Worker using Hono, connecting to D1, KV, and R2 bindings, and accessing user session data including geolocation."},"warnings":[{"fix":"Ensure your `better-auth` installation is at version `^1.5.0` or higher. Run `npm install better-auth@^1.5.0` or `yarn add better-auth@^1.5.0`.","message":"The minimum peer dependency for `better-auth` has been raised from `^1.1.21` to `^1.5.0`.","severity":"breaking","affected_versions":">=0.3.0"},{"fix":"Install the new peer dependency: `npm install @better-auth/drizzle-adapter@^1.5.0` or `yarn add @better-auth/drizzle-adapter@^1.5.0`.","message":"A new peer dependency, `@better-auth/drizzle-adapter` (`^1.5.0`), is now required if you are using Drizzle-based database options (D1, Postgres, MySQL) with `better-auth-cloudflare`.","severity":"breaking","affected_versions":">=0.3.0"},{"fix":"When configuring KV options, ensure any custom TTL values are 60 seconds (60000 milliseconds) or greater.","message":"Cloudflare KV storage requires a minimum TTL (Time-To-Live) of 60 seconds for entries. Setting a TTL below this value will be clamped to 60 seconds or result in an error in some environments.","severity":"gotcha","affected_versions":">=0.2.8"},{"fix":"Ensure your R2 upload configurations explicitly pass `allowedMediaTypes` when calling upload functions, and that the client-side upload includes a correct and supported `Content-Type` header.","message":"R2 uploads might fail with a 415 error (Unsupported Media Type) if `allowedMediaTypes` are not correctly specified or if the client sends an unsupported `Content-Type` header.","severity":"gotcha","affected_versions":"<0.2.9"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Migrate your project to use ES Modules. Use `import` statements instead of `require()`. Ensure your `package.json` specifies `\"type\": \"module\"` or uses `.mjs` file extensions.","cause":"Attempting to use `better-auth-cloudflare` with CommonJS `require()` syntax in a Node.js or Cloudflare Worker environment that expects ES Modules.","error":"ERR_REQUIRE_ESM"},{"fix":"Prefer `npm` for executing CLI commands. Use `npx better-auth-cloudflare@latest generate` instead of `bunx better-auth-cloudflare@latest generate`.","cause":"This error can occur when using the `@better-auth/cli` commands (e.g., `npx better-auth-cloudflare@latest generate`) with `bunx` due to compatibility issues.","error":"Failed to generate auth schema"}],"ecosystem":"npm"}