# koa-ratelimit

> Rate limiter middleware for koa

Latest version **6.0.0** (published 2025-06-05) · MIT license · 0 weekly downloads

## Install

```sh
npm install koa-ratelimit
pnpm add koa-ratelimit
yarn add koa-ratelimit
bun add koa-ratelimit
```

## Health

**Score 33/100 (F)** — status: maintenance-mode.

Positive: has types package; no vulnerabilities; high quality score.

Warnings: low downloads; no esm support.

Negative: stale; low maintenance score.

## Facts

| | |
|---|---|
| Version | 6.0.0 |
| Published | 2025-06-05 |
| First published | 2013-11-29 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | separate (@types/koa-ratelimit) |
| Module format | CommonJS |
| Node | >=18 |
| Dependencies | 2 |
| Unpacked size | 11.5 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 493 |
| Author | Koa.js contributors |
| Maintainers | coderhaoxin, niftylettuce, aaron, juliangruber, eivifj, dead_horse, tjholowaychuk, jongleberry, fengmk2, titanism |
| Keywords | koa, middleware, rate, ratelimit, ratelimiter |

## Links

- npm: https://www.npmjs.com/package/koa-ratelimit
- Repository: https://github.com/koajs/ratelimit
- Homepage: https://github.com/koajs/ratelimit#readme
- Issues: https://github.com/koajs/ratelimit/issues
- npm.io page: https://npm.io/package/koa-ratelimit

## Dependencies (2)

- [ms](https://npm.io/package/ms.md) ^2.1.3
- [async-ratelimiter](https://npm.io/package/async-ratelimiter.md) ^1.5.2

## Alternatives

- [@sindresorhus/slugify](https://npm.io/package/@sindresorhus/slugify.md) — 3.7M weekly downloads
- [solid-js](https://npm.io/package/solid-js.md) — 2.7M weekly downloads
- [expo-glass-effect](https://npm.io/package/expo-glass-effect.md) — 2.5M weekly downloads
- [nanoassert](https://npm.io/package/nanoassert.md) — 780.8K weekly downloads
- [@ffmpeg/ffmpeg](https://npm.io/package/@ffmpeg/ffmpeg.md) — 529.5K weekly downloads

## Recent versions

- 6.0.0 (latest) — 2025-06-05
- 5.1.0 — 2023-12-06
- 5.0.1 — 2021-07-19
- 5.0.0 — 2020-10-31
- 4.2.1 — 2019-12-01
- 4.3.0 — 2019-11-13
- 4.2.0 — 2019-02-03
- 4.1.2 — 2018-06-13
- 4.1.1 — 2018-05-29
- 4.1.0 — 2018-04-08
- 4.0.0 — 2017-03-12
- 3.0.0 — 2017-03-12
- 2.4.0 — 2016-10-26
- 2.3.0 — 2016-05-12
- 2.2.0 — 2016-04-11
- … 6 more at https://npm.io/package/koa-ratelimit/versions

## README

# [**koa-ratelimit**](https://github.com/koajs/ratelimit)

[![build status](https://github.com/koajs/ratelimit/actions/workflows/ci.yml/badge.svg)](https://github.com/koajs/ratelimit/actions/workflows/ci.yml)
[![code style](https://img.shields.io/badge/code_style-XO-5ed9c7.svg)](https://github.com/sindresorhus/xo)
[![styled with prettier](https://img.shields.io/badge/styled_with-prettier-ff69b4.svg)](https://github.com/prettier/prettier)
[![made with lass](https://img.shields.io/badge/made_with-lass-95CC28.svg)](https://lass.js.org)
[![license](https://img.shields.io/github/license/koajs/ratelimit.svg)](LICENSE)

> Rate limiter middleware for koa.


## Table of Contents

* [Installation](#installation)
* [Example](#example)
  * [With a Redis driver](#with-a-redis-driver)
  * [With a memory driver](#with-a-memory-driver)
* [Options](#options)
* [Responses](#responses)
* [License](#license)


## Installation

```sh
npm install koa-ratelimit
```


## Example

### With a Redis driver

```js
const Koa = require('koa');
const ratelimit = require('koa-ratelimit');
const Redis = require('ioredis');
const app = new Koa();

// apply rate limit
app.use(ratelimit({
  driver: 'redis',
  db: new Redis(),
  duration: 60000,
  errorMessage: 'Sometimes You Just Have to Slow Down.',
  id: (ctx) => ctx.ip,
  headers: {
    remaining: 'Rate-Limit-Remaining',
    reset: 'Rate-Limit-Reset',
    total: 'Rate-Limit-Total'
  },
  max: 100,
  disableHeader: false,
  whitelist: (ctx) => {
    // some logic that returns a boolean
  },
  blacklist: (ctx) => {
    // some logic that returns a boolean
  },
  onLimited: (ctx) => {
    // optional function to run when a user is rate limited
  }
}));

// response middleware
app.use(async (ctx) => {
  ctx.body = 'Stuff!';
});

// run server
app.listen(
  3000,
  () => console.log('listening on port 3000')
);
```

### With a memory driver

```js
const Koa = require('koa');
const ratelimit = require('koa-ratelimit');
const app = new Koa();

// apply rate limit
const db = new Map();

app.use(ratelimit({
  driver: 'memory',
  db: db,
  duration: 60000,
  errorMessage: 'Sometimes You Just Have to Slow Down.',
  id: (ctx) => ctx.ip,
  headers: {
    remaining: 'Rate-Limit-Remaining',
    reset: 'Rate-Limit-Reset',
    total: 'Rate-Limit-Total'
  },
  max: 100,
  disableHeader: false,
  whitelist: (ctx) => {
    // some logic that returns a boolean
  },
  blacklist: (ctx) => {
    // some logic that returns a boolean
  }
}));

// response middleware
app.use(async (ctx) => {
  ctx.body = 'Stuff!';
});

// run server
app.listen(
  3000,
  () => console.log('listening on port 3000')
);
```


## Options

* `driver` memory or redis \[redis]
* `db` redis connection instance or Map instance (memory)
* `duration` of limit in milliseconds \[3600000]
* `errorMessage` custom error message
* `id` id to compare requests \[ip]
* `namespace` prefix for storage driver key name \[limit]
* `headers` custom header names
* `max` max requests within `duration` \[2500]
* `disableHeader` set whether send the `remaining, reset, total` headers \[false]
* `remaining` remaining number of requests \[`'X-RateLimit-Remaining'`]
* `reset` reset timestamp \[`'X-RateLimit-Reset'`]
* `total` total number of requests \[`'X-RateLimit-Limit'`]
* `whitelist` if function returns true, middleware exits before limiting
* `blacklist` if function returns true, `403` error is thrown
* `throw` call ctx.throw if true


## Responses

Example 200 with header fields:

```sh
HTTP/1.1 200 OK
X-Powered-By: koa
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 99
X-RateLimit-Reset: 1384377793
Content-Type: text/plain; charset=utf-8
Content-Length: 6
Date: Wed, 13 Nov 2013 21:22:13 GMT
Connection: keep-alive

Stuff!
```

Example 429 response:

```sh
HTTP/1.1 429 Too Many Requests
X-Powered-By: koa
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1384377716
Content-Type: text/plain; charset=utf-8
Content-Length: 39
Retry-After: 7
Date: Wed, 13 Nov 2013 21:21:48 GMT
Connection: keep-alive

Rate limit exceeded, retry in 8 seconds
```


## License

[MIT](LICENSE) © Koa.js contributors

---
_Source: https://npm.io/package/koa-ratelimit · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._