Registry / database / koa-redis

koa-redis

JSON →
library4.0.1jsnpmunverified

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.

databaseweb-frameworkhttp-networking
npm install koa-redis
github ↗package ↗
INSTALL
IMPORT
SIG · KOA-REDIS
K
koa-redis
databasejavascriptv4.0.1
Install
—
Import
—
Disk
—
Pass rate
0/ 6
Env Coverage0 / 6
glibc
18–22
musl
18–22
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18–226 runs
build_error
glibc
node 18–226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

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

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);
Debug
Known issues
breakingv4.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').
affects: >=4.0.0
breakingIn 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.
affects: >=4.0.0
breakingv4.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.
affects: >=4.0.0
deprecatedThe '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.
affects: >=4.0.0
gotchaThe '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.
affects: >=4.0.0
gotchaThe 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.
affects: all
gotchaThis 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.
affects: >=4.0.0
Errors
Common errors & fixes
Error: Cannot find module 'ioredis'
ioredis is a peer dependency not installed automatically.
fix
npm install ioredis
TypeError: redisStore is not a function
Using ESM import incorrectly or requiring wrong export.
fix
In CommonJS: const redisStore = require('koa-redis'); In ESM: import redisStore from 'koa-redis';
TypeError: session is not a function
Forgot to install and require koa-generic-session.
fix
npm install koa-generic-session and add const session = require('koa-generic-session');
ReplyError: MOVED ...
Using cluster mode without setting 'isRedisCluster' or 'nodes' options.
fix
Add isRedisCluster: true or provide nodes and clusterOptions in the store config.
Error: Redis connection to 127.0.0.1:6379 failed - connect ECONNREFUSED
Redis server is not running or not accessible at the specified host/port.
fix
Start Redis server or check host/port settings.
Upgrade
Version history
4.0.1latest on npm
Audit
Dependencies
ioredisrequiredpeer dependency; required for Redis connections (v4+ uses ioredis exclusively)
koa-generic-sessionoptionalrecommended session middleware for Koa; koa-redis is a store for it
Agent activity
4 hits · last 30 days
node
4
Resources
githubhttps://github.com/koajs/koa-redis ↗
packagehttps://www.npmjs.com/package/koa-redis ↗