Hono Rate Limiter Middleware

Common errors

• TypeError: keyGenerator is not a function or is missing

  cause The `keyGenerator` option was omitted from the `rateLimiter` configuration after it became a required parameter in `v0.3.0`.
  fix Add `keyGenerator: (c) => c.req.ip` or a custom function to your `rateLimiter` options.

• Error: Invalid store. Please provide a valid store implementation.

  cause The `store` option for `rateLimiter` was either not provided or an invalid object was passed, preventing the middleware from initializing properly.
  fix Ensure you are passing a valid store instance, e.g., `store: new MemoryStore()` or `store: new RedisStore(...)` after installing the appropriate package.

• TypeError: rateLimiter is not a function

  cause Attempting to use `require()` for importing `hono-rate-limiter` in an ESM context, or incorrectly trying to import it as a default export.
  fix Use ESM named imports: `import { rateLimiter } from 'hono-rate-limiter';`.

Warnings

• breaking As of `v0.5.0`, specialized Cloudflare KV and Durable Object stores were removed from the main `hono-rate-limiter` package. If you were using these, you now need to explicitly use the `@hono-rate-limiter/cloudflare` package.
  Fix: Migrate to using `@hono-rate-limiter/cloudflare` for Cloudflare-specific stores. Review documentation for updated configuration.
• breaking In `core-0.3.0`, the `keyGenerator` option became a required parameter for the `rateLimiter` configuration. Omitting it will lead to runtime errors.
  Fix: Ensure `keyGenerator` is explicitly provided in your `rateLimiter` configuration, e.g., `keyGenerator: (c) => c.req.ip`.
• breaking Support for built-in Redis stores was dropped in `core-0.2.0`. Users who relied on this feature must now use a separate data store package, such as `@hono-rate-limiter/redis` or an `unstorage` compatible store.
  Fix: Install and configure a dedicated Redis store package (e.g., `@hono-rate-limiter/redis`) or an `unstorage` Redis driver, and pass an instance to the `store` option.
• gotcha The package is still actively in development. While functional, it might undergo further API changes or feature adjustments in future minor versions. Feedback is highly appreciated by the maintainers.
  Fix: Keep an eye on the changelog for new releases, report issues, and be prepared for potential minor breaking changes. Pinning to specific minor versions might be advisable in production.

Install

• npm install hono-rate-limiter npm
• yarn add hono-rate-limiter yarn
• pnpm add hono-rate-limiter pnpm

Imports

• rateLimiter
  wrong:

  const rateLimiter = require('hono-rate-limiter');

  correct:

  import { rateLimiter } from 'hono-rate-limiter';

  The primary named export for creating the HTTP rate limit middleware. Hono is primarily ESM-focused, so CJS `require` is generally incorrect.
• WebSocketLimiter
  wrong:

  import WebSocketLimiter from 'hono-rate-limiter';

  correct:

  import { WebSocketLimiter } from 'hono-rate-limiter';

  Named export for WebSocket-specific rate limiting, introduced in v0.4.0.
• MemoryStore
  wrong:

  import { MemoryStore } from 'hono-rate-limiter';

  correct:

  import { MemoryStore } from 'hono-rate-limiter/stores';

  Basic in-memory store; concrete store implementations are typically imported from the `/stores` subpath or a dedicated storage package.
• Store
  wrong:

  import { Store } from 'hono-rate-limiter';

  correct:

  import type { Store } from 'hono-rate-limiter';

  Type-only import for implementing custom storage solutions, ensuring type compatibility.

Quickstart

Demonstrates how to import and apply the `rateLimiter` middleware to a Hono application, configure basic limits, and use an in-memory store.

import { Hono } from 'hono';
import { rateLimiter } from 'hono-rate-limiter';
import { MemoryStore } from 'hono-rate-limiter/stores';

const app = new Hono();

// Configure the rate limiter middleware
const limiter = rateLimiter({
  windowMs: 60 * 1000, // 1 minute
  limit: 5, // Limit each IP to 5 requests per minute
  standardHeaders: 'draft-7', // Set standard rate limit headers
  legacyHeaders: false, // Disable X-RateLimit-* headers
  // keyGenerator: (c) => c.req.ip, // Uses client IP by default if not provided
  store: new MemoryStore(), // In-memory store (not recommended for production)
  message: 'You are making too many requests. Please try again soon.',
  handler: (c) => {
    return c.json({
      status: 429,
      message: 'Too many requests, please try again after some time.'
    }, 429)
  }
});

// Apply the rate limiter globally or to specific routes
app.use(limiter);

app.get('/', (c) => {
  return c.text('Welcome to the Hono Rate Limited API!');
});

app.get('/protected', (c) => {
  return c.json({ data: 'This is protected data.' });
});

export default app;