Application-Layer Rate Limiting

Define and enforce type-safe rate limits in your Convex backend. Transactional, fair, and scalable with configurable sharding.

Get Started API Reference

Quick Start

Get up and running with rate limiting in minutes

Install the package

Add the rate limiter component to your Convex project:

npm install @convex-dev/rate-limiter

Configure the component

Create or update your convex/convex.config.ts file:

import { defineApp } from "convex/server";
import rateLimiter from "@convex-dev/rate-limiter/convex.config.js";

const app = defineApp();
app.use(rateLimiter);

export default app;

Define your rate limits

Create a rate limiter instance with your configuration:

import { RateLimiter, MINUTE, HOUR } from "@convex-dev/rate-limiter";
import { components } from "./_generated/api";

const rateLimiter = new RateLimiter(components.rateLimiter, {
  sendMessage: { kind: "token bucket", rate: 10, period: MINUTE, capacity: 3 },
  freeTrialSignUp: { kind: "fixed window", rate: 100, period: HOUR }
});

Use in your mutations

Enforce rate limits in your Convex mutations:

export const sendMessage = mutation({
  args: { message: v.string() },
  handler: async (ctx, args) => {
    const userId = await getUserId(ctx);
    
    // Check rate limit
    const { ok, retryAfter } = await rateLimiter.limit(ctx, "sendMessage", {
      key: userId
    });
    
    if (!ok) {
      throw new Error(`Rate limited. Retry after ${retryAfter}ms`);
    }
    
    // Process the message
    await ctx.db.insert("messages", { userId, text: args.message });
  }
});

Key Features

Everything you need for production-grade rate limiting

Type-Safe

Define rate limits with full TypeScript support. Catch configuration errors at compile time, not runtime.

Transactional

Rate limit changes roll back automatically if your mutation fails. No partial state or leaked capacity.

Scalable Sharding

Configure sharding to handle high throughput without compromising correctness or fairness.

Fair Reservations

Reserve capacity ahead of time to prevent starvation and avoid exponential backoff.

Multiple Algorithms

Choose between token bucket for smooth rate limiting or fixed window for burst allowance.

React Integration

Built-in React hooks for client-side rate limit status and synchronized timing.

Common Use Cases

Explore real-world examples and patterns

User Actions

Limit how fast users can perform actions like sending messages or posting content.

API Protection

Protect your backend from abuse with global or per-user rate limits.

Free Trial Signup

Prevent bot signups by limiting registration rates during free trials.

Failed Login Attempts

Implement security best practices by rate limiting authentication failures.

LLM API Calls

Control costs by limiting AI API requests with token bucket rate limits.

Custom Workflows

Build sophisticated rate limiting for complex business logic.

Ready to Get Started?

Add production-grade rate limiting to your Convex backend in minutes

View Quickstart Guide

Get Started

Core Concepts

Usage Guide

Advanced

Examples