@jfungus/ratelimit-h3


Rate limiting middleware for H3 and Nitro.

Installation

``bash
npm install @jfungus/ratelimit-h3
`

Usage

$3

`ts
import { createApp, createRouter, eventHandler } from "h3";
import { rateLimiter } from "@jfungus/ratelimit-h3";

const app = createApp();

// Apply rate limiting globally
app.use(
rateLimiter({
limit: 100,
windowMs: 60 * 1000, // 1 minute
}),
);

const router = createRouter();
router.get(
"/",
eventHandler(() => "Hello!"),
);

app.use(router);
`

$3

`ts
// server/middleware/ratelimit.ts
import { rateLimiter } from "@jfungus/ratelimit-h3";

export default rateLimiter({
limit: 100,
windowMs: 60 * 1000, // 1 minute
});
`

Options

| Option | Type | Default | Description |
| -------------- | ----------------------------------------------- | ------------------ | --------------------------------------- |
| limit | number | 100 | Max requests per window |
| windowMs | number | 60 * 1000 | Window size in milliseconds (1 minute) |
| algorithm | "sliding-window" \| "fixed-window" | "sliding-window" | Rate limiting algorithm |
| keyGenerator | (event: H3Event) => string | IP-based | Function to generate unique key |
| skip | (event: H3Event) => boolean | - | Skip rate limiting for certain requests |
| handler | (event: H3Event, info: RateLimitInfo) => void | 429 JSON | Custom rate limit exceeded handler |
| store | Store | MemoryStore | Custom storage backend |

Custom Key Generator

`ts
import { getHeader } from "h3";

app.use(
rateLimiter({
limit: 100,
windowMs: 60 * 1000,
keyGenerator: (event) => {
// Rate limit by API key
return getHeader(event, "x-api-key") || "anonymous";
},
}),
);
`

Distributed Storage

For multi-instance deployments, use @jfungus/ratelimit-unstorage:

`ts
import { createStorage } from "unstorage";
import redisDriver from "unstorage/drivers/redis";
import { createUnstorageStore } from "@jfungus/ratelimit-unstorage";

const storage = createStorage({
driver: redisDriver({ url: "redis://localhost:6379" }),
});

app.use(
rateLimiter({
limit: 100,
windowMs: 60 * 1000,
store: createUnstorageStore({ storage }),
}),
);
`

Nuxt

For Nuxt applications, use the dedicated module @jfungus/ratelimit-nuxt` instead.

Documentation

Full documentation

License

MIT