NestJS Better Auth Fastify Module

0.0.24 · active · verified Wed Apr 22

The `nestjs-better-auth-fastify` package provides a dedicated NestJS module for integrating authentication capabilities specifically when using the Fastify platform adapter. It acts as a bridge, leveraging the underlying `better-auth` library to deliver authentication services tailored for high-performance Fastify-based NestJS applications. Currently, the package is in early development, reflected by its 0.0.24 version, which implies that API surfaces may change without adhering to strict semantic versioning, although recent releases show largely minor updates. Its core differentiator lies in its optimized integration with Fastify, providing a specialized solution for developers prioritizing Fastify's performance benefits within the NestJS ecosystem, rather than a generic authentication module. While recent changes have been minimal, early versions typically address fundamental architectural considerations and bug fixes, such as making `@nestjs/graphql` an optional dependency.

Common errors

```
Error: Nest can't resolve dependencies of the BetterAuthFastifyModule (?). Please make sure that the argument at index [0] is available in the RootTestModule context.
```
cause The `better-auth` library (or its dependencies) is not properly installed or accessible, or the configuration passed to `forRoot` is malformed.

fix Verify `better-auth` is listed in your `package.json` and installed. Check the `forRoot` configuration for any missing required properties or incorrect types as per `better-auth`'s documentation.
```
TypeError: app.listen is not a function
```
cause Attempting to use Fastify-specific application methods (like `listen` on `NestFastifyApplication`) on a generic `INestApplication` instance, likely because the `FastifyAdapter` was not correctly passed during `NestFactory.create`.

fix Ensure `NestFactory.create` is explicitly typed and instantiated with `new FastifyAdapter()`. Example: `await NestFactory.create<NestFastifyApplication>(AppModule, new FastifyAdapter());`

Warnings

breaking As a package in the 0.0.x version range, any release may introduce breaking changes without adhering to strict semantic versioning (e.g., a minor release might contain breaking API changes). Always review the changelog before upgrading.
Fix: Always pin to exact versions (e.g., `"nestjs-better-auth-fastify": "0.0.24"`) or use caret ranges with caution. Thoroughly test updates in development environments.
gotcha Prior to v0.0.17, the `@nestjs/graphql` peer dependency was not truly optional, potentially causing installation or runtime issues if GraphQL was not used. This has since been fixed using dynamic imports.
Fix: Ensure you are using `v0.0.17` or newer if you wish to use the module without installing `@nestjs/graphql`. If on an older version and not using GraphQL, consider installing `@nestjs/graphql` as a temporary workaround or upgrade.
gotcha The module requires `@nestjs/platform-fastify` and `fastify` to be correctly installed and configured in your NestJS application. Using a different platform adapter (e.g., Express) will lead to runtime errors or incorrect behavior.
Fix: Ensure your `main.ts` or `main.js` explicitly configures the NestJS application to use `new FastifyAdapter()` when calling `NestFactory.create()`.

Install

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

Imports

BetterAuthFastifyModule

wrong:

const BetterAuthFastifyModule = require('nestjs-better-auth-fastify').BetterAuthFastifyModule;

correct:

import { BetterAuthFastifyModule } from 'nestjs-better-auth-fastify';

Main module for registration in NestJS root or feature modules. Primarily used with ESM imports in modern NestJS projects.

BetterAuthGuard
```
import { BetterAuthGuard } from 'nestjs-better-auth-fastify';
```
Guard to protect routes, typically applied with `@UseGuards(BetterAuthGuard)`.
BetterAuthConfig
```
import { BetterAuthConfig } from 'nestjs-better-auth-fastify';
```
Interface or type definition for module configuration options. Used for type safety when configuring the module.

Quickstart

This quickstart demonstrates setting up a basic NestJS application using Fastify as the platform adapter and integrating `nestjs-better-auth-fastify` with a minimal configuration.

import { NestFactory } from '@nestjs/core';
import { FastifyAdapter, NestFastifyApplication } from '@nestjs/platform-fastify';
import { Module } from '@nestjs/common';
import { BetterAuthFastifyModule } from 'nestjs-better-auth-fastify';

@Module({
  imports: [
    BetterAuthFastifyModule.forRoot({
      secret: process.env.AUTH_SECRET ?? 'super-secret-jwt-key',
      expiresIn: '1h',
      // Other better-auth specific configurations would go here
      // For example, strategy configuration:
      // strategies: [
      //   { name: 'jwt', handler: () => ({ /* JWT strategy setup */ }) }
      // ]
    }),
  ],
  controllers: [],
  providers: [],
})
class AppModule {}

async function bootstrap() {
  const app = await NestFactory.create<NestFastifyApplication>(
    AppModule,
    new FastifyAdapter(),
  );

  app.listen(3000, () => {
    console.log('NestJS application with Fastify and BetterAuth listening on port 3000');
  });
}

bootstrap();

view raw JSON →