Installation

``bash
npm install @unkey/ratelimit
`

Quickstart

1. Configure your ratelimiter:

`ts
import { Ratelimit } from "@unkey/ratelimit";

const unkey = new Ratelimit({
rootKey: process.env.UNKEY_ROOT_KEY,
namespace: "my-app",
limit: 10,
duration: "30s",
async: true,
});
`

2. Use it:

`ts
async function handler(request) {
const identifier = request.getUserId(); // or IP or anything else you want

const ratelimit = await unkey.limit(identifier);
if (!ratelimit.success) {
return new Response("try again later", { status: 429 });
}

// handle the request here
}
`

Making it Bullet Proof

To ensure reliability, you can configure timeout and error handling:

`ts
import { Ratelimit } from "@unkey/ratelimit";

const fallback = (identifier: string) => ({
success: true,
limit: 0,
reset: 0,
remaining: 0,
});

const unkey = new Ratelimit({
// ... standard configuration
timeout: {
ms: 3000, // only wait 3s at most before returning the fallback
fallback,
},
onError: (err, identifier) => {
console.error(${identifier} - ${err.message});
return fallback(identifier);
},
});
`

API Overview

Create a new instance for ratelimiting by providing the necessary configuration.

`ts
new Ratelimit(config: RatelimitConfig)
`

Check whether a specific identifier is currently allowed to do something or if they have currently exceeded their limit.

`ts
.limit(identifier: string, opts: LimitOptions): Promise
``

$3

Read the full documentation