Registry / web-framework / koa2-ratelimit

koa2-ratelimit

library1.1.3jsnpmunverified

IP rate-limiting middleware for Koa2, inspired by express-rate-limit. Version 1.1.3 supports Redis, MongoDB (via Mongoose), and Sequelize stores. Release cadence is low; last significant update was in 2020. Differentiators: async/await, flexible interval config (ms or object), per-route keys, and delay-after behavior for throttling. Requires Node >=7.10 and peer deps for advanced stores.

web-framework database

npm install koa2-ratelimit

github ↗package ↗

INSTALL

IMPORT

SIG · KOA2-RATELIMIT

koa2-ratelimit

web-frameworkjavascriptv1.1.3

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

RateLimit

✓ const { RateLimit } = require('koa2-ratelimit');

✗ import { RateLimit } from 'koa2-ratelimit';

Package is CJS-only; ESM import may cause errors unless using bundler.

Stores

✓ const { Stores } = require('koa2-ratelimit');

✗ const Stores = require('koa2-ratelimit').Stores;

Both patterns work, but destructuring is cleaner.

default

✓ const koa2Ratelimit = require('koa2-ratelimit');

✗ import koa2Ratelimit from 'koa2-ratelimit';

No default export; always use named exports.

Basic Koa2 app with rate limiting: 100 requests per 15 minutes per IP.

Debug

Known issues

breakingIn v1.0.0, the `messageKey` option was removed; responses now use a standard JSON format.

fix

Update to v1.0.0+ and remove `messageKey` from options. Override `message` as a function to customize response.

affects: <1.0.0

breakingIn v1.0.0, `prefixKey` is now required when using stores to differentiate endpoints.

fix

Add `prefixKey` to your middleware options, e.g., `prefixKey: 'my-route'`.

affects: <1.0.0

deprecatedThe `delayAfter` and `timeWait` options are deprecated in favor of simpler throttling mechanisms.

fix

Remove `delayAfter` and `timeWait`; use rate-only limiting.

affects: >=0.9.0

gotchaRedis store requires `redis@4`; older `redis@2` or `redis@3` will cause connection errors.

fix

Install `npm install redis@4` and update client configuration to v4 style.

affects: >=1.0.0

gotchaThe package does not ship TypeScript definitions; you must create your own or use `@types/koa2-ratelimit` (community).

fix

Install `@types/koa2-ratelimit` or declare module manually.

affects: >=0.9.0

Errors

Common errors & fixes

Error: Cannot find module 'redis'

Redis store used but 'redis' package not installed.

fix

Run `npm install redis@4` in your project.

TypeError: Invalid interval: must be a number or an object with time units

Interval provided in unsupported format (e.g., string).

fix

Use number (milliseconds) or object like `{ hour: 1 }`. See docs for supported units.

TypeError: Cannot read property 'middleware' of undefined

Using `RateLimit.middleware.middleware()` (typo in README).

fix

Use `RateLimit.middleware(options)` only once.

Error: prefixKey is required when using a store

Using a database store without specifying `prefixKey`.

fix

Add `prefixKey: 'someKey'` to middleware options.

Upgrade

Version history

1.1.3latest on npm

Audit

Dependencies

mongooseoptionalRequired for MongoDB store (optional peer dep)

redisoptionalRequired for Redis store (optional peer dep, v4+)

sequelizeoptionalRequired for Sequelize store (optional peer dep)

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/ysocorp/koa2-ratelimit ↗

packagehttps://www.npmjs.com/package/koa2-ratelimit ↗