Bezzie

1.0.1 verified Sat Apr 25 auth: no javascript

Bezzie is a BFF (Backend for Frontend) OAuth 2.0 authentication library for Cloudflare Workers, currently at v1.0.1 (April 2026). It implements BCP212 (OAuth for Browser-Based Apps) by keeping tokens server-side in Cloudflare KV and issuing session cookies to the frontend, preventing JWTs from ever reaching the browser. It integrates seamlessly with Hono (v4) and supports providers like Auth0, Google, and generic OIDC. Compared to alternatives (Duende BFF, @auth0/nextjs-auth0), Bezzie is framework-agnostic, runs on Cloudflare Workers' edge, and is TypeScript-first with ESM-only distribution. Active development with recent breaking changes in v1.0.0.

Common errors

error Cannot find module 'bezzie' ↓

cause Old version (pre-v0.1.5) had incorrect dist output path.

fix

Update to bezzie@^1.0.0: npm install bezzie@latest

error TypeError: cloudflareKVAdapter is not a function ↓

cause Importing from wrong subpath; adapter moved to main export in v1.0.0.

fix

Change import { cloudflareKVAdapter } from 'bezzie/adapters' to import { cloudflareKVAdapter } from 'bezzie'

error Error: Session adapter must be a function returning an object with get/set/destroy ↓

cause Passed an adapter instance instead of a factory function (v1.0.0+).

fix

Use factory functions: cloudflareKVAdapter(env.SESSION_KV) instead of new CloudflareKVAdapter(env.SESSION_KV)

error Cannot use import statement outside a module ↓

cause Project not configured for ESM.

fix

Add "type": "module" to package.json or rename file to .mjs

Warnings

breaking v1.0.0: adapters changed from class constructors to factory functions (e.g., MemoryAdapter → memoryAdapter). ↓

fix Replace `new MemoryAdapter()` with `memoryAdapter()`, `new RedisAdapter(client)` with `redisAdapter(client)`. `cloudflareKVAdapter(kv)` remains unchanged.

breaking v1.0.0: removed `providerHints`, `cloudflareKV`, and `Bezzie.cache`. The adapter configuration now uses a factory function pattern. ↓

fix Migrate to the new adapter factory functions (e.g., cloudflareKVAdapter(env.SESSION_KV)).

gotcha The library is ESM-only (no CommonJS support). Using `require('bezzie')` will throw. ↓

fix Use `import` syntax or set `"type": "module"` in package.json.

gotcha Peer dependency on Hono ^4.0.0. Will not work with Hono v3 or earlier. ↓

fix Upgrade Hono to v4: `npm install hono@^4.0.0`.

gotcha Session adapter must be provided. Using `memoryAdapter()` is fine for development but sessions are lost on worker restart. ↓

fix In production, use `cloudflareKVAdapter(env.SESSION_KV)` or a persistent adapter.

deprecated The internal route paths are customizable via `routes` config (v1.0.0+). Defaults may collide with existing routes. ↓

fix Use `routes: { login: '/signin', callback: '/cb', logout: '/signout' }` to avoid conflicts.

Install

npm install bezzie

yarn add bezzie

pnpm add bezzie

Imports

createBezzie

wrong

const { createBezzie } = require('bezzie')

correct

import { createBezzie } from 'bezzie'

Bezzie is ESM-only; CommonJS require will fail.

providers
wrong
```
import * as providers from 'bezzie/providers'
```
correct
```
import { providers } from 'bezzie'
```
providers is a named export from the main package, not a submodule.
cloudflareKVAdapter
wrong
```
import { cloudflareKVAdapter } from 'bezzie/adapters'
```
correct
```
import { cloudflareKVAdapter } from 'bezzie'
```
Adapter functions are exported from the main entry point since v1.0.0; the previous subpath was removed.
Bezzie
wrong
```
import { Bezzie } from 'bezzie'
```
correct
```
import type { Bezzie } from 'bezzie'
```
Bezzie is a TypeScript interface, not a class. Use type import for compile-time use.
memoryAdapter
wrong
```
import { MemoryAdapter } from 'bezzie'
```
correct
```
import { memoryAdapter } from 'bezzie'
```
In v1.0.0, MemoryAdapter was renamed to memoryAdapter (factory function). Using the class name will cause a runtime error.

Quickstart

Sets up Bezzie with Auth0 provider and memory adapter, mounts auth routes, protects an API endpoint.

import { createBezzie, providers, cloudflareKVAdapter, memoryAdapter } from 'bezzie'
import { Hono } from 'hono'

type Env = {
  SESSION_KV: KVNamespace
  AUTH0_CLIENT_SECRET: string
}

const app = new Hono<{ Bindings: Env }>()

app.use('*', async (c, next) => {
  const auth = createBezzie({
    ...providers.auth0('your-tenant.auth0.com'),
    clientId: 'your-client-id',
    clientSecret: c.env.AUTH0_CLIENT_SECRET,
    adapter: memoryAdapter(),
    baseUrl: 'https://app.yourproject.com',
  })
  c.set('auth', auth)
  await next()
})

app.route('/auth', (c) => {
  const auth = c.get('auth')
  return auth.routes()
} as any)

app.get('/api/me', (c) => {
  const user = c.var.user
  const token = c.var.accessToken
  return c.json({ user, token })
})

export default app