Packages@g14o/ratelimit-hono

API Reference

Hono helpers for @g14o/ratelimit.

Generics and Env typing

@g14o/ratelimit-hono is generic over Hono's Env so Bindings and Variables flow into handler callbacks.

Symbol	Description
`createRateLimit<E extends Env>(options)`	Factory. Pass your app's env (e.g. `AppEnv`) to bind types for the whole client.
`HonoRateLimitClient<E>`	Client returned by the factory. All methods use `Context<E>`.
`HonoRateLimitOptions<E>`	Per-call options. `identifierFn` and `skipRateLimit` (boolean or callback) receive `Context<E>`. Global `skipRateLimit` on `CreateRateLimitOptions` is boolean-only.
`HonoHandler<E>`	Route handler passed to `withRateLimit` / `withUserRateLimit`.
`Env`	Re-exported from `hono`. Use as the base for your `AppEnv` type.

withRateLimit and withUserRateLimit return MiddlewareHandler<E>, assignable to typed app.get / app.post routes.

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).

HonoRateLimitClient

Prop	Type	Description
`checkRateLimit`	`function`	Checks the rate limit for a Hono request without wrapping a handler.
`getRateLimiter`	`function`	Returns a cached rate limiter adapter for a tier.
`middleware`	`function`	Hono middleware that rate-limits before `next()`. Returns `429` with standard headers when blocked; calls `next()` when allowed.
`reset`	`function`	Clears in-memory limiter state and the adapter cache. Useful in tests; does not reset Upstash Redis counters.
`userMiddleware`	`function`	Hono middleware with per-user rate limiting. Uses `getUserId(c)` as the identifier; falls back to IP when null.
`withRateLimit`	`function`	Wraps a Hono route handler with rate limiting. Returns `429` when blocked; invokes the handler when allowed.
`withUserRateLimit`	`function`	Wraps a Hono route handler with per-user rate limiting.

HonoRateLimitOptions

Option	Type	Description
`identifierFn?`	`function`	Function to get the identifier for the request. Defaults to the IP address of the request.
`prefix?`	`string`	Redis key prefix override for this call. Defaults to the tier prefix.
`skipRateLimit?`	`boolean \| ((c: Context<E>) => boolean \| Promise<boolean>) \| undefined`	Skip rate limit for this request.
`tier?`	`TokenTier \| undefined`	Rate limit tier to use. Defaults to `"moderate"`.

Setup

Hono middleware, route wrappers, and per-user rate limiting.

Overview

Framework-agnostic typesafe environment variables via Standard Schema.

On this page

Generics and Env typing CreateRateLimitOptions HonoRateLimitClient HonoRateLimitOptions