Basic Usage

Learn how to use the @perseidesjs/medusa-plugin-rate-limit plugin in your Medusa app

How to use

If you want to start restricting specific routes, you can import the RateLimit class from the plugin and then use it as follows:

src/api/middlewares.ts

import { defineMiddlewares } from "@medusajs/medusa"
import { RateLimit } from '@perseidesjs/medusa-plugin-rate-limit'
import { Modules } from "@medusajs/framework/utils"

export default defineMiddlewares({
  routes: [
    {
      matcher: "/store/custom*",
      middlewares: [
        async (req: MedusaRequest, res: MedusaResponse, next: MedusaNextFunction) => {
          const cacheService = req.scope.resolve(Modules.CACHE)
          const rateLimit = new RateLimit({
            cacheService,
            options: {
              limit: 50, // 50 requests per minute
              window: 60
            }
          })

          const ip = req.socket.remoteAddress as string

          // 🪄 This is where the magic happens
          const { success } = await rateLimit.limit(ip)

          if (!success) {
            res.status(429).send('Too many requests, please try again later.')
            return
          }

          next()
        }
      ],
    },
  ],
})

When building custom middleware, use req.socket.remoteAddress for the client IP. Avoid using x-forwarded-for directly as it can be spoofed. If you need proxy support, use the built-in ipRateLimit middleware with trustProxy instead.

The idea is simple: limit the number of requests by the identifier/key of your choice. This is useful if you want to protect based on some business logic aspects, for example by basing it on a license plate in the context of a car website or by user id, you are free to manage this as you wish.

src/api/middlewares.ts

  // ℹ️  A few examples in action...

  // For example by header
  await rateLimit.limit(req.headers['x-plate'])

  // By user id
  await rateLimit.limit(req.auth_context.actor_id)

  // Or by a static value that will be global to all users
  await rateLimit.limit('global')

Built-in IP Rate Limiting

For the common use case of IP-based rate limiting, V3 includes a ready-to-use ipRateLimit middleware:

src/api/middlewares.ts

import { defineMiddlewares } from "@medusajs/medusa"
import { ipRateLimit } from '@perseidesjs/medusa-plugin-rate-limit'

export default defineMiddlewares({
  routes: [
    {
      matcher: "/store/auth*",
      middlewares: [ipRateLimit({
        limit: 10,
        window: 60
      })],
    },
  ],
})

The ipRateLimit middleware automatically:

Extracts the client IP address
Sets appropriate rate limit headers (X-RateLimit-Limit, X-RateLimit-Remaining)
Returns a 429 status when the limit is exceeded

Extracting the client IP

By default, ipRateLimit uses req.socket.remoteAddress (the direct connection IP). This prevents attackers from bypassing rate limiting by spoofing the X-Forwarded-For header.

If your server is behind a reverse proxy (nginx, Cloudflare, etc.), enable trustProxy:

src/api/middlewares.ts

ipRateLimit({
  limit: 10,
  window: 60,
  trustProxy: 1  // Number of trusted proxy hops
})

`trustProxy` value	Behavior
`false` (default)	Uses direct connection IP. Ignores `X-Forwarded-For`.
`true`	Uses leftmost IP from `X-Forwarded-For`. Only use if your proxy overwrites the header.
`number`	Number of trusted proxy hops. Extracts IP from the right side of the header, preventing spoofing.

Example with trustProxy: 1:

X-Forwarded-For: spoofed-ip, real-client-ip
                            ↑ uses this (rightmost)

Only enable trustProxy if your server is behind a trusted reverse proxy. Enabling it without a proxy allows clients to spoof their IP and bypass rate limiting.

How to use

Built-in IP Rate Limiting

Extracting the client IP

On this page