clhq-auth-module

1.1.0-alpha.189 verified Sat Apr 25 auth: no javascript

A reusable authentication module for NestJS v11 applications, currently in early alpha (v1.1.0-alpha.189). It provides guards, decorators, and services for JWT-based auth with role-based access control. Differentiators: minimal configuration, full TypeScript support, and designed for monorepo workflows. Requires @nestjs/core >=11.0.0 and @nestjs/common >=11.0.0. Active development with frequent breaking changes before stable.

Common errors

error Cannot find module 'clhq-auth-module' or its corresponding type declarations. ↓

cause Missing npm install or TypeScript not configured to resolve the module.

fix

Run 'npm install clhq-auth-module' and ensure 'moduleResolution' is 'node' or 'node16' in tsconfig.json.

error Error: Forbidden resource ↓

cause Request lacks valid JWT token or token is expired.

fix

Provide a valid JWT token in the Authorization header: 'Bearer <token>'.

error Nest can't resolve dependencies of the AuthModule (JwtAuthGuard, ...) ↓

cause AuthModule.forRoot() not called or missing peer dependencies.

fix

Ensure @nestjs/core and @nestjs/common are installed and AuthModule.forRoot() is added to the imports array.

Warnings

breaking The module API is unstable in alpha versions; forRoot() options may change without notice. ↓

fix Pin to a specific alpha version and monitor release notes.

deprecated Usage of 'AuthModule.forRootAsync()' with factory provider is deprecated in favor of synchronous forRoot(). ↓

fix Pass configuration directly to forRoot().

gotcha JwtAuthGuard must be applied to controllers or routes; it does not automatically protect all endpoints. ↓

fix Add @UseGuards(JwtAuthGuard) to controller class or individual routes.

breaking The 'Roles' decorator previously accepted an array of strings; now requires an array of enums. ↓

fix Define an enum for roles and pass an array of enum values.

Install

npm install clhq-auth-module

yarn add clhq-auth-module

pnpm add clhq-auth-module

Imports

AuthModule

wrong

const AuthModule = require('clhq-auth-module')

correct

import { AuthModule } from 'clhq-auth-module'

ESM-only package; CommonJS require will fail.

JwtAuthGuard

wrong

import { JWTGuard } from 'clhq-auth-module'

correct

import { JwtAuthGuard } from 'clhq-auth-module'

Guard name is case-sensitive and includes 'Auth'.

Roles

wrong

import { Roles } from '@nestjs/passport'

correct

import { Roles } from 'clhq-auth-module'

Custom Roles decorator provided by this module, not from passport.

CurrentUser
wrong
```
import { Req } from '@nestjs/common'
```
correct
```
import { CurrentUser } from 'clhq-auth-module'
```
Use this decorator to access the authenticated user in route handlers.

Quickstart

Shows how to import and configure AuthModule with a JWT secret in a NestJS application.

import { Module } from '@nestjs/common';
import { AuthModule } from 'clhq-auth-module';
import { AppController } from './app.controller';

@Module({
  imports: [
    AuthModule.forRoot({
      jwtSecret: process.env.JWT_SECRET ?? '',
      expiry: '1h',
    }),
  ],
  controllers: [AppController],
})
export class AppModule {}