Registry / auth-security / better-auth-cloudflare

better-auth-cloudflare

JSON →
library0.3.0jsnpmunverified

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.

npm install better-auth-cloudflare
INSTALL
IMPORT
SIG · BETTER-AUTH-CLOUDF
B
better-auth-cloudflare
auth-securityjavascriptv0.3.0
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

withCloudflare
import { withCloudflare } from 'better-auth-cloudflare';
const { withCloudflare } = require('better-auth-cloudflare');
This package is primarily designed for ESM environments, especially in Cloudflare Workers. CommonJS 'require' will result in an ERR_REQUIRE_ESM error.
CloudflareSession
import type { CloudflareSession } from 'better-auth-cloudflare';
import { CloudflareSession } from 'better-auth-cloudflare';
Import as a type only, 'CloudflareSession' is a TypeScript interface for session data, not a runtime value.
BetterAuthCloudflareOptions
import type { BetterAuthCloudflareOptions } from 'better-auth-cloudflare';
import { BetterAuthCloudflareOptions } from 'better-auth-cloudflare';
Import as a type only for configuring the Cloudflare integration options.

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.

import { withCloudflare } from 'better-auth-cloudflare'; import { BetterAuth } from 'better-auth'; import { Hono } from 'hono'; import { Env } from './env'; // Assume a types file for Cloudflare Bindings // Initialize the core BetterAuth instance const auth = new BetterAuth({ secret: process.env.AUTH_SECRET ?? 'super-secret-key-please-change', // ... other better-auth configuration like adapters, providers }); // Create a Hono app, assuming it's your Cloudflare Worker entry point const app = new Hono<{ Bindings: Env }>(); // Integrate BetterAuth with Cloudflare services using `withCloudflare` const cloudflareAuth = withCloudflare(auth, { // Use the D1Database binding directly (new in v0.3.0) d1Native: (env) => env.D1_DATABASE, // Optional: Cloudflare KV for secondary storage/caching kv: (env) => env.KV_STORAGE, // Optional: Cloudflare R2 for file storage r2: (env) => env.R2_BUCKET, // Cloudflare-specific configurations are passed here }); // Mount the better-auth routes to your Hono application app.route('/auth', cloudflareAuth.router); // Example route demonstrating session and geolocation access app.get('/', (c) => { const session = cloudflareAuth.getSession(c); const user = session?.user; const geolocation = session?.geolocation; const message = user ? `Hello ${user.name} from ${geolocation?.city}, ${geolocation?.country}!` : 'Hello, guest! Please log in.'; return c.text(message); }); // Export the Hono app for Cloudflare Workers export default app;
Debug
Known issues
breakingThe minimum peer dependency for `better-auth` has been raised from `^1.1.21` to `^1.5.0`.
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`.
affects: >=0.3.0
breakingA 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`.
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`.
affects: >=0.3.0
gotchaCloudflare 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.
fix
When configuring KV options, ensure any custom TTL values are 60 seconds (60000 milliseconds) or greater.
affects: >=0.2.8
gotchaR2 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.
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.
affects: <0.2.9
Errors
Common errors & fixes
ERR_REQUIRE_ESM
Attempting to use `better-auth-cloudflare` with CommonJS `require()` syntax in a Node.js or Cloudflare Worker environment that expects ES Modules.
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.
Failed to generate auth schema
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.
fix
Prefer `npm` for executing CLI commands. Use `npx better-auth-cloudflare@latest generate` instead of `bunx better-auth-cloudflare@latest generate`.
Upgrade
Version history
0.3.0latest on npm
Audit
Dependencies
better-authrequiredCore authentication library that this package extends and integrates with Cloudflare services.
@better-auth/drizzle-adapteroptionalRequired when using Drizzle-based database options (D1, Postgres, MySQL) since v0.3.0.
@cloudflare/workers-typesrequiredProvides TypeScript types for Cloudflare Worker environments, essential for development.
Agent activity
26 hits · last 30 days
node
22
OpenAI (training)
1
Resources
better-auth-cloudflare — npm install better-auth-cloudflare · libregistry