connect-redis

connect-redis is a lightweight, single-purpose adapter that plugs Redis into express-session’s Store interface, giving Express applications persistent, shared session storage instead of the default in-memory store. It wraps a user-supplied node-redis client (standalone or cluster) and implements the full Store contract — get, set, destroy, touch, clear, length, ids, and all — with configurable TTL, key prefixing, and serialization.

Maintained by TJ Holowaychuk’s connect-redis project since 2010, it remains one of the most widely used session backends in the Node.js ecosystem, with the current major version targeting modern node-redis clients and current Node.js runtimes. It supports cluster-aware key scanning, dynamic TTL callbacks, and pluggable serializers, without bundling Redis as a direct dependency — the store is constructed once by the caller and handed straight to express-session.

What You Get

• A drop-in express-session Store implementation backed by Redis (standalone or Cluster clients)
• Automatic TTL management synced to the session cookie’s expiration, plus a custom TTL callback option
• Cluster-aware key scanning (SCAN) for ids(), all(), length(), and clear() across sharded Redis deployments
• Configurable key prefixing and pluggable serialization (defaults to JSON, swappable for custom encoders)

Common Use Cases

• Sharing session state across multiple Express server instances behind a load balancer
• Persisting sessions through server restarts and deploys instead of losing them with an in-memory store
• Isolating session keyspaces for multiple apps sharing one Redis instance via key prefixes
• Scaling session storage horizontally with Redis Cluster as traffic grows

Under The Hood

Architecture connect-redis is a single-class, single-file library: RedisStore extends express-session’s Store base class and implements the full storage contract (get/set/destroy/touch/clear/length/ids/all) directly against a Redis client the caller constructs and passes in. There’s no internal layering beyond that — each method computes a prefixed key, issues one or two Redis calls, and funnels results and errors through a shared callback helper that supports both promise-based and legacy Node-style callback consumers. Cluster support lives in a private scan-iterator method that detects a cluster-typed client at runtime and fans a SCAN out across every cluster node, otherwise delegating to the client’s own scan iterator. The design has no adapter layer insulating it from express-session’s Store contract, but that contract has been stable for a long time, keeping the practical coupling risk low.

Tech Stack The implementation is TypeScript in strict mode, targeting a modern ECMAScript version with bundler-style module resolution. The Redis client and express-session are both peer dependencies installed by the consumer rather than bundled, keeping the package thin. Builds run through Vite with a dts plugin to emit both ESM and CJS outputs alongside hand-copied type declaration files. Linting and formatting use a Rust-based toolchain in place of ESLint/Prettier, and tests run under Vitest with coverage reporting. CI runs the full lint, build, and test pipeline against a real, locally spawned Redis server across a matrix of current Node.js versions on every push and pull request.

Code Quality Tests are integration-style rather than mocked unit tests: a real Redis server process is spawned for the suite and every Store method is exercised against it, including a bulk load/clear pass, though the cluster-scanning branch itself has no dedicated automated coverage. Error handling is consistent across every method — Redis calls are wrapped in try/catch and errors are threaded through the shared callback helper so promise and callback consumers get identical error semantics without duplicated logic. Strict TypeScript settings catch unused locals and implicit-return bugs at compile time; the one meaningful type-safety compromise is an any-typed client option that is narrowed immediately inside the constructor. Naming is short and idiomatic, matching express-session’s own conventions. CI enforces type-checking, linting, formatting, and tests before merge.

API Design The public surface is a single exported class constructed with one options object and handed straight to express-session’s store option — genuinely minimal boilerplate to get started. Every method transparently supports both promise-based and legacy Node callback calling conventions via a shared helper, so it drops into either style without extra adapter code. Standalone-versus-cluster Redis clients are detected automatically at runtime, so callers don’t need a separate class or flag for Redis Cluster deployments. The configuration options (ttl, prefix, serializer, disableTTL, disableTouch, scanCount) map directly onto Redis-native concepts, keeping the mental model close to Redis itself rather than introducing new abstractions.