Express Rate Limiting Middleware

Common errors

• TypeError: rateLimit is not a function

  cause Attempting to use `new rateLimit()` or incorrectly importing the function, especially in CommonJS where the default export might be expected directly.
  fix Ensure you are using named import: `import { rateLimit } from 'express-rate-limit'` for ESM, or `const { rateLimit } = require('express-rate-limit')` for CommonJS. Do not use `new` with `rateLimit`.

• Error: Store must be defined (if using a custom store with 'store' option)

  cause The `store` option was specified but its value was `undefined` or `null`, often due to an uninitialized external store instance.
  fix Ensure that the `store` option is provided with an instantiated store object, e.g., `store: new RedisStore({ client: redisClient })`.

• Rate limiting not being applied or not working as expected (e.g., still receiving 200 OK after many requests)

  cause The middleware might be applied globally when it should be route-specific, or vice-versa, or applied in the wrong order in your Express middleware chain.
  fix Verify that `app.use(limiter)` is called *before* the routes you intend to limit. If limiting specific routes, apply `app.get('/route', limiter, handler)` instead of globally. Check your `windowMs` and `limit` values are not excessively high.

Warnings

• breaking Version 8.0.0 introduced breaking changes. Specifically, the library shifted towards adhering more closely to IETF RateLimit header specifications. Review your configuration, especially `standardHeaders` and `legacyHeaders`.
  Fix: Consult the official changelog for v8.0.0. Update `standardHeaders` to 'draft-8' for the latest spec, or 'draft-6' for an older one. Set `legacyHeaders: false` to disable the deprecated `X-RateLimit-*` headers if not needed for backwards compatibility.
• gotcha By default, `express-rate-limit` uses a `MemoryStore`. In production environments with multiple Node.js instances or processes, this can lead to inconsistent rate limiting as each instance will have its own independent hit count.
  Fix: For production deployments, configure an external `store` like Redis or Memcached to ensure consistent rate limiting across all instances. Refer to the 'Data Stores' section in the documentation.
• gotcha The `ipv6Subnet` option is crucial for correctly identifying unique users on IPv6 networks. An incorrect setting can either be too aggressive (treating many users in a subnet as one) or too lenient (allowing more requests than intended).
  Fix: Carefully choose an appropriate `ipv6Subnet` value (e.g., 60 or 64 for typical home networks, 52 or 48 for more aggressive limiting) based on your network architecture and desired behavior. The default might not be suitable for all use cases.
• deprecated The traditional `X-RateLimit-*` headers are considered legacy. While still supported via the `legacyHeaders: true` option, the library encourages adoption of the IETF RateLimit header specification.
  Fix: Set `standardHeaders` to `'draft-8'` (or `'draft-6'/'draft-7'` if needed for older clients) and consider setting `legacyHeaders: false` to embrace the modern standard. Inform clients about the header change.

Install

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

Imports

• rateLimit
  wrong:

  const rateLimit = require('express-rate-limit')

  correct:

  import { rateLimit } from 'express-rate-limit'

  While CommonJS `require` still works, ESM `import` is the recommended and modern approach, especially for new projects. The package ships TypeScript types.
• RateLimitRequestHandler

  import { type RateLimitRequestHandler } from 'express-rate-limit'

  Type import for explicit TypeScript usage, enabling better type checking for middleware functions.
• MemoryStore
  wrong:

  import { Store } from 'express-rate-limit'

  correct:

  import { MemoryStore } from 'express-rate-limit'

  The default store is `MemoryStore`. If you need to explicitly reference or extend it, use `MemoryStore`. `Store` is an interface/abstract class.

Quickstart

This quickstart demonstrates how to set up a basic rate limit for all requests under '/api/' using the `rateLimit` middleware, configuring its window, limit, and modern headers.

import express from 'express';
import { rateLimit } from 'express-rate-limit';

const app = express();

// Configure the rate limiter: 100 requests per IP every 15 minutes.
const apiLimiter = rateLimit({
  windowMs: 15 * 60 * 1000, // 15 minutes
  limit: 100, // Max 100 requests per IP per window
  standardHeaders: 'draft-8', // Uses the latest IETF RateLimit header draft
  legacyHeaders: false, // Disables the older X-RateLimit-* headers
  message: 'Too many requests from this IP, please try again after 15 minutes.',
  // store: new RedisStore({ /* ... config ... */ }), // Example of an external store
});

// Apply the rate limiting middleware to all API requests
app.use('/api/', apiLimiter);

// A public route that is not rate-limited
app.get('/', (req, res) => {
  res.send('Welcome! This route is not rate-limited.');
});

// A rate-limited API endpoint
app.get('/api/data', (req, res) => {
  res.json({ message: 'This is some data.' });
});

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