Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
FastifyBetterAuth
✓ import FastifyBetterAuth from 'fastify-better-auth';
✗ const FastifyBetterAuth = require('fastify-better-auth');
Primarily designed for ESM usage, with `import` being the standard. CommonJS `require` is not officially supported or typically used.
FastifyBetterAuthOptions
✓ import { type FastifyBetterAuthOptions } from 'fastify-better-auth';
✗ import { 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
✓ import { getAuthDecorator } from 'fastify-better-auth';
✗ const { getAuthDecorator } = require('fastify-better-auth');
`getAuthDecorator` is a named export providing a type-safe way to access the `better-auth` instance from the Fastify decorator.
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();
Errors
Common errors & fixes
Error: The package 'fastify-better-auth' requires a Node.js version >= 23.10.0. You are using vX.Y.Z.
Your Node.js environment is older than the minimum required version 23.10.0.
fixUpgrade Node.js to version 23.10.0 or higher (e.g., using `nvm install 23 && nvm use 23`).
Error: Cannot find module 'better-auth'
The peer dependency `better-auth` is not installed or not resolvable by your package manager.
fixInstall 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
The `auth` option, which expects an initialized `better-auth` instance, was not provided to the plugin.
fixEnsure 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>'.
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.
fixImport `getAuthDecorator` from the package and call it: `import { getAuthDecorator } from 'fastify-better-auth'; const authInstance = getAuthDecorator(fastify);` Audit
Dependencies
better-authrequiredCore authentication library that this plugin integrates with Fastify.
fastifyrequiredThe web framework this plugin is built for; required for plugin registration and functionality.