Compatibility Matrix
Support Tiers
- Supported — Tested in CI matrix, bugs are treated as high priority
- Best effort — May work, not tested in CI, community PRs accepted
- Not supported — Known incompatibilities, not planned
Runtime Compatibility
| Node 18 | Node 20 | Node 22 | |
|---|---|---|---|
| NestJS 12 | Not supported¹ | Supported | Supported |
| NestJS 11 | Supported | Supported | Best effort |
| NestJS 10 | Supported | Supported | Best effort |
| NestJS 9 | Best effort | Best effort | Not supported |
¹ NestJS 12 itself requires Node ≥ 20 (engines).
NestJS 9 is EOL and not covered by CI. It may work but is best-effort only.
NestJS 12 and ESM
NestJS 12 is published as native ESM. All RedisX packages ship a dual build: import resolves the ESM bundle (dist/index.mjs), require the CommonJS one (dist/index.js), each with matching type declarations. An ESM application ("type": "module") works out of the box; a CommonJS application on Nest 12 relies on Node's require(esm) support (Node 20.19+ / 22.12+). Jest users on Nest 12 should run Jest in ESM mode — its CJS module registry cannot require() the ESM Nest internals.
Redis Compatibility
| Redis 6.2 | Redis 7.x | |
|---|---|---|
| Standalone | Supported | Supported |
| Sentinel | Supported | Supported |
| Cluster | Supported | Supported |
Redis 6.2 is the minimum version required for Lua scripting features used by locks, rate-limit, and idempotency packages.
Driver Compatibility
| Driver | Status | Notes |
|---|---|---|
| ioredis (recommended) | Supported | Primary driver, most tested |
| node-redis | Supported | Feature parity for supported topologies via driver abstraction |
ioredis is the recommended driver due to mature Cluster and Sentinel support and wider community adoption. The driver abstraction layer provides feature parity for supported topologies. For Docker Sentinel behind NAT, ioredis is recommended.
Peer Dependencies
| Dependency | Minimum | Recommended |
|---|---|---|
| Node.js | 18.0.0 | 20.x LTS |
| @nestjs/common | 10.0.0 | 11.x / 12.x |
| @nestjs/core | 10.0.0 | 11.x / 12.x |
| ioredis | 5.0.0 | 5.9+ |
| redis (node-redis) | 4.6.0 | 4.7+ |
| reflect-metadata | 0.2.0 | 0.2.x |
| rxjs | 7.8.0 | 7.8+ |
Plugin-Specific Dependencies
Plugin packages additionally require @nestjs-redisx/core as a peer dependency.
| Plugin | Extra Dependencies |
|---|---|
| metrics | prom-client as a peer dependency (auto-installed by npm 7+ / pnpm 8+; yarn classic users add it manually) |
| tracing | @opentelemetry/api + bundled OTel SDK packages, loaded only when the plugin sets up its own provider (i.e. when the application has no registered tracer provider) |
All other plugins (cache, locks, rate-limit, idempotency, streams) have no additional production dependencies beyond core and NestJS.
Known Limitations
- Redis Cluster requires Redis 6.2+ and at least 3 master nodes
- Redis Sentinel requires Redis 6.2+ with a sentinel-aware topology
- Lua scripts used by locks, rate-limit, and idempotency require Redis 6.2+ for
EVALSHAwith script preloading - node-redis Sentinel support is limited compared to ioredis
- Redis Cluster multi-key commands require hash tags
{...}to avoid CROSSSLOT errors - Lua scripts in Cluster must operate on keys within the same hash slot (RedisX uses hash tags for this)