NestJS Cache Manager (@nestjs/cache-manager)

@nestjs/cache-manager is the official NestJS wrapper around the cache-manager library, giving Nest applications a dynamic CacheModule for storing and retrieving values across in-memory, Redis, or any Keyv-compatible backend. It replaces the deprecated built-in CacheModule that used to ship inside @nestjs/common, and is maintained directly under the nestjs GitHub organization by the framework’s core team.

Under the hood, the module builds a cache-manager v7 Cache instance through a Nest-idiomatic ConfigurableModuleBuilder, so it supports both register() for static options and registerAsync() for config-driven setups (e.g. reading a Redis URL from ConfigService). Store instances passed in stores are normalized through Keyv adapters or accepted directly if they already implement the Cacheable or Keyv interfaces, and a bundled CacheInterceptor plus @CacheKey()/@CacheTTL() decorators let HTTP route responses be cached declaratively with automatic X-Cache HIT/MISS headers.

What You Get

• A CacheModule.register()/registerAsync() dynamic module for wiring one or more Keyv-backed cache stores into the Nest DI container
• An injectable Cache token (aliased to CACHE_MANAGER) backed by cache-manager v7’s createCache()
• CacheInterceptor for automatically caching GET route responses keyed by request URL, with X-Cache HIT/MISS response headers
• @CacheKey() and @CacheTTL() decorators (including factory-function variants) for per-route cache key and TTL overrides
• Support for Cacheable and raw Keyv instances passed directly as stores, alongside plain store objects wrapped in Keyv automatically

Common Use Cases

• Caching expensive GET endpoint responses in a Nest REST API without hand-rolling cache-key logic
• Sharing a Redis-backed cache across multiple Nest microservices via a Keyv Redis adapter
• Layering a fast in-memory cache in front of a slower Redis store using cache-manager’s multi-store support
• Injecting the cache manager directly into services to memoize database or third-party API calls

Under The Hood

Architecture The module is a thin, idiomatic Nest integration built around ConfigurableModuleBuilder (lib/cache.module-definition.ts), which generates the register()/registerAsync() static methods on CacheModule (lib/cache.module.ts) so the module can be wired statically or via factory/existing-provider async configuration, mirroring the pattern Nest’s own official modules use. The actual cache instance is built by a single factory provider, createCacheManager() (lib/cache.providers.ts), which normalizes whatever is passed in stores — a plain store object, an existing Keyv instance, or a Cacheable instance — into a form cache-manager’s createCache() can consume, and attaches an onModuleDestroy hook that disconnects every store when the Nest application shuts down. HTTP-layer caching is a separate, opt-in concern: CacheInterceptor (lib/interceptors/cache.interceptor.ts) reads @CacheKey()/@CacheTTL() metadata via Reflector, keys uncached GET requests by URL when no explicit key is set, and writes X-Cache HIT/MISS response headers through the framework-agnostic HttpAdapterHost. This separation — DI-level cache manager vs. HTTP-level interceptor — means the core cache functionality works identically in HTTP, WebSocket, and microservice contexts, with only the interceptor being HTTP-specific.

Tech Stack Written entirely in TypeScript, compiled to a pure ESM package (“type”: “module”) targeting Node’s require(esm)-capable runtimes (^20.19, ^22.12, or >=24). It peer-depends on @nestjs/common/@nestjs/core (^9 through ^12), cache-manager >=6 for the underlying cache engine, keyv >=5 as the storage-adapter abstraction, and rxjs for the interceptor’s observable pipeline. The dev/test stack is comparatively modern for a Nest module: oxlint for linting instead of ESLint, vitest plus supertest for end-to-end HTTP tests, husky and commitlint (Angular convention) for commit hygiene, and release-it for versioned releases, with CircleCI running build and integration-test jobs against a real Node 24 container.

Code Quality Test coverage lives entirely in tests/e2e/.spec.ts, each spec spinning up a real Nest application (via Test.createTestingModule) against a small supporting app under tests/src/ and asserting through supertest — covering custom TTL, async registration with extra providers, multi-store configuration, direct Keyv-instance stores, non-blocking Cacheable stores, and the X-Cache header contract specifically. There are no isolated unit tests for individual providers or decorators, so coverage is entirely black-box/integration-style rather than unit-level. Error handling is deliberate rather than defensive: CacheInterceptor swallows cache-manager read failures silently to avoid breaking a request on a cache outage, but logs write failures explicitly via Nest’s Logger. Naming and typing are consistent with Nest’s own core modules (.module.ts, *.interface.ts, *.decorator.ts), the public API is fully typed with generics for store-specific option shapes, and oxlint plus CircleCI enforce lint and build checks on every change.

API Design The public surface is intentionally small: one dynamic module, one injectable token/class (CACHE_MANAGER/Cache), one interceptor, and two decorators, all documented with @see links back to the official NestJS caching guide and @publicApi JSDoc tags marking the supported surface. Getting started requires no boilerplate beyond a single CacheModule.register() call and a constructor injection of Cache; per-route caching is a one-line @UseInterceptors(CacheInterceptor) plus optional @CacheKey()/@CacheTTL() decorators, with both decorators accepting either a static value or an async factory function for dynamic cases. The main ergonomic rough edge is the ESM-only distribution, which requires either a modern Node runtime or an ESM-compatible build setup, called out explicitly in the README rather than left as a silent breaking change.