Hono Tutorial

The Hono adapter ships in v0.4.0 and works across every Hono runtime Node, Bun, Deno, Cloudflare Workers, and Vercel Edge. The middleware sets standard RateLimit-* headers and responds 429 with { error, message, retryAfter } when a limit is exceeded.

1. Installation

npm install halt-rate hono

2. Basic setup

import { Hono } from 'hono';
import { RateLimiter, InMemoryStore, presets } from 'halt-rate';
import { haltMiddleware } from 'halt-rate/hono';

const limiter = new RateLimiter({
  store: new InMemoryStore(),
  policy: presets.PUBLIC_API,
});

const app = new Hono();
app.use('*', haltMiddleware({ limiter }));

app.get('/', (c) => c.json({ message: 'Hello, rate-limited world!' }));

export default app;

3. Edge IP detection

By default the adapter derives the client IP from edge headers (x-forwarded-for, cf-connecting-ip, x-real-ip), which works for Cloudflare Workers, Vercel Edge, and most reverse proxies. Override with getClientIp for custom infrastructure:

app.use('*', haltMiddleware({
  limiter,
  getClientIp: (c) => c.req.header('x-my-edge-ip') ?? 'unknown',
}));

4. Custom blocked response

app.use('*', haltMiddleware({
  limiter,
  onBlocked: (c, decision) => c.json(
    { error: 'too_many_requests', retryAfter: decision.retryAfter },
    429,
  ),
}));

Production storage

On Node and Bun, drop in the Redis store for atomic, distributed limits. On Cloudflare Workers or Vercel Edge, see Edge & Runtime Support for how to inject a fetch-based Redis client like Upstash.