nestjs-better-auth

The library registers an AuthGuard globally by default. This means all routes in your application are protected unless you explicitly opt-out using decorators.

• REST & GraphQL: The global guard applies to both controllers and resolvers. Use @AllowAnonymous() to make a route public or @OptionalAuth() to make authentication optional.
• WebSockets: The global guard also applies to WebSocket connections. To protect a Gateway or specific messages, you must apply the AuthGuard using @UseGuards(AuthGuard) at the Gateway or Message level.

import { SubscribeMessage, WebSocketGateway } from "@nestjs/websockets";
import { UseGuards } from "@nestjs/common";
import { AuthGuard } from '@thallesp/nestjs-better-auth';

@WebSocketGateway({
	path: "/ws",
	namespace: "test",
	cors: {
		origin: "*",
	},
})
@UseGuards(AuthGuard)
export class TestGateway { /* ... */ }

On Fastify, the module automatically applies CORS to Better Auth routes based on the trustedOrigins setting in your Better Auth configuration.

Important considerations:

• App-level @fastify/cors does not fully apply to Better Auth routes on its own.
• The automatic fallback only supports array-based trustedOrigins. Function-based trustedOrigins are currently unsupported.
• If you need to use function-based trustedOrigins, set disableTrustedOriginsCors: true and manage CORS for Better Auth routes manually.

Install the library using your preferred package manager to integrate Better Auth into your NestJS application.

# Using npm
npm install @thallesp/nestjs-better-auth

# Using yarn
yarn add @thallesp/nestjs-better-auth

# Using pnpm
pnpm add @thallesp/nestjs-better-auth

# Using bun
bun add @thallesp/nestjs-better-auth

By default, the module registers a global AuthGuard. If you prefer to manage route protection manually, set disableGlobalAuthGuard: true in the AuthModule.forRoot() configuration. You can then apply the AuthGuard specifically to controllers or routes using the @UseGuards(AuthGuard) decorator.

// app.module.ts
@Module({
  imports: [
    AuthModule.forRoot({
      auth,
      disableGlobalAuthGuard: true,
    }),
  ],
})
export class AppModule {}

// app.controller.ts
import { AuthGuard } from "@thallesp/nestjs-better-auth";

@Controller("users")
@UseGuards(AuthGuard)
export class UserController {
  @Get("me")
  async getProfile() {
    return { message: "Protected route" };
  }
}

Before installing, ensure you meet the following requirements:

• A working NestJS application.
• better-auth version >= 1.5.0 installed and configured.

IMPORTANT

Versions of better-auth older than 1.5.0 are deprecated and unsupported.

To run the Pokemon team builder example, which demonstrates nestjs-better-auth integration with Fastify and an in-memory database, use the following commands:

pnpm install
pnpm start:dev

The example demonstrates three distinct authorization patterns using decorators:

1. Public Routes: No authentication required. Accessible via @AllowAnonymous().

   • GET /pokemon
   • GET /pokemon/:id

2. Optional Auth Routes: Routes that provide personalized responses if a user is logged in, but remain accessible to guests. Accessible via @OptionalAuth().

   • GET /pokemon/featured/random

3. Protected Routes: Routes that strictly require an active session. Accessible via @Session().

   • GET /pokemon/team/my
   • POST /pokemon/team/:pokemonId
   • DELETE /pokemon/team/:pokemonId

To allow Better Auth to handle the raw request body, you must disable NestJS's built-in body parser in your main.ts file.

Note: Disabling this means the rawBody: true option in NestFactory.create() will have no effect. If you need access to req.rawBody (e.g., for webhooks), configure it via AuthModule.forRoot() instead.

import { NestFactory } from "@nestjs/core";
import { AppModule } from "./app.module";

async function bootstrap() {
  const app = await NestFactory.create(AppModule, {
    // The library will re-add the default body parsers for non-auth routes.
    bodyParser: false,
  });
  await app.listen(process.env.PORT ?? 3333);
}
bootstrap();

The AuthModule uses NestJS discovery to find providers decorated with @Hook or @DatabaseHook.

Lifecycle Requirements: To use these decorators, you must explicitly enable the hook systems in your AuthModule.forRoot() configuration by providing the corresponding empty objects. If you provide decorated providers without these configuration keys, the module will throw an error during initialization.

• Hooks: Enabled via auth.options.hooks = {}. These allow you to intercept Better Auth lifecycle events.
• Database Hooks: Enabled via auth.options.databaseHooks = {}. These allow you to intercept database operations (like create, update, etc.) on specific models.