Better Auth sur Cloudflare

Un service d’authentification léger en TypeScript, optimisé pour Cloudflare Workers

Présentation de la pile

🔥 Hono
Un framework web rapide et léger fondé sur les standards du Web.

🔒 Better Auth
Un framework d’authentification complet pour TypeScript.

🧩 Drizzle ORM
Un ORM léger et performant pour TypeScript, conçu pour faciliter le travail des développeurs.

🐘 Postgres avec Neon
Un service Postgres sans serveur optimisé pour le cloud.

Préparation

1. Installation

npm

# Hono
# > Select cloudflare-workers template
npm create hono

# Better Auth
npm install better-auth

# Drizzle ORM
npm install drizzle-orm
npm install --save-dev drizzle-kit

# Neon
npm install @neondatabase/serverless

pnpm

# Hono
# > Select cloudflare-workers template
pnpm create hono

# Better Auth
pnpm add better-auth

# Drizzle ORM
pnpm add drizzle-orm
pnpm add -D drizzle-kit

# Neon
pnpm add @neondatabase/serverless

yarn

# Hono
# > Select cloudflare-workers template
yarn create hono

# Better Auth
yarn add better-auth

# Drizzle ORM
yarn add drizzle-orm
yarn add --dev drizzle-kit

# Neon
yarn add @neondatabase/serverless

bun

# Hono
# > Select cloudflare-workers template
bun create hono

# Better Auth
bun add better-auth

# Drizzle ORM
bun add drizzle-orm
bun add -d drizzle-kit

# Neon
bun add @neondatabase/serverless

2. Variables d’environnement

Définissez les variables d’environnement suivantes pour connecter votre application à Better Auth et à Neon.

Consultez les guides officiels :

• Better Auth – Guide
• Neon – Guide

Fichiers nécessaires :

.dev.vars

# Used by Wrangler in local development
# In production, these should be set as Cloudflare Worker Secrets.

BETTER_AUTH_URL=
BETTER_AUTH_SECRET=
DATABASE_URL=

.env

# Used for local development and CLI tools such as:
#
# - Drizzle CLI
# - Better Auth CLI

BETTER_AUTH_URL=
BETTER_AUTH_SECRET=
DATABASE_URL=

3. Wrangler

Après avoir défini vos variables d’environnement, exécutez le script suivant pour générer les types de votre configuration Cloudflare Workers :

npm

npx wrangler types --env-interface CloudflareBindings
# OR
npm run cf-typegen

pnpm

pnpm wrangler types --env-interface CloudflareBindings
# OR
pnpm cf-typegen

yarn

yarn wrangler types --env-interface CloudflareBindings
# OR
yarn cf-typegen

bun

bunx wrangler types --env-interface CloudflareBindings
# OR
bun run cf-typegen

Vérifiez ensuite que votre fichier tsconfig.json inclut les types générés.

tsconfig.json

{
  "compilerOptions": {
    "types": ["worker-configuration.d.ts"]
  }
}

4. Drizzle

Pour utiliser la CLI Drizzle Kit, ajoutez le fichier de configuration Drizzle suivant à la racine de votre projet.

drizzle.config.ts

import { defineConfig } from 'drizzle-kit';

export default defineConfig({
  out: './drizzle',
  schema: './src/db/schema.ts',
  dialect: 'postgresql',
  dbCredentials: {
    url: process.env.DATABASE_URL!,
  },
});

Application

1. Instance Better Auth

Créez une instance Better Auth en utilisant les bindings Cloudflare Workers.

Les options de configuration disponibles sont nombreuses et dépassent largement le cadre de cet exemple. Consultez la documentation officielle et adaptez la configuration aux besoins de votre projet :

(Documentation : Better Auth - Options)

src/lib/better-auth/index.ts

import { neon } from '@neondatabase/serverless';
import { drizzle } from 'drizzle-orm/neon-http';
import { drizzleAdapter } from 'better-auth/adapters/drizzle';
import { betterAuth } from 'better-auth';
import { betterAuthOptions } from './options';

import * as schema from "../db/schema"; // Ensure the schema is imported

/**
 * Better Auth Instance
 */
export const auth = (env: CloudflareBindings): ReturnType<typeof betterAuth> => {
  const sql = neon(env.DATABASE_URL);
  const db = drizzle(sql);

  return betterAuth({
    ...betterAuthOptions,
    database: drizzleAdapter(db, { provider: 'pg' }),
    baseURL: env.BETTER_AUTH_URL,
    secret: env.BETTER_AUTH_SECRET,

    // Additional options that depend on env ...
  });
};

src/lib/better-auth/options.ts

import { BetterAuthOptions } from 'better-auth';

