Packages@g14o/ratelimit-nextjs

API Reference

Next.js helpers for @g14o/ratelimit.

Next.js types

@g14o/ratelimit-nextjs binds @g14o/ratelimit to Next.js NextRequest / NextResponse.

Symbol	Description
`createRateLimit(options)`	Factory returning a client typed for `NextRequest` / `NextResponse`.
`RateLimitClient`	Alias of `RateLimitClient<NextRequest, NextResponse>` from core.
`RateLimitOptions`	Per-call options. `identifierFn` and `skipRateLimit` (boolean or callback) receive `NextRequest`. Global `skipRateLimit` on `CreateRateLimitOptions` is boolean-only.

CreateRateLimitOptions

Option	Type	Description
`env?`	`Environment \| undefined`	Environment name override. When omitted, falls back to `process.env.NODE_ENV` or `"development"`. Values `"development"` and `"test"` use in-memory cache and rate limiting.
`inMemoryDuringBuild?`	`boolean \| undefined`	When `true` (default), use in-memory cache/rate-limit backends during static build phases (`phase-production-build`, `phase-export` via `NEXT_PHASE`). Default: `true`
`hooks?`	`object`	Optional lifecycle hooks for observability and side effects. Hooks are awaited; hook errors are logged and swallowed so they never affect rate limiting or fail-open behavior.
`logger?`	`object`	Application logger. Defaults to a silent no-op logger.
`skipRateLimit?`	`boolean \| undefined`	When `true`, skip rate limiting for every request from this client. Evaluated at client creation — no request is available. Use per-call `skipRateLimit` for request-aware skip logic.
`tiers?`	`object`	Override built-in tier limits/windows/prefixes. Each tier key is optional; each field inside a tier is optional and merged onto factory defaults.
`redis?`	`RedisConfig \| undefined`	Legacy Upstash credentials or client. Mutually exclusive with `store`. Use `store: upstashStore({ url, token })` for new projects.
`store?`	`object`	Explicit store implementation (preferred).

RateLimitClient

Prop	Type	Description
`checkRateLimit`	`function`	Checks the rate limit for a request without wrapping a handler. Fails open on internal errors (returns `ok: true` with zeroed counters).
`getRateLimiter`	`function`	Returns a cached rate limiter adapter for a tier.
`reset`	`function`	Clears in-memory limiter state and the adapter cache. Useful in tests; does not reset Upstash Redis counters.
`withRateLimit`	`function`	Wraps an async handler with rate limiting. Returns `429` JSON with `Retry-After` and `X-RateLimit-` headers when blocked. On success, attaches `X-RateLimit-` headers to the handler response.
`withUserRateLimit`	`function`	Wraps a handler with per-user rate limiting. Uses `getUserId(req)` as the identifier; falls back to IP via getDefaultIdentifier when null.

RateLimitOptions

Option	Type	Description
`identifierFn?`	`function`	Function to get the identifier for the request. Defaults to the IP address of the request.
`prefix?`	`string`	Key prefix override for this call. Defaults to the tier prefix.
`skipRateLimit?`	`SkipRateLimitOption<NextRequest> \| undefined`	Skip rate limit for this request.
`tier?`	`TokenTier \| undefined`	Rate limit tier to use. Defaults to "moderate".

Setup

Next.js App Router routes and per-user rate limiting.

Overview

Express.js rate limiting with Upstash Redis for middleware and route handlers.

On this page

Next.js types CreateRateLimitOptions RateLimitClient RateLimitOptions