Better Auth RONIN Database Adapter

Common errors

• Error [ERR_REQUIRE_ESM]: require() of ES Module .../node_modules/blade-better-auth/dist/index.js from ... not supported.

  cause Attempting to `require` an ESM-only package (`blade-better-auth`) in a CommonJS context.
  fix Switch your project to use ECMAScript Modules (ESM) by adding `'type': 'module'` to your `package.json` or use dynamic `import()` for `blade-better-auth`.

• TypeError: Cannot read properties of undefined (reading 'model') at blade/schema/index.ts

  cause One or more of the required RONIN schema models (User, Session, Account, Verification) for Better Auth are not correctly defined or accessible in your database schema.
  fix Verify that the `User`, `Session`, `Account`, and `Verification` models are accurately set up in your RONIN database according to the `better-auth` 'core schema' requirements, as detailed in the `blade-better-auth` README.

• Error: Peer dependency blade-client@^3.16.2 not installed.

  cause The `blade-client` peer dependency is missing from your project's `node_modules` or an incompatible version is installed.
  fix Install the required version of `blade-client` using `npm install blade-client@^3.16.2` (or `yarn add blade-client@^3.16.2` / `pnpm add blade-client@^3.16.2`).

• Error: Invalid token provided for RONIN client.

  cause A custom `blade-client` instance was initialized without a valid RONIN API token, preventing database access.
  fix Ensure the `RONIN_TOKEN` environment variable is correctly set with a valid RONIN API token, or explicitly pass a valid token string to `createSyntaxFactory({ token: 'your_token_here' })` when creating your custom client.

Warnings

• breaking Since version 3.x, `blade-better-auth` is distributed as an ESM-only package. Attempting to `require()` it in CommonJS environments will result in runtime errors.
  Fix: Migrate your project to use ECMAScript Modules (ESM) by adding `'type': 'module'` to your `package.json` or use dynamic `import()` for `blade-better-auth`.
• gotcha The Better Auth 'core schema' (User, Session, Account, Verification models) must be correctly defined and present in your RONIN database for the adapter to function. Missing or incorrectly structured models will lead to database errors and authentication failures.
  Fix: Refer to the `blade-better-auth` README and `better-auth` documentation for the exact schema requirements and implement them accurately in your RONIN database via `blade/schema`.
• breaking `blade-client` is a peer dependency, meaning your application must explicitly install it. Major version updates of `blade-client` may introduce breaking changes requiring updates to `blade-better-auth` or your application code that uses `blade-client` directly.
  Fix: Ensure your `blade-client` version is compatible with your `blade-better-auth` version. Always check both package changelogs before upgrading either dependency.
• gotcha When providing a custom `blade-client` instance to `ronin()`, ensure the `token` (e.g., `process.env.RONIN_TOKEN`) is correctly supplied and valid. Without a valid token, the client will fail to authenticate with the RONIN API, leading to persistent connection errors.
  Fix: Set the `RONIN_TOKEN` environment variable with a valid API token or explicitly pass a valid token to `createSyntaxFactory({ token: 'your_token' })`.

Install

• npm install blade-better-auth npm
• yarn add blade-better-auth yarn
• pnpm add blade-better-auth pnpm

Imports

• ronin
  wrong:

  const { ronin } = require('blade-better-auth');

  correct:

  import { ronin } from 'blade-better-auth';

  The primary factory function for configuring the RONIN database adapter. This package is ESM-only since v3.
• betterAuth
  wrong:

  import BetterAuth from 'better-auth';

  correct:

  import { betterAuth } from 'better-auth';

  This symbol is from the `better-auth` package, not `blade-better-auth`, but is crucial for consuming the adapter. Ensure correct named import.
• createSyntaxFactory
  wrong:

  import { createSyntaxFactory } from 'blade-better-auth';

  correct:

  import { createSyntaxFactory } from 'blade-client';

  Used for creating custom RONIN client instances. It is part of `blade-client`, not `blade-better-auth`. Developers often confuse its origin when setting up custom clients.

Quickstart

Demonstrates initializing Better Auth with `blade-better-auth` using both a default and a custom RONIN client instance, highlighting common setup patterns for session management.

import { betterAuth } from 'better-auth';
import { ronin } from "blade-better-auth";
import { createSyntaxFactory } from 'blade-client';

// --- Option 1: Use the default RONIN client managed by the adapter ---
// This simplifies setup, assuming a default RONIN environment and config.
const authWithDefaultClient = betterAuth({
  database: ronin(), // Use the default RONIN client
  // ... other Better Auth configuration, e.g., providers, secrets
  secret: process.env.AUTH_SECRET ?? 'super-secret-dev-key', // Example secret for development
  callbacks: {
    async signIn({ user }) {
      console.log(`User ${user.email} signed in.`);
      return true;
    },
  },
});

// --- Option 2: Provide a custom RONIN client instance ---
// Useful for specific configurations, e.g., custom tokens, endpoints, or advanced client options.
const customClient = createSyntaxFactory({
  token: process.env.RONIN_TOKEN ?? '', // Ensure RONIN_TOKEN is set in environment for production
  // ... other blade-client configuration specific to your RONIN setup
});

const authWithCustomClient = betterAuth({
  database: ronin(customClient), // Pass the custom client instance
  // ... other Better Auth configuration
  secret: process.env.AUTH_SECRET ?? 'another-secret-dev-key',
  callbacks: {
    async redirect({ url, baseUrl }) {
      console.log(`Redirecting to ${url} from ${baseUrl}.`);
      return url;
    },
  },
});

console.log('Better Auth adapters initialized for different client types.');

// In a real application, you would typically export and use one of these instances
// within your API routes, server-side functions, or authentication middleware.
// export { authWithDefaultClient as auth };