> ## Documentation Index
> Fetch the complete documentation index at: https://express-rate-limit.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Usage

### Importing the Library

<Note>
  This library requires [node](https://nodejs.org) version 16 or above.
</Note>

This library is provided in [esm](https://nodejs.org/api/esm.html) as well as
[cjs](https://nodejs.org/api/modules.html) forms, and works with both Javascript
and Typescript projects.

<CodeGroup>
  ```ts esm theme={null}
  // Your code most likely uses the es module format if the `type` field in your
  // `package.json` is set to `module`.

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

  ```ts commonjs theme={null}
  // Your code most likely uses the commonjs module format if the `type` field in
  // your `package.json` is absent, or set to `commonjs`.

  const { rateLimit } = require('express-rate-limit')
  ```
</CodeGroup>

### Using the Library in Express

The `rateLimit` function accepts an options object and returns the rate limiting
middleware.

An example with the recommended configuration is as follows:

```ts theme={null}
const limiter = rateLimit({
	windowMs: 15 * 60 * 1000, // 15 minutes
	limit: 100, // Limit each IP to 100 requests per `window` (here, per 15 minutes)
	standardHeaders: true, // Return rate limit info in the `RateLimit-*` headers
	legacyHeaders: false, // Disable the `X-RateLimit-*` headers
	ipv6Subnet: 56, // Set to 60 or 64 to be less aggressive, or 52 or 48 to be more aggressive
})
```

Then use it in your [Express](https://expressjs.com/) application as follows:

```ts theme={null}
app.use(limiter)
```

To use it only for a certain path (e.g., limit only calls to the `/auth/*`
endpoints), specify the url as the first parameter in `app.use`:

```ts theme={null}
app.use('/auth', limiter)
```

To use it only for a certain endpoint (e.g., limit calls to
`POST /reset_password`), add the limiter as a middle argument to
`app.get`/`app.post`/etc.:

```ts theme={null}
app.post('/reset_password', limiter, (req, res) => {
	// ...
})
```

Take a look at the [configuration page](/reference/configuration) for a list of
options you can use to change the behaviour of the limiter.

<Warning>
  If your server runs behind a proxy/load balancer, the IP address of the request
  might be `undefined`, or the IP of the load balancer/reverse proxy (leading to
  the rate limiter blocking **all** requests once the limit is reached).

  To fix this, take a look at the [guide](/guides/troubleshooting-proxy-issues) to
  troubleshooting proxy issues.
</Warning>

### Using the library in Next.js

Although not officially supported, several individuals have been able to
successfully use express-rate-limit in [Next.js](https://nextjs.org/) by
defining a custom [`keyGenerator`](/reference/configuration#keygenerator) to
return the user's IP (or some other identifier). However, additional changes
changes are sometimes needed, such as
[handling schema migrations with rate-limit-postgresql](https://github.com/express-rate-limit/rate-limit-postgresql/issues/36).

### Using External Stores

A store is essentially a javascript/typescript class that allows the library to
store hit counts and reset times for clients wherever you want, e.g., in an
external database.

To use an external store, pass an instance of the store to the `rateLimit`
function, like so:

```ts theme={null}
const limiter = rateLimit({
	// ... other options,
	store: new ExternalStore(),
})
```

For a list of stores you can use, take a look at the
[data stores page](/reference/stores).

For a tutorial on how to create your own store, see
[this](/guides/creating-a-store).