/**
 * Custom options for Better Auth
 *
 * Docs: https://www.better-auth.com/docs/reference/options
 */
export const betterAuthOptions: BetterAuthOptions = {
  /**
   * The name of the application.
   */
  appName: 'YOUR_APP_NAME',
  /**
   * Base path for Better Auth.
   * @default "/api/auth"
   */
  basePath: '/api',

  // .... More options
};

2. Schéma Better Auth

Pour créer les tables nécessaires à Better Auth, ajoutez d’abord le fichier suivant au répertoire racine :

better-auth.config.ts

/**
 * Better Auth CLI configuration file
 *
 * Docs: https://www.better-auth.com/docs/concepts/cli
 */
import { neon } from '@neondatabase/serverless';
import { drizzle } from 'drizzle-orm/neon-http';
import { drizzleAdapter } from 'better-auth/adapters/drizzle';
import { betterAuth } from 'better-auth';
import { betterAuthOptions } from './src/lib/better-auth/options';

const { DATABASE_URL, BETTER_AUTH_URL, BETTER_AUTH_SECRET } = process.env;

const sql = neon(DATABASE_URL!);
const db = drizzle(sql);

export const auth: ReturnType<typeof betterAuth> = betterAuth({
  ...betterAuthOptions,
  database: drizzleAdapter(db, { provider: 'pg', schema }),  // schema is required in order for bettter-auth to recognize
  baseURL: BETTER_AUTH_URL,
  secret: BETTER_AUTH_SECRET,
});

Exécutez ensuite le script suivant :

npm

npx @better-auth/cli@latest generate --config ./better-auth.config.ts --output ./src/db/schema.ts

pnpm

pnpm dlx @better-auth/cli@latest generate --config ./better-auth.config.ts --output ./src/db/schema.ts

yarn

yarn dlx @better-auth/cli@latest generate --config ./better-auth.config.ts --output ./src/db/schema.ts

bun

bunx @better-auth/cli@latest generate --config ./better-auth.config.ts --output ./src/db/schema.ts

3. Appliquer le schéma à la base de données

Après avoir généré le fichier de schéma, exécutez les commandes suivantes pour créer et appliquer la migration de la base de données : Vérifiez que votre configuration wrangler lit correctement process.env, afin que wrangler dev fonctionne ensuite. Vous devez configurer node_compatibility.

npm

npx drizzle-kit generate
npx drizzle-kit migrate

pnpm

pnpm drizzle-kit generate
pnpm drizzle-kit migrate

yarn

yarn drizzle-kit generate
yarn drizzle-kit migrate

bun

bunx drizzle-kit generate
bunx drizzle-kit migrate

4. Monter le gestionnaire

Montez le gestionnaire Better Auth sur un point de terminaison Hono, en vous assurant que le chemin de montage correspond au paramètre basePath de votre instance Better Auth.

src/index.ts

import { Hono } from 'hono';
import { auth } from './lib/better-auth';

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

app.on(['GET', 'POST'], '/api/*', (c) => {
  return auth(c.env).handler(c.req.raw);
});

export default app;

Utilisation avancée

Cet exemple s’appuie sur les documentations officielles de Hono, Better Auth et Drizzle. Il va toutefois au-delà d’une simple intégration et offre les avantages suivants :

• Un développement efficace grâce à l’intégration des CLI Cloudflare, Better Auth et Drizzle.
• Une transition fluide entre les environnements de développement et de production.
• L’application cohérente des modifications au moyen d’un script.

Vous pouvez compléter cette configuration par des scripts adaptés à votre flux de travail. Par exemple :

package.json

{
  "scripts": {
    "dev": "wrangler dev",
    "deploy": "pnpm run cf-gen-types && wrangler secret bulk .dev.vars.production && wrangler deploy --minify",
    "cf-gen-types": "wrangler types --env-interface CloudflareBindings",
    "better-auth-gen-schema": "pnpm dlx @better-auth/cli@latest generate --config ./better-auth.config.ts --output ./src/db/schema.ts"
  },
}

REMARQUE :
Consultez la documentation officielle de la CLI de chaque outil pour les usages avancés et les options les plus récentes :

• Cloudflare CLI
• Better Auth CLI
• Drizzle ORM CLI

Pour conclure

Vous disposez désormais d’un service d’authentification léger, rapide et complet qui s’exécute sur Cloudflare Workers. Grâce aux Service Bindings, cette configuration permet de construire des architectures de microservices avec une latence minimale.

Ce guide ne présente qu’un exemple de base. Pour des usages avancés comme OAuth ou la limitation du débit, consultez la documentation officielle et adaptez la configuration aux besoins de votre service.

Le code source complet de l’exemple est disponible ici :
Dépôt GitHub