Fastify Integration for Better Auth

1.2.0 · active · verified Wed Apr 22

Fastify Better Auth is a Fastify plugin designed to seamlessly integrate the `better-auth` authentication library into Fastify applications. It automates the registration of all necessary authentication routes, typically under `/api/auth/*`, and decorates the Fastify instance with utilities to access the `better-auth` instance and manage session data. The current stable version is 1.2.0, with minor feature releases indicating active development. Key differentiators include its focus on type-safe decorator access to the auth instance via `getAuthDecorator()` and its direct compatibility with Fastify 5.x and Better Auth 1.x, simplifying setup for applications using these specific versions.

Common errors

```
Error: The package 'fastify-better-auth' requires a Node.js version >= 23.10.0. You are using vX.Y.Z.
```
cause Your Node.js environment is older than the minimum required version 23.10.0.

fix Upgrade Node.js to version 23.10.0 or higher (e.g., using `nvm install 23 && nvm use 23`).
```
Error: Cannot find module 'better-auth'
```
cause The peer dependency `better-auth` is not installed or not resolvable by your package manager.

fix Install the `better-auth` package: `npm install better-auth@1.x` or `yarn add better-auth@1.x`.
```
FastifyError: FST_ERR_BAD_PLUGIN_OPTS: Plugin 'fastify-better-auth' requires a 'auth' option
```
cause The `auth` option, which expects an initialized `better-auth` instance, was not provided to the plugin.

fix Ensure you pass an `auth` object when registering the plugin: `fastify.register(FastifyBetterAuth, { auth: yourAuthInstance });`
```
Property 'getAuthDecorator' does not exist on type 'FastifyInstance<any, any, any, Logger, RawServerDefault>'.
```
cause You are trying to access `getAuthDecorator` directly on the `fastify` instance, but it's an exported utility function, not a decorator on the instance itself.

fix Import `getAuthDecorator` from the package and call it: `import { getAuthDecorator } from 'fastify-better-auth'; const authInstance = getAuthDecorator(fastify);`

Warnings

breaking This package requires Node.js version 23.10.0 or higher. Running on older Node.js versions will result in installation failures or runtime errors.
Fix: Upgrade your Node.js environment to version 23.10.0 or newer. Consider using a Node.js version manager like `nvm` or `volta`.
breaking The plugin has strict peer dependency requirements for `fastify@5.x` and `better-auth@1.x`. Incompatible versions of these libraries may lead to runtime errors or unexpected behavior.
Fix: Ensure that `fastify` and `better-auth` are installed at versions `5.x` and `1.x` respectively. Check your `package.json` for correct peer dependency resolution.
gotcha While module augmentation for TypeScript is possible, `getAuthDecorator()` is the recommended and type-safe way to access the `better-auth` instance from Fastify, especially when plugins extend the auth instance.
Fix: Always prefer `import { getAuthDecorator } from 'fastify-better-auth';` and call it to retrieve the `better-auth` instance in your handlers or hooks.

Install

npm install fastify-better-auth npm
yarn add fastify-better-auth yarn
pnpm add fastify-better-auth pnpm

Imports

FastifyBetterAuth
wrong:
```
const FastifyBetterAuth = require('fastify-better-auth');
```
correct:
```
import FastifyBetterAuth from 'fastify-better-auth';
```
Primarily designed for ESM usage, with `import` being the standard. CommonJS `require` is not officially supported or typically used.
FastifyBetterAuthOptions
wrong:
```
import { FastifyBetterAuthOptions } from 'fastify-better-auth';
```
correct:
```
import { type FastifyBetterAuthOptions } from 'fastify-better-auth';
```
Use `import type` for type-only imports to ensure they are removed during compilation, preventing potential runtime issues or unnecessary bundles.
getAuthDecorator
wrong:
```
const { getAuthDecorator } = require('fastify-better-auth');
```
correct:
```
import { getAuthDecorator } from 'fastify-better-auth';
```
`getAuthDecorator` is a named export providing a type-safe way to access the `better-auth` instance from the Fastify decorator.

Quickstart

Demonstrates how to initialize a `better-auth` instance and register it as a Fastify plugin, providing authentication routes and instance access.

import { betterAuth } from 'better-auth';
import { drizzleAdapter } from 'better-auth/adapters/drizzle';
import type { FastifyInstance } from 'fastify';
import Fastify from 'fastify';
import FastifyBetterAuth from 'fastify-better-auth';
import fp from 'fastify-plugin';

// Mock DB for demonstration; replace with your actual Drizzle ORM client
const db = {};

// 1. Create the Better Auth instance
export const auth = betterAuth({
  trustedOrigins: [process.env.AUTH_URL ?? 'http://localhost:3000'],
  database: drizzleAdapter(db as any, { // Cast db to any for mock simplicity
    provider: 'pg',
    usePlural: true,
  }),
  emailAndPassword: {
    enabled: true,
  },
});

// 2. Define and register the plugin using fastify-plugin
async function authPlugin(fastify: FastifyInstance) {
  await fastify.register(FastifyBetterAuth, { auth });
  fastify.get('/protected', async (request, reply) => {
    // Example of accessing the auth instance, though this route is not protected by default
    // const authInstance = fastify.getAuthDecorator(); 
    return { message: 'Hello from a route. Auth routes are registered at /api/auth/*' };
  });
}

const registeredAuthPlugin = fp(authPlugin, {
  name: 'auth-plugin',
});

// 3. Set up and start your Fastify application
const fastify = Fastify({ logger: true });

fastify.register(registeredAuthPlugin);

const start = async () => {
  try {
    await fastify.listen({ port: 3000 });
    console.log('Server listening on http://localhost:3000');
  } catch (err) {
    fastify.log.error(err);
    process.exit(1);
  }
};

start();

view raw JSON →