{"id":16779,"library":"blade-better-auth","title":"Better Auth RONIN Database Adapter","description":"blade-better-auth (current stable version 3.18.35) functions as a specialized database adapter, integrating the `better-auth` authentication framework with RONIN databases. Its primary role is to facilitate the storage of session and user data within a RONIN backend by translating `better-auth`'s core schema requirements into RONIN's data modeling language. This package provides a `ronin()` factory function that can either operate with a default RONIN client instance or accept a custom `blade-client` instance, offering flexibility for advanced configurations like specific token management. The library ships with comprehensive TypeScript type definitions, ensuring type-safe development. Operating under a rapid versioning scheme, it undergoes continuous maintenance and updates, reflecting its active role within the RONIN ecosystem. It distinguishes itself by providing the specific bridge and schema translations necessary for this particular technology stack.","status":"active","version":"3.18.35","language":"javascript","source_language":"en","source_url":"https://github.com/ronin-co/better-auth","tags":["javascript","auth","better-auth","betterauth","ronin","ts","typescript"],"install":[{"cmd":"npm install blade-better-auth","lang":"bash","label":"npm"},{"cmd":"yarn add blade-better-auth","lang":"bash","label":"yarn"},{"cmd":"pnpm add blade-better-auth","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required for interacting with the RONIN database","package":"blade-client","optional":false}],"imports":[{"note":"The primary factory function for configuring the RONIN database adapter. This package is ESM-only since v3.","wrong":"const { ronin } = require('blade-better-auth');","symbol":"ronin","correct":"import { ronin } from 'blade-better-auth';"},{"note":"This symbol is from the `better-auth` package, not `blade-better-auth`, but is crucial for consuming the adapter. Ensure correct named import.","wrong":"import BetterAuth from 'better-auth';","symbol":"betterAuth","correct":"import { betterAuth } from 'better-auth';"},{"note":"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.","wrong":"import { createSyntaxFactory } from 'blade-better-auth';","symbol":"createSyntaxFactory","correct":"import { createSyntaxFactory } from 'blade-client';"}],"quickstart":{"code":"import { betterAuth } from 'better-auth';\nimport { ronin } from \"blade-better-auth\";\nimport { createSyntaxFactory } from 'blade-client';\n\n// --- Option 1: Use the default RONIN client managed by the adapter ---\n// This simplifies setup, assuming a default RONIN environment and config.\nconst authWithDefaultClient = betterAuth({\n  database: ronin(), // Use the default RONIN client\n  // ... other Better Auth configuration, e.g., providers, secrets\n  secret: process.env.AUTH_SECRET ?? 'super-secret-dev-key', // Example secret for development\n  callbacks: {\n    async signIn({ user }) {\n      console.log(`User ${user.email} signed in.`);\n      return true;\n    },\n  },\n});\n\n// --- Option 2: Provide a custom RONIN client instance ---\n// Useful for specific configurations, e.g., custom tokens, endpoints, or advanced client options.\nconst customClient = createSyntaxFactory({\n  token: process.env.RONIN_TOKEN ?? '', // Ensure RONIN_TOKEN is set in environment for production\n  // ... other blade-client configuration specific to your RONIN setup\n});\n\nconst authWithCustomClient = betterAuth({\n  database: ronin(customClient), // Pass the custom client instance\n  // ... other Better Auth configuration\n  secret: process.env.AUTH_SECRET ?? 'another-secret-dev-key',\n  callbacks: {\n    async redirect({ url, baseUrl }) {\n      console.log(`Redirecting to ${url} from ${baseUrl}.`);\n      return url;\n    },\n  },\n});\n\nconsole.log('Better Auth adapters initialized for different client types.');\n\n// In a real application, you would typically export and use one of these instances\n// within your API routes, server-side functions, or authentication middleware.\n// export { authWithDefaultClient as auth };","lang":"typescript","description":"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."},"warnings":[{"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`.","message":"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.","severity":"breaking","affected_versions":">=3.0.0"},{"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`.","message":"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.","severity":"gotcha","affected_versions":">=3.0.0"},{"fix":"Ensure your `blade-client` version is compatible with your `blade-better-auth` version. Always check both package changelogs before upgrading either dependency.","message":"`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.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Set the `RONIN_TOKEN` environment variable with a valid API token or explicitly pass a valid token to `createSyntaxFactory({ token: 'your_token' })`.","message":"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.","severity":"gotcha","affected_versions":">=3.0.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"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`.","cause":"Attempting to `require` an ESM-only package (`blade-better-auth`) in a CommonJS context.","error":"Error [ERR_REQUIRE_ESM]: require() of ES Module .../node_modules/blade-better-auth/dist/index.js from ... not supported."},{"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.","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.","error":"TypeError: Cannot read properties of undefined (reading 'model') at blade/schema/index.ts"},{"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`).","cause":"The `blade-client` peer dependency is missing from your project's `node_modules` or an incompatible version is installed.","error":"Error: Peer dependency blade-client@^3.16.2 not installed."},{"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.","cause":"A custom `blade-client` instance was initialized without a valid RONIN API token, preventing database access.","error":"Error: Invalid token provided for RONIN client."}],"ecosystem":"npm","meta_description":null}