create-nestjs-middleware-module

NestJS configured middleware module made simple

What is it?

It is a tiny helper library that helps you create simple idiomatic NestJS module based on Express/Fastify middleware in just a few lines of code with routing out of the box.

---

This is the documentation for v0.5. Compatibility with earlier versions:

create-nestjs-middleware-module	NestJS	Node.js
v0.5	11.2+, 12	>=22.12
v0.4	8, 9, 10, 11	>=18

---

Install

npm i create-nestjs-middleware-module

or

yarn add create-nestjs-middleware-module

Usage

Let's imaging you have some middleware factory, for example, simple logger:

export interface Options {
  maxDuration: number
}

export function createResponseDurationLoggerMiddleware(opts: Options) {
  return (request, response, next) => {
    const start = Date.now();

    response.on('finish', () => {
      const message = `${request.method} ${request.path} - ${duration}ms`;

      const duration = Date.now() - start;

      if (duration > maxDuration) {
        console.warn(message);
      } else {
        console.log(message);
      }
    });

    next();
  };
}

And you want to create an idiomatic NestJS module based on that middleware. Just pass this middleware factory to createModule function:

import { createModule } from 'create-nestjs-middleware-module';
import { Options, createResponseDurationLoggerMiddleware } from './middleware';

export const TimingModule = createModule<Options>(createResponseDurationLoggerMiddleware);

That's it, your module is ready. Let's see what API it has:

import { TimingModule } from './timing-module';
import { MyController } from './my.controller';

@Module({
  imports: [

    // 1. `.forRoot()` method accept params satisfying `Options` interface
    TimingModule.forRoot({ maxDuration: 1000 }),

    // 2. `.forRoot()` method accept additional optional routing params
    TimingModule.forRoot({
      maxDuration: 1000,

      // both `forRoutes` and `exclude` properties are optional
      // and has the same API as NestJS buil-in `MiddlewareConfigProxy`
      // @see https://docs.nestjs.com/middleware#applying-middleware
      forRoutes: [MyController],
      exclude: [{ method: RequestMethod.ALL, path: 'always-fast' }],
    }),

    // 3. `.forRootAsync()` method with only factory
    TimingModule.forRootAsync({
      useFactory: async () => {
        return { maxDuration: 1000 }
      }
    }),

    // 4. `.forRootAsync()` method with dependencies
    TimingModule.forRootAsync({
      imports: [ConfigModule],
      inject: [ConfigService],
      useFactory: async (config: ConfigService) => {
        return { maxDuration: config.maxDurationForAPIHandler }
      }
    }),

    // 5. `.forRootAsync()` method with routing
    TimingModule.forRootAsync({
      imports: [ConfigModule],
      inject: [ConfigService],
      useFactory: async (config: ConfigService) => {
        return {
          maxDuration: config.maxDurationForAPIHandler

          // both `forRoutes` and `exclude` properties are optional
          // and has the same API as NestJS buil-in `MiddlewareConfigProxy`
          // @see https://docs.nestjs.com/middleware#applying-middleware
          forRoutes: [MyController],
          exclude: [{ method: RequestMethod.ALL, path: 'always-fast' }],
        };
      }
    }),
  ]
  controllers: [MyController /*, ... */]
})
class App {}

More examples

See examples of usage in __tests__ folder or nestjs-session and nestjs-cookie-session packages

Notes

1. createModule callback function can return not only one middleware, but array of it.

import { createModule } from 'create-nestjs-middleware-module';


interface Options {
  // ...
}

createModule<Options>((options) => {
  function firstMidlleware() { /* ... */ }
  function secondMidlleware() { /* ... */ }
  return [firstMidlleware, secondMidlleware]
});

1. If your Options interface has not required properties it can be frustrating to force end-users of your module to call forRoot({}), and for better developer expirience you can cast createModule(...) result to FacadeModuleStaticOptional<Options>, then forRoot() could be called without arguments and without TS error. In such case createModule callback function will be called with empty object {}.

import { createModule, FacadeModuleStaticOptional } from 'create-nestjs-middleware-module';

interface Options {
  maxDuration?: number;
}

createModule<Options>((options) => {
  typeof options // always "object" even if not passed to `forRoot()`

  return (request, response, next) => {
    // ...
    next();
  };
}) as FacadeModuleStaticOptional<Options>;

1. For better developer experience of end-users of your module you can also export interfaces of forRoot and forRootAsync argument:

import {
  AsyncOptions,
  SyncOptions,
} from 'create-nestjs-middleware-module';

interface Options {
  // ...
}

export type MyModuleOptions = SyncOptions<Options>;

export type MyModuleAsyncOptions = AsyncOptions<Options>;

1. This library is tested against express and fastify. But you should be aware that middlewares of express are not always work with fastify and vise versa. Sometimes you can check platforms internally. Sometimes maybe it's better to create 2 separate modules for each platform. It's up to you.

Migration

v0.5

NestJS 8, 9 and 10 are dropped: @nestjs/common and @nestjs/core are peer dependencies with the range ^11.2.0 || ^12.0.0, and Node.js >=22.12 is required. The package is also published from dist/ with an exports map instead of copying the build output into the package root, so deep imports into the package no longer resolve — import from the package root.

The default route changed from * to {/*splat}, which fixes the global prefix root. With app.setGlobalPrefix('v1') and no explicit forRoutes, a module built with this library behaved like this:

request	before	after
/v1	no middleware	middleware
/v1/anything	middleware	middleware

path-to-regexp v8, used by express@5 and @fastify/middie@9, no longer accepts the unnamed * wildcard, so NestJS converted it into /v1/{*path} — a pattern that matches everything under the prefix but not the prefix itself. Nothing changes if the end-user passes their own forRoutes, or if no global prefix is set; paths excluded from the global prefix keep the middleware as before.

Do you use this library?
Don't be shy to give it a star! ★

Also if you are into NestJS you might be interested in one of my other NestJS libs.