NestJS RedisX

Modular Redis toolkit for NestJS with plugin architecture

Documentation • Getting Started • API Reference • Discussions

Who is this for

• Replace cache-manager with production-grade L1+L2 caching, stampede protection, and tag invalidation
• Need distributed locks, rate limiting, and idempotency in one ecosystem instead of 5 separate libraries
• Need Prometheus metrics and OpenTelemetry tracing for Redis operations out of the box
• Building multi-tenant NestJS apps that need cache isolation per tenant
• Migrating from raw ioredis/node-redis and want NestJS-native DI integration

Quality

• 2k+ tests across unit, integration, and E2E
• Coverage tracked via Codecov
• Pack-test validates every package installs and works from tarball
• Compatibility tested across Node 18/20/22/24, NestJS 10/11, Redis 6.2/7.x
• Works with both Express and Fastify adapters

Node.js support: the published packages run on Node >= 18 (declared in each package's engines and exercised in CI on 18/20/22/24). The root package.json of this monorepo requires Node >= 20 — that constraint applies only to developing this repository (build tooling), not to using the packages.

Testing details | Compatibility matrix

Features

	Feature	What you get
Cache	Two-Tier Cache	L1 memory + L2 Redis with anti-stampede, SWR, and tag invalidation
Locks	Distributed Locks	Redis-based locking with auto-renewal and retry strategies
Rate Limit	Rate Limiting	Fixed window, sliding window, and token bucket algorithms
Circuit Breaker	Distributed Circuit Breaker	Closed/open/half-open breaker with fail-fast rejection and fallbacks
Pub/Sub	Typed Pub/Sub	Publish/subscribe with pattern subscriptions and @Subscribe auto-discovery
Session	Session Management	express-session/@fastify/session store with device page, revoke-everywhere, seat limits
Idempotency	Request Idempotency	Deduplication with fingerprinting and response replay
Streams	Redis Streams	Consumer groups, dead-letter queues, and backpressure
Metrics	Prometheus Metrics	Command latencies, cache hit rates, and custom metrics
Tracing	OpenTelemetry Tracing	Distributed tracing with Jaeger/Zipkin/OTLP export

Quick Start

npm install @nestjs-redisx/core @nestjs-redisx/cache ioredis

import { RedisModule } from '@nestjs-redisx/core';
import { CachePlugin, Cached } from '@nestjs-redisx/cache';
import { ConfigModule, ConfigService } from '@nestjs/config';

// 1. Register
@Module({
  imports: [
    RedisModule.forRootAsync({
      imports: [ConfigModule],
      inject: [ConfigService],
      plugins: [
        CachePlugin.registerAsync({
          imports: [ConfigModule],
          inject: [ConfigService],
          useFactory: (config: ConfigService) => ({
            l1: { maxSize: config.get('CACHE_L1_MAX_SIZE', 1000) },
            l2: { defaultTtl: config.get('CACHE_L2_TTL', 3600) },
          }),
        }),
      ],
      useFactory: (config: ConfigService) => ({
        clients: {
          host: config.get('REDIS_HOST', 'localhost'),
          port: config.get('REDIS_PORT', 6379),
        },
      }),
    }),
  ],
})
export class AppModule {}

// 2. Use
@Injectable()
export class UserService {
  @Cached({ key: 'user:{0}', ttl: 300, tags: ['users'] })
  async getUser(id: string) { return this.repo.findById(id); }
}

Plugins

Plugin	Description	Version
@nestjs-redisx/core	Driver abstraction, plugin system, multi-client support
@nestjs-redisx/cache	L1+L2 caching with SWR, stampede protection, tags
@nestjs-redisx/locks	Distributed locks with auto-renewal
@nestjs-redisx/rate-limit	Multi-algorithm rate limiting
@nestjs-redisx/circuit-breaker	Distributed circuit breaker (closed/open/half-open)
@nestjs-redisx/pubsub	Typed Pub/Sub with @Subscribe auto-discovery
@nestjs-redisx/session	Session store + device page, revocation, seat limits, lifetime cap
@nestjs-redisx/idempotency	Request deduplication and response replay
@nestjs-redisx/streams	Redis Streams with consumer groups and DLQ
@nestjs-redisx/metrics	Prometheus metrics for Redis operations
@nestjs-redisx/tracing	OpenTelemetry distributed tracing
@nestjs-redisx/testing	In-memory Redis driver for unit tests (no Redis required)

Comparison

	RedisX	@nestjs/cache-manager	@liaoliaots/nestjs-redis	ioredis
L1+L2 Cache	Yes	-	-	-
Stampede Protection	Yes	-	-	-
Distributed Locks	Yes	-	-	Manual
Rate Limiting	Yes	-	-	-
Circuit Breaker	Yes	-	-	-
Pub/Sub	Yes	-	-	Manual
Session Management	Yes	-	-	-
Idempotency	Yes	-	-	-
Prometheus + OTel	Yes	-	-	-

Full comparison

Documentation

Full documentation, guides, and API reference at nestjs-redisx.dev.

Sponsors

NestJS RedisX is free and open source. Development is supported by the community.

Become a Sponsor

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

Using with AI Assistants

For better code generation with AI tools (Cursor, Claude Code, GitHub Copilot, etc.), point your agent to the full API reference:

https://nestjs-redisx.dev/llms-full.txt

License

MIT