{"id":44820,"library":"egg-redis","title":"egg-redis","description":"Egg.js plugin providing Redis client integration via ioredis. Current version 2.6.1, supports Node >= 6.0.0 and Egg.js applications. Enables single or multiple Redis clients, Sentinel support, and custom ioredis versions. Primarily maintained by the Egg.js core team with monthly releases. Key differentiator: seamless integration with Egg.js lifecycle, supports weakDependent option to not block app startup, and enables per-client configuration. Based on ioredis, so all ioredis features (cluster, pipelining, etc.) are available.","status":"active","version":"2.6.1","language":"javascript","source_language":"en","source_url":"https://github.com/eggjs/redis","tags":["javascript","egg","eggPlugin","egg-plugin","redis","database","typescript"],"install":[{"cmd":"npm install egg-redis","lang":"bash","label":"npm"},{"cmd":"yarn add egg-redis","lang":"bash","label":"yarn"},{"cmd":"pnpm add egg-redis","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core Redis client driver; egg-redis wraps ioredis and delegates all commands to it.","package":"ioredis","optional":false}],"imports":[{"note":"egg-redis is a plugin, not a direct dependency. Do not require/import it in application code. Instead enable it in Egg.js plugin config and use app.redis.","wrong":"const redis = require('egg-redis');","symbol":"egg-redis plugin (configured, not directly imported)","correct":"// In config/plugin.js:\nexports.redis = { enable: true, package: 'egg-redis' };"},{"note":"app.redis is available after plugin is enabled. All ioredis commands return promises; use await or .then().","wrong":"const redis = app.redis;\nredis.get('key'); // Missing await","symbol":"app.redis","correct":"await app.redis.get('key');"},{"note":"For single client, the configuration must be under config.redis.client. For multi clients, use config.redis.clients.","wrong":"config.redis = { host: '127.0.0.1', port: 6379 }; // Must wrap in client object","symbol":"config.redis.client","correct":"// config/config.default.js\nconfig.redis = {\n  client: { host: '127.0.0.1', port: 6379, password: 'auth' }\n};"}],"quickstart":{"code":"// 1. Install\n// npm i egg-redis --save\n\n// 2. Enable plugin: config/plugin.js\nexports.redis = {\n  enable: true,\n  package: 'egg-redis',\n};\n\n// 3. Set config: config/config.default.js\nexports.redis = {\n  client: {\n    host: '127.0.0.1',\n    port: 6379,\n    password: process.env.REDIS_PASSWORD ?? '',\n    db: 0,\n  },\n};\n\n// 4. Use in controller/service\n'use strict';\n\nconst Controller = require('egg').Controller;\n\nclass HomeController extends Controller {\n  async index() {\n    const { ctx, app } = this;\n    await app.redis.set('foo', 'bar');\n    const value = await app.redis.get('foo');\n    ctx.body = value; // 'bar'\n  }\n}\n\nmodule.exports = HomeController;\n","lang":"javascript","description":"Basic setup of egg-redis plugin: install, enable, configure single client, and use in a controller with set/get."},"warnings":[{"fix":"Do not require/import egg-redis directly. Enable it in config/plugin.js and use app.redis.","message":"Direct import of egg-redis module in application code will not work.","severity":"gotcha","affected_versions":">=0.0.0"},{"fix":"Use config.redis = { client: { host, port, ... } } for single client, or config.redis = { clients: { instanceName: { ... } } } for multi clients.","message":"Configuration object must be nested under client or clients; flat properties are ignored.","severity":"gotcha","affected_versions":">=0.0.0"},{"fix":"Set password to null explicitly if no auth is needed (e.g., password: null).","message":"If Redis password is not set, omitting password may cause connection failure depending on Redis server config.","severity":"gotcha","affected_versions":">=0.0.0"},{"fix":"To use a custom ioredis version, set config.redis.Redis = require('ioredis') with the desired version.","message":"ioredis v4 is the default; future versions may upgrade to ioredis v5 which has breaking changes.","severity":"deprecated","affected_versions":">=2.0.0 <3.0.0"},{"fix":"Only use weakDependent when Redis is truly optional. Otherwise ensure Redis is reachable.","message":"Using weakDependent: true may hide connection errors at startup; app may start with broken Redis.","severity":"gotcha","affected_versions":">=2.0.0"}],"env_vars":null,"search_vec":"'2.6.1':14 '6.0.0':17 'app':56 'applic':20 'avail':75 'base':64 'block':55 'client':8,26,62 'cluster':71 'configur':63 'core':38 'current':12 'custom':30 'databas':83 'differenti':44 'egg':2,77,80 'egg-plugin':79 'egg-redi':1 'egg.js':4,19,37,48 'eggplugin':78 'enabl':21,59 'etc':73 'featur':70 'integr':9,46 'ioredi':11,31,66,69 'javascript':76 'key':43 'lifecycl':49 'maintain':34 'month':41 'multipl':24 'node':16 'option':52 'per':61 'per-client':60 'pipelin':72 'plugin':5,81 'primarili':33 'provid':6 'redi':3,7,25,82 'releas':42 'seamless':45 'sentinel':27 'singl':22 'startup':57 'support':15,28,50 'team':39 'typescript':84 'version':13,32 'via':10 'weakdepend':51","created_at":"2026-06-07T12:51:59.834392+00:00","updated_at":"2026-06-07T12:51:59.834392+00:00","problems":[{"fix":"Run npm install egg-redis --save and ensure it is in dependencies.","cause":"egg-redis not installed or not listed in package.json dependencies.","error":"Error: Can not find module 'egg-redis'"},{"fix":"Start Redis server (e.g., redis-server) or verify host/port in config.","cause":"Redis server is not running or host/port are incorrect.","error":"Error: Redis connection to 127.0.0.1:6379 failed - connect ECONNREFUSED"},{"fix":"Check config/plugin.js: exports.redis = { enable: true, package: 'egg-redis' }; and verify config/config.default.js has valid redis client config.","cause":"egg-redis plugin not properly enabled or configured, so app.redis is undefined.","error":"TypeError: app.redis.get is not a function"},{"fix":"Run npm install ioredis --save (or reinstall egg-redis).","cause":"ioredis not installed automatically; egg-redis has ioredis as a peer or dependency, but may be missing.","error":"Error: Cannot find module 'ioredis'"}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":null,"cli_version":null,"type":"library","homepage":"https://github.com/eggjs/redis#readme","github":"https://github.com/eggjs/redis","docs":null,"changelog":null,"pypi":null,"npm":"egg-redis","openapi_spec":null,"status_page":null,"smithery":null,"categories":["database"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-07","next_check":"2026-09-05","install_tag":null}}