{"id":18476,"library":"koa-redis","title":"koa-redis","description":"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.","status":"active","version":"4.0.1","language":"javascript","source_language":"en","source_url":"https://github.com/koajs/koa-redis","tags":["javascript","cache","caching","client","clients","cluster","clustering","clusters","express"],"install":[{"cmd":"npm install koa-redis","lang":"bash","label":"npm"},{"cmd":"yarn add koa-redis","lang":"bash","label":"yarn"},{"cmd":"pnpm add koa-redis","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"peer dependency; required for Redis connections (v4+ uses ioredis exclusively)","package":"ioredis","optional":false},{"reason":"recommended session middleware for Koa; koa-redis is a store for it","package":"koa-generic-session","optional":true}],"imports":[{"note":"Package exports a default function; in CommonJS, use require('koa-redis').default or set type: module.","wrong":"const redisStore = require('koa-redis')","symbol":"default","correct":"import redisStore from 'koa-redis'"},{"note":"In CommonJS, require returns the default function. ESM import default is required.","wrong":"import { redisStore } from 'koa-redis'","symbol":"redisStore","correct":"const redisStore = require('koa-redis')"},{"note":"koa-redis is the store, not the session middleware. You must use koa-generic-session separately.","wrong":"const session = require('koa-redis')","symbol":"session","correct":"const session = require('koa-generic-session')"}],"quickstart":{"code":"const Koa = require('koa');\nconst session = require('koa-generic-session');\nconst redisStore = require('koa-redis');\nconst app = new Koa();\napp.keys = ['secret', 'keys'];\napp.use(session({\n  store: redisStore({\n    host: process.env.REDIS_HOST || '127.0.0.1',\n    port: parseInt(process.env.REDIS_PORT || '6379'),\n    db: 0\n  })\n}));\napp.use((ctx) => {\n  ctx.session.count = (ctx.session.count || 0) + 1;\n  ctx.body = `Visited ${ctx.session.count} times`;\n});\napp.listen(3000);","lang":"javascript","description":"Sets up a Koa app with session stored in Redis using koa-redis store."},"warnings":[{"fix":"Update redis options to ioredis format (e.g., 'host' instead of 'hostname', no 'auth_pass'—use 'password').","message":"v4.0.0 switched from node_redis to ioredis. All Redis client options must follow ioredis API, not node_redis.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"Install koa-generic-session and pass it as shown in usage examples.","message":"In v4.0.0, the module no longer includes a built-in session middleware. You must use koa-generic-session separately.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"Remove 'parser' option; configure cookies via koa-generic-session options.","message":"v4.0.0 removed the 'parser' option and no longer supports cookies directly. Sessions are entirely handled by koa-generic-session.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"Remove 'isRedisCluster' and provide 'nodes' and 'clusterOptions' instead.","message":"The 'isRedisCluster' option is deprecated in favor of using the 'nodes' and 'clusterOptions' keys to auto-detect cluster mode.","severity":"deprecated","affected_versions":">=4.0.0"},{"fix":"Use either 'url' or individual host/port/db options, not both.","message":"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.","severity":"gotcha","affected_versions":">=4.0.0"},{"fix":"Set ttl in the store options: redisStore({ ttl: 3600 }) for 1 hour.","message":"The default TTL for sessions is 86400 seconds (1 day) unless overridden. If your sessions expire unexpectedly, check the ttl option.","severity":"gotcha","affected_versions":"all"},{"fix":"Pass retryStrategy as part of redisOptions in clusterOptions.","message":"This package uses ioredis, which by default retries connections on failure. In cluster mode, retry may cause delays. Set retryStrategy if needed.","severity":"gotcha","affected_versions":">=4.0.0"}],"env_vars":null,"last_verified":"2026-04-25T00:00:00.000Z","next_check":"2026-07-24T00:00:00.000Z","problems":[{"fix":"npm install ioredis","cause":"ioredis is a peer dependency not installed automatically.","error":"Error: Cannot find module 'ioredis'"},{"fix":"In CommonJS: const redisStore = require('koa-redis'); In ESM: import redisStore from 'koa-redis';","cause":"Using ESM import incorrectly or requiring wrong export.","error":"TypeError: redisStore is not a function"},{"fix":"npm install koa-generic-session and add const session = require('koa-generic-session');","cause":"Forgot to install and require koa-generic-session.","error":"TypeError: session is not a function"},{"fix":"Add isRedisCluster: true or provide nodes and clusterOptions in the store config.","cause":"Using cluster mode without setting 'isRedisCluster' or 'nodes' options.","error":"ReplyError: MOVED ..."},{"fix":"Start Redis server or check host/port settings.","cause":"Redis server is not running or not accessible at the specified host/port.","error":"Error: Redis connection to 127.0.0.1:6379 failed - connect ECONNREFUSED"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}