Redis Store for Express Rate Limit

Common errors

• TypeError: client.connect is not a function

  cause The `node-redis` client (created with `createClient()`) requires an explicit `await client.connect()` call before it can be used to send commands.
  fix Ensure you call `await client.connect()` after creating your Redis client instance and before passing it to the `RedisStore` constructor.

• Error: require() of ES Module ... not supported.

• SyntaxError: Cannot use import statement outside a module

  cause This error typically occurs when mixing CommonJS (`require`) and ES Module (`import`) syntax, or when an ES Module is imported in a CommonJS context without proper transpilation or configuration.
  fix For ES Modules, set `"type": "module"` in your `package.json` and use `import`. For CommonJS, ensure `"type": "commonjs"` (or no `type` field) and use `require()`. Ensure bundlers or TypeScript configurations handle module resolution correctly.

• Argument of type '(command: string, ...args: string[]) => Promise<RedisReply>' is not assignable to parameter of type '(...args: string[]) => number | Promise<number>'

  cause When using TypeScript, the `sendCommand` function in `RedisStore` expects a return type of `Promise<number>` or `number`. If your Redis client's command function returns a different type (e.g., `Promise<RedisReply>` from `ioredis`'s `call` method), a type mismatch occurs.
  fix Adjust the `sendCommand` function's signature or cast its return value to `Promise<number>` or `number` to match the expected type. For `ioredis`, you might cast `client.call(...) as Promise<number>`.

• TypeError: Cannot read properties of undefined (reading 'sendCommand')

  cause The `sendCommand` function was not correctly provided or it's attempting to access a method on an uninitialized or incorrectly configured Redis client instance within the `RedisStore` options.
  fix Verify that your Redis client object is properly initialized and connected, and that the `sendCommand` function within `RedisStore`'s options correctly references a valid command sending method on that client (e.g., `client.sendCommand(args)` or `client.call(command, ...args)`).

Warnings

• breaking Version 4.0.0 dropped support for Node.js 14. Projects must now use Node.js 16 or newer to ensure compatibility.
  Fix: Upgrade your Node.js runtime environment to version 16 or later.
• breaking Version 4.0.0 introduced support for `express-rate-limit` v7. Ensure your `express-rate-limit` dependency is updated to a compatible version (v7 or higher) to avoid potential issues.
  Fix: Update your `express-rate-limit` package to version 7 or newer in your project's dependencies.
• gotcha This package requires a Redis server version 2.6.12 or above. Using an older Redis version may lead to unexpected behavior or errors.
  Fix: Ensure your Redis server instance is running version 2.6.12 or newer.
• gotcha Prior to v4.1.1, the `store.get()` function would return `NaN` if no hits were stored for a client, instead of the expected `0`. This could cause issues in logic dependent on the return value.
  Fix: Upgrade to version 4.1.1 or later to ensure `store.get()` consistently returns `0` when no hits are recorded for a client.

Install

• npm install rate-limit-redis npm
• yarn add rate-limit-redis yarn
• pnpm add rate-limit-redis pnpm

Imports

• RedisStore
  wrong:

  const RedisStore = require('rate-limit-redis').RedisStore

  correct:

  import { RedisStore } from 'rate-limit-redis'

  For CommonJS projects, use `const { RedisStore } = require('rate-limit-redis')`. This package provides both ESM and CJS builds.
• RedisStore

  import type { RedisStore } from 'rate-limit-redis'

  When using TypeScript, import the type explicitly for type safety in store configurations.
• RedisReply

  import type { RedisReply } from 'rate-limit-redis'

  This type is often used in TypeScript projects when configuring the `sendCommand` function for clients like `ioredis` to correctly type the return promise.

Quickstart

Demonstrates setting up an Express application with rate limiting using Redis as a store, configured with the node-redis client. It connects to Redis and applies the rate limiter to all routes.

import { rateLimit } from 'express-rate-limit';
import { RedisStore } from 'rate-limit-redis';
import { createClient } from 'redis';
import express from 'express';

const app = express();

async function setupRateLimiter() {
  // Create a `node-redis` client
  const client = createClient({
    url: process.env.REDIS_URL ?? 'redis://localhost:6379'
  });

  // Then connect to the Redis server
  client.on('error', (err) => console.error('Redis Client Error', err));
  await client.connect();
  console.log('Connected to Redis');

  // Create and use the rate limiter
  const limiter = rateLimit({
    windowMs: 15 * 60 * 1000, // 15 minutes
    max: 100, // Limit each IP to 100 requests per window
    standardHeaders: true, // Return rate limit info in the `RateLimit-*` headers
    legacyHeaders: false, // Disable the `X-RateLimit-*` headers

    // Redis store configuration
    store: new RedisStore({
      sendCommand: (...args: string[]) => client.sendCommand(args),
    }),
  });

  app.use(limiter);

  app.get('/', (req, res) => {
    res.send('Hello, you are rate-limited!');
  });

  const PORT = process.env.PORT || 3000;
  app.listen(PORT, () => {
    console.log(`Server running on http://localhost:${PORT}`);
  });
}

setupRateLimiter().catch(console.error);