connect-redis

What is connect-redis?

The connect-redis npm package is a Redis session store for Express and Connect. It allows you to store session data in a Redis database, which can help with scaling applications by providing a centralized session store.

What are connect-redis's main functionalities?

Basic Setup

This code demonstrates how to set up a basic Express application with connect-redis as the session store. It configures the session middleware to use Redis for storing session data.

const session = require('express-session');
const RedisStore = require('connect-redis')(session);
const express = require('express');
const app = express();

app.use(session({
  store: new RedisStore({
    host: 'localhost',
    port: 6379
  }),
  secret: 'your secret',
  resave: false,
  saveUninitialized: false
}));

app.get('/', (req, res) => {
  res.send('Hello World!');
});

app.listen(3000, () => {
  console.log('Server is running on port 3000');
});

Custom Redis Client

This code demonstrates how to use a custom Redis client with connect-redis. This can be useful if you need to configure the Redis client with specific options or use an existing Redis client instance.

const session = require('express-session');
const RedisStore = require('connect-redis')(session);
const express = require('express');
const redis = require('redis');
const app = express();

const redisClient = redis.createClient({
  host: 'localhost',
  port: 6379
});

app.use(session({
  store: new RedisStore({ client: redisClient }),
  secret: 'your secret',
  resave: false,
  saveUninitialized: false
}));

app.get('/', (req, res) => {
  res.send('Hello World!');
});

app.listen(3000, () => {
  console.log('Server is running on port 3000');
});

Advanced Configuration

This code demonstrates advanced configuration options for connect-redis, such as setting the time-to-live (ttl) for sessions and enabling error logging.

const session = require('express-session');
const RedisStore = require('connect-redis')(session);
const express = require('express');
const app = express();

app.use(session({
  store: new RedisStore({
    host: 'localhost',
    port: 6379,
    ttl: 260,
    logErrors: true
  }),
  secret: 'your secret',
  resave: false,
  saveUninitialized: false
}));

app.get('/', (req, res) => {
  res.send('Hello World!');
});

app.listen(3000, () => {
  console.log('Server is running on port 3000');
});

Other packages similar to connect-redis

express-session

express-session is a general-purpose session middleware for Express. It supports various session stores, including in-memory, file-based, and database-backed stores. Unlike connect-redis, it does not provide a Redis-specific store out of the box but can be extended with other packages.

connect-mongo

connect-mongo is a MongoDB session store for Express and Connect. It provides similar functionality to connect-redis but uses MongoDB as the backend store instead of Redis. It is useful for applications that already use MongoDB and want to keep session data in the same database.

express-mysql-session

express-mysql-session is a MySQL session store for Express. It provides similar functionality to connect-redis but uses MySQL as the backend store. It is useful for applications that use MySQL and want to store session data in a relational database.

README

connect-redis provides Redis session storage for Express.

Installation

connect-redis requires express-session to installed and one of the following compatible Redis clients:

• redis
• ioredis

Install with redis:

npm install redis connect-redis express-session

Install with ioredis:

npm install ioredis connect-redis express-session

Importing

connect-redis supports both CommonJS (require) and ESM (import) modules.

Import using ESM/Typescript:

import RedisStore from "connect-redis"

Require using CommonJS:

const RedisStore = require("connect-redis").default

API

Full setup using redis package:

import RedisStore from "connect-redis"
import session from "express-session"
import {createClient} from "redis"

// Initialize client.
let redisClient = createClient()
redisClient.connect().catch(console.error)

// Initialize store.
let redisStore = new RedisStore({
  client: redisClient,
  prefix: "myapp:",
})

// Initialize sesssion storage.
app.use(
  session({
    store: redisStore,
    resave: false, // required: force lightweight session keep alive (touch)
    saveUninitialized: false, // recommended: only save session when data exists
    secret: "keyboard cat",
  })
)

RedisStore(options)

Options

client

An instance of redis or ioredis.

prefix

Key prefix in Redis (default: sess:).

Note: This prefix appends to whatever prefix you may have set on the client itself.

Note: You may need unique prefixes for different applications sharing the same Redis instance. This limits bulk commands exposed in express-session (like length, all, keys, and clear) to a single application's data.

ttl

If the session cookie has a expires date, connect-redis will use it as the TTL.

Otherwise, it will expire the session using the ttl option (default: 86400 seconds or one day).

Note: The TTL is reset every time a user interacts with the server. You can disable this behavior in some instances by using disableTouch.

Note: express-session does not update expires until the end of the request life cycle. Calling session.save() manually beforehand will have the previous value.

disableTouch

Disables resetting the TTL when using touch (default: false)

The express-session package uses touch to signal to the store that the user has interacted with the session but hasn't changed anything in its data. Typically, this helps keep the users session alive if session changes are infrequent but you may want to disable it to cut down the extra calls or to prevent users from keeping sessions open too long. Also consider enabling if you store a lot of data on the session.

Ref: https://github.com/expressjs/session#storetouchsid-session-callback

disableTTL

Disables key expiration completely (default: false)

This option disables key expiration requiring the user to manually manage key cleanup outside of connect-redis. Only use if you know what you are doing and have an exceptional case where you need to manage your own expiration in Redis.

Note: This has no effect on express-session setting cookie expiration.

serializer

Provide a custom encoder/decoder to use when storing and retrieving session data from Redis (default: JSON.parse and JSON.stringify).

interface Serializer {
  parse(string): object
  stringify(object): string
}

scanCount

Value used for count parameter in Redis SCAN command. Used for ids() and all() methods (default: 100).

FAQ

How to log Redis errors?

client.on("error", console.error)

How do I handle lost connections to Redis?

By default, the Redis client will auto-reconnect on lost connections. But requests may come in during that time. In Express, one way you can handle this scenario is including a "session check":

app.use(session(/* setup session here */))
app.use(function (req, res, next) {
  if (!req.session) {
    return next(new Error("oh no")) // handle error
  }
  next() // otherwise continue
})

If you want to retry, here is another option.