egg-redis

library2.6.1jsnpmunverified

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.

database

npm install egg-redis

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · EGG-REDIS

egg-redis

databasejavascriptv2.6.1

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

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

egg-redis plugin (configured, not directly imported)

✓ // In config/plugin.js: exports.redis = { enable: true, package: 'egg-redis' };

✗ const redis = require('egg-redis');

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.

app.redis

✓ await app.redis.get('key');

✗ const redis = app.redis; redis.get('key'); // Missing await

app.redis is available after plugin is enabled. All ioredis commands return promises; use await or .then().

config.redis.client

✓ // config/config.default.js config.redis = { client: { host: '127.0.0.1', port: 6379, password: 'auth' } };

✗ config.redis = { host: '127.0.0.1', port: 6379 }; // Must wrap in client object

For single client, the configuration must be under config.redis.client. For multi clients, use config.redis.clients.

Basic setup of egg-redis plugin: install, enable, configure single client, and use in a controller with set/get.

// 1. Install // npm i egg-redis --save // 2. Enable plugin: config/plugin.js exports.redis = { enable: true, package: 'egg-redis', }; // 3. Set config: config/config.default.js exports.redis = { client: { host: '127.0.0.1', port: 6379, password: process.env.REDIS_PASSWORD ?? '', db: 0, }, }; // 4. Use in controller/service 'use strict'; const Controller = require('egg').Controller; class HomeController extends Controller { async index() { const { ctx, app } = this; await app.redis.set('foo', 'bar'); const value = await app.redis.get('foo'); ctx.body = value; // 'bar' } } module.exports = HomeController;

Debug

Known issues

gotchaDirect import of egg-redis module in application code will not work.

fix

Do not require/import egg-redis directly. Enable it in config/plugin.js and use app.redis.

affects: >=0.0.0

gotchaConfiguration object must be nested under client or clients; flat properties are ignored.

fix

Use config.redis = { client: { host, port, ... } } for single client, or config.redis = { clients: { instanceName: { ... } } } for multi clients.

affects: >=0.0.0

gotchaIf Redis password is not set, omitting password may cause connection failure depending on Redis server config.

fix

Set password to null explicitly if no auth is needed (e.g., password: null).

affects: >=0.0.0

deprecatedioredis v4 is the default; future versions may upgrade to ioredis v5 which has breaking changes.

fix

To use a custom ioredis version, set config.redis.Redis = require('ioredis') with the desired version.

affects: >=2.0.0 <3.0.0

gotchaUsing weakDependent: true may hide connection errors at startup; app may start with broken Redis.

fix

Only use weakDependent when Redis is truly optional. Otherwise ensure Redis is reachable.

affects: >=2.0.0

Errors

Common errors & fixes

Error: Can not find module 'egg-redis'

egg-redis not installed or not listed in package.json dependencies.

fix

Run npm install egg-redis --save and ensure it is in dependencies.

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

Redis server is not running or host/port are incorrect.

fix

Start Redis server (e.g., redis-server) or verify host/port in config.

TypeError: app.redis.get is not a function

egg-redis plugin not properly enabled or configured, so app.redis is undefined.

fix

Check config/plugin.js: exports.redis = { enable: true, package: 'egg-redis' }; and verify config/config.default.js has valid redis client config.

Error: Cannot find module 'ioredis'

ioredis not installed automatically; egg-redis has ioredis as a peer or dependency, but may be missing.

fix

Run npm install ioredis --save (or reinstall egg-redis).

Upgrade

Version history

2.6.1latest on npm

Audit

Dependencies

ioredisrequiredCore Redis client driver; egg-redis wraps ioredis and delegates all commands to it.

Agent activity

11 hits · last 30 days

node

Resources

githubhttps://github.com/eggjs/redis ↗

packageegg-redis ↗

homepagehttps://github.com/eggjs/redis#readme ↗