Modular Redis toolkit for NestJS with plugin architecture
Documentation • Getting Started • API Reference • Discussions
- Replace
cache-managerwith 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
- 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, NestJS 10/11, Redis 6.2/7.x
Testing details | Compatibility matrix
| 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 |
| 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 |
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); } }
| 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/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 |
| RedisX | @nestjs/cache-manager | @liaoliaots/nestjs-redis | ioredis | |
|---|---|---|---|---|
| L1+L2 Cache | Yes | - | - | - |
| Stampede Protection | Yes | - | - | - |
| Distributed Locks | Yes | - | - | Manual |
| Rate Limiting | Yes | - | - | - |
| Idempotency | Yes | - | - | - |
| Prometheus + OTel | Yes | - | - | - |
Full documentation, guides, and API reference at nestjs-redisx.dev.
NestJS RedisX is free and open source. Development is supported by the community.
Contributions are welcome! Please see CONTRIBUTING.md for guidelines.
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