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

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

                                const status = await rateLimiter.limit(
                                ctx,
                                "sendMessage",
                                { key: userId }
                                );`}

Quick Start

Get up and running with rate limiting in minutes

Add the rate limiter component to your Convex project: ```bash theme={null} npm install @convex-dev/rate-limiter ``` Create or update your `convex/convex.config.ts` file: ```typescript theme={null} import { defineApp } from "convex/server"; import rateLimiter from "@convex-dev/rate-limiter/convex.config.js"; const app = defineApp(); app.use(rateLimiter); export default app; ``` Create a rate limiter instance with your configuration: ```typescript theme={null} 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 } }); ``` Enforce rate limits in your Convex mutations: ```typescript theme={null} 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

Define rate limits with full TypeScript support. Catch configuration errors at compile time, not runtime. Rate limit changes roll back automatically if your mutation fails. No partial state or leaked capacity. Configure sharding to handle high throughput without compromising correctness or fairness. Reserve capacity ahead of time to prevent starvation and avoid exponential backoff. Choose between token bucket for smooth rate limiting or fixed window for burst allowance. Built-in React hooks for client-side rate limit status and synchronized timing.

Common Use Cases

Explore real-world examples and patterns

Limit how fast users can perform actions like sending messages or posting content. Protect your backend from abuse with global or per-user rate limits. Prevent bot signups by limiting registration rates during free trials. Implement security best practices by rate limiting authentication failures. Control costs by limiting AI API requests with token bucket rate limits. 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