Redis is a high-performance in-memory data store widely used for caching, session management, message queues, and more.

@eggjs/redis

The framework provides the @eggjs/redis plugin to access Redis. This plugin is based on ioredis and supports single client, multi-client, and cluster modes.

Installation and Configuration

Install the plugin:

npm i @eggjs/redis

Enable the plugin:

// config/plugin.ts
export default {
  redis: {
    enable: true,
    package: '@eggjs/redis',
  },
};

Single Client

// config/config.default.ts
export default function () {
  return {
    redis: {
      client: {
        host: '127.0.0.1',
        port: 6379,
        password: '',
        db: 0,
      },
    },
  };
}

Multi Client

// config/config.default.ts
export default function () {
  return {
    redis: {
      clients: {
        cache: {
          host: '127.0.0.1',
          port: 6379,
          password: '',
          db: 0,
        },
        session: {
          host: '127.0.0.1',
          port: 6379,
          password: '',
          db: 1,
        },
      },
    },
  };
}

Cluster Mode

// config/config.default.ts
export default function () {
  return {
    redis: {
      client: {
        cluster: true,
        nodes: [
          { host: '127.0.0.1', port: 6380 },
          { host: '127.0.0.1', port: 6381 },
        ],
      },
    },
  };
}

Usage

Single Client

// app/controller/home.ts
import { Context } from 'egg';

export default class HomeController {
  async index(ctx: Context) {
    // set a value
    await ctx.app.redis.set('foo', 'bar');

    // get a value
    const value = await ctx.app.redis.get('foo');

    // set with expiration (seconds)
    await ctx.app.redis.setex('temp', 60, 'expires in 60s');

    // delete a key
    await ctx.app.redis.del('foo');

    ctx.body = value;
  }
}

Multi Client

When using multi-client mode, access each client via app.redis.getSingletonInstance('clientName'):

// app/controller/home.ts
import { Context } from 'egg';

export default class HomeController {
  async index(ctx: Context) {
    const cache = ctx.app.redis.getSingletonInstance('cache');
    const session = ctx.app.redis.getSingletonInstance('session');

    await cache.set('key', 'value');
    await session.set('sid', 'session-data');

    ctx.body = await cache.get('key');
  }
}

Common Commands

The plugin supports all ioredis commands. Here are some commonly used ones:

Command	Description	Example
set	Set a key-value pair	await redis.set('key', 'value')
get	Get a value by key	await redis.get('key')
setex	Set with expiration (seconds)	await redis.setex('key', 60, 'value')
del	Delete a key	await redis.del('key')
incr	Increment a number	await redis.incr('counter')
hset	Set a hash field	await redis.hset('hash', 'field', 'value')
hget	Get a hash field	await redis.hget('hash', 'field')
lpush	Push to a list	await redis.lpush('list', 'value')
lpop	Pop from a list	await redis.lpop('list')
sadd	Add to a set	await redis.sadd('set', 'member')
smembers	Get all set members	await redis.smembers('set')
zadd	Add to a sorted set	await redis.zadd('zset', 1, 'member')

Using ioredis-mock for Unit Tests

You can use ioredis-mock to replace the real Redis client in unit tests. This eliminates the need for a running Redis server during testing.

Install

npm i --save-dev ioredis-mock @types/ioredis-mock

Configure

// config/config.unittest.ts
import RedisMock from 'ioredis-mock';
import type { EggAppInfo, PartialEggConfig } from 'egg';

export default function (_appInfo: EggAppInfo): PartialEggConfig {
  return {
    redis: {
      Redis: RedisMock,
      client: {
        host: '127.0.0.1',
        port: 6379,
        password: '',
        db: 0,
        weakDependent: true,
      },
    },
  };
}

Important: You must set weakDependent: true when using ioredis-mock. Mock clients emit the ready event synchronously during construction, before the plugin's listener is attached. Without weakDependent: true, the app will hang on startup.

Benefits

• Faster CI: No need to spin up Redis Docker containers
• Simpler local dev: No Redis server required for running tests
• Isolated: Each test worker gets its own in-memory Redis instance
• Compatible: Supports most common Redis commands

Note: For production deployment testing, you should still use a real Redis server.

Advanced Configuration

Weak Dependent

If your application can start without Redis being ready (e.g., Redis is used as a cache and is not critical):

// config/config.default.ts
export default function () {
  return {
    redis: {
      client: {
        host: '127.0.0.1',
        port: 6379,
        password: '',
        db: 0,
        weakDependent: true, // app start won't wait for Redis to be ready
      },
    },
  };
}

Using Valkey

Valkey is a Redis-compatible fork. You can use it with the Redis config option:

import Valkey from 'iovalkey';

export default function () {
  return {
    redis: {
      Redis: Valkey,
      client: {
        host: '127.0.0.1',
        port: 6379,
        password: '',
        db: 0,
      },
    },
  };
}