NestJS Cache Manager

This package is distributed as ESM only. To avoid ERR_REQUIRE_ESM errors when using require() (which happens in CommonJS applications), you must use a Node.js version where require(esm) is available unflagged.

Supported Node.js versions:

• ^20.19.0
• ^22.12.0
• >=24.0.0

If you are using a standard NestJS setup (CommonJS), you can continue using standard import statements; TypeScript will compile them to require(), and the compatible Node.js runtime will handle the ESM loading automatically.

To use caching in your NestJS application, install the @nestjs/cache-manager package along with the underlying cache-manager library.

This package serves as a drop-in replacement for the deprecated CacheModule that was previously part of @nestjs/common.

$ npm i --save @nestjs/cache-manager cache-manager

This docker-compose.yml file provides a configuration to run a Redis instance, which can be used as a cache store for the @nestjs/cache-manager package. It exposes the default Redis port 6379 to the host machine.

version: "3"

services:
  redis:
    image: redis
    ports:
      - "6379:6379"
    restart: always

The CacheModuleOptions object defines how the cache module is initialized. It combines standard CacheManagerOptions with store-specific configuration and an optional isGlobal flag.

• isGlobal (optional): If set to true, the CacheModule is registered as a global module, making it available across the entire application without needing to import it into every module.

Note: Store-specific configuration keys take precedence over general cache module options because of how createCacheManager is implemented.

const options: CacheModuleOptions = {
  isGlobal: true,
  // ... other CacheManagerOptions and store-specific config
};

The CacheModule is configured using the MODULE_OPTIONS_TOKEN. When setting up the module, you can provide configuration via the register or registerAsync methods. If you are using a factory pattern to provide options, the module expects a method named createCacheOptions to be available on your options factory object.

// Example of how the module is typically configured using the generated class
@Module({
  imports: [CacheModule.register({ ttl: 60 })],
})
export class AppModule {}

The CacheInterceptor is the primary tool for implementing automatic response caching in NestJS applications. By applying this interceptor to a controller or a specific route handler, NestJS will automatically cache the response and serve it from the cache for subsequent requests, reducing load on your application logic and data sources.

To use it, import CacheInterceptor from @nestjs/cache-manager and register it using the @UseInterceptors() decorator.

import { Controller, Get, UseInterceptors } from '@nestjs/common';
import { CacheInterceptor } from '@nestjs/cache-manager';

@Controller('users')
@UseInterceptors(CacheInterceptor) // Applies caching to all routes in this controller
export class UsersController {
  @Get()
  findAll() {
    return { data: 'this is cached' };
  }
}

Use CacheModule.register() to configure the cache manager with static options. This is useful when your cache configuration does not depend on any asynchronous providers (like ConfigService). You can pass isGlobal: true in the options to make the CacheModule available globally across your entire application.

@Module({
  imports: [CacheModule.register({ isGlobal: true, store: myStore, ... })],
})
export class AppModule {}

Use the @CacheTTL() decorator to define a custom time-to-live (TTL) for cached responses on a specific route handler. The TTL value is specified in milliseconds.

You can provide a static number or a CacheTTLFactory function. The factory function receives the ExecutionContext and can return a number or a Promise<number>, allowing you to calculate the TTL dynamically based on the request context (e.g., user roles or request headers).

// Using a static number (5 seconds)
@CacheTTL(5000)
@Get()
async findAll() {}

// Using a dynamic factory
@CacheTTL((context: ExecutionContext) => {
  const request = context.switchToHttp().getRequest();
  return request.user.isAdmin ? 60000 : 1000;
})
@Get()
async findDynamic() {}

Use CacheModule.registerAsync() to configure the cache manager using asynchronous providers. This is the recommended approach when your cache configuration needs to be fetched from an external source or a NestJS ConfigService. You can also provide extraProviders via the options object to include additional providers in the module.

@Module({
  imports: [
    CacheModule.registerAsync({
      isGlobal: true,
      useFactory: async (configService: ConfigService) => ({
        store: myStore,
        ttl: configService.get('CACHE_TTL'),
      }),
      inject: [ConfigService],
      extraProviders: [MyCustomProvider],
    }),
  ],
})
export class AppModule {}