koa-redis

4.0.1 verified Sat Apr 25 auth: no javascript

Redis storage for Koa session middleware/cache with Sentinel and Cluster support, version 4.0.1. This package provides a session store for koa-generic-session using Redis, built on ioredis. v4 rewrite added Sentinel and Cluster support, switched from node_redis to ioredis, and requires ioredis as a peer dependency. Release cadence is sporadic; last release was in 2020. Key differentiator: native support for Redis Sentinel and Cluster via ioredis, unlike earlier versions or other Redis session stores.

Common errors

error Error: Cannot find module 'ioredis' ↓

cause ioredis is a peer dependency not installed automatically.

fix

npm install ioredis

error TypeError: redisStore is not a function ↓

cause Using ESM import incorrectly or requiring wrong export.

fix

In CommonJS: const redisStore = require('koa-redis'); In ESM: import redisStore from 'koa-redis';

error TypeError: session is not a function ↓

cause Forgot to install and require koa-generic-session.

fix

npm install koa-generic-session and add const session = require('koa-generic-session');

error ReplyError: MOVED ... ↓

cause Using cluster mode without setting 'isRedisCluster' or 'nodes' options.

fix

Add isRedisCluster: true or provide nodes and clusterOptions in the store config.

error Error: Redis connection to 127.0.0.1:6379 failed - connect ECONNREFUSED ↓

cause Redis server is not running or not accessible at the specified host/port.

fix

Start Redis server or check host/port settings.

Warnings

breaking v4.0.0 switched from node_redis to ioredis. All Redis client options must follow ioredis API, not node_redis. ↓

fix Update redis options to ioredis format (e.g., 'host' instead of 'hostname', no 'auth_pass'—use 'password').

breaking In v4.0.0, the module no longer includes a built-in session middleware. You must use koa-generic-session separately. ↓

fix Install koa-generic-session and pass it as shown in usage examples.

breaking v4.0.0 removed the 'parser' option and no longer supports cookies directly. Sessions are entirely handled by koa-generic-session. ↓

fix Remove 'parser' option; configure cookies via koa-generic-session options.

deprecated The 'isRedisCluster' option is deprecated in favor of using the 'nodes' and 'clusterOptions' keys to auto-detect cluster mode. ↓

fix Remove 'isRedisCluster' and provide 'nodes' and 'clusterOptions' instead.

gotcha The 'url' option is forwarded to ioredis, but if you provide both 'url' and other connection options (host, port), the 'url' takes precedence and other options are ignored. ↓

fix Use either 'url' or individual host/port/db options, not both.

gotcha The default TTL for sessions is 86400 seconds (1 day) unless overridden. If your sessions expire unexpectedly, check the ttl option. ↓

fix Set ttl in the store options: redisStore({ ttl: 3600 }) for 1 hour.

gotcha This package uses ioredis, which by default retries connections on failure. In cluster mode, retry may cause delays. Set retryStrategy if needed. ↓

fix Pass retryStrategy as part of redisOptions in clusterOptions.

Install

npm install koa-redis

yarn add koa-redis

pnpm add koa-redis

Imports

default
wrong
```
const redisStore = require('koa-redis')
```
correct
```
import redisStore from 'koa-redis'
```
Package exports a default function; in CommonJS, use require('koa-redis').default or set type: module.
redisStore
wrong
```
import { redisStore } from 'koa-redis'
```
correct
```
const redisStore = require('koa-redis')
```
In CommonJS, require returns the default function. ESM import default is required.
session
wrong
```
const session = require('koa-redis')
```
correct
```
const session = require('koa-generic-session')
```
koa-redis is the store, not the session middleware. You must use koa-generic-session separately.

Quickstart

Sets up a Koa app with session stored in Redis using koa-redis store.

const Koa = require('koa');
const session = require('koa-generic-session');
const redisStore = require('koa-redis');
const app = new Koa();
app.keys = ['secret', 'keys'];
app.use(session({
  store: redisStore({
    host: process.env.REDIS_HOST || '127.0.0.1',
    port: parseInt(process.env.REDIS_PORT || '6379'),
    db: 0
  })
}));
app.use((ctx) => {
  ctx.session.count = (ctx.session.count || 0) + 1;
  ctx.body = `Visited ${ctx.session.count} times`;
});
app.listen(3000);