---
name: bijection-rate-limiter
description: "Evaluate and integrate the Rate Limiter component with Bijection."
---

# Rate Limiter

Transactional application rate limits

- Package: @bijectionhq/rate-limiter
- Category: Database & Backend
- Status: Preview
- License: Apache-2.0
- Bijection source (repository access required): https://github.com/bijectionhq/rate-limiter/tree/21107e0c5806ac7738b6963c3385da0293e705fd
- Upstream: https://github.com/convex/rate-limiter/tree/dee5af1daaa347ec2d6edaea1d28c7946a17243f
- Documentation: https://docs.bijection.com/components/using
- Directory: https://bijection.com/components/rate-limiter

## Get the source

Bijection repository access is required. Request access at https://bijection.com/contact.

```sh
git clone https://github.com/bijectionhq/rate-limiter.git
cd rate-limiter
git checkout 21107e0c5806ac7738b6963c3385da0293e705fd
```

## Before using this component

Read the package README at the recorded revision for setup, dependencies, and API examples. Upstream documentation describes the original package and may differ from the Bijection adaptation. This is a source candidate for evaluation. Catalog inclusion does not establish npm availability or runtime qualification. Check compatibility with your SDK and deployment before adoption. External providers run their own compute.

## Integration workflow

1. Read the source README and package manifest at the recorded revision.
2. Confirm the required SDK, dependency availability, and runtime compatibility.
3. Follow the component's documented setup and configuration. Never invent an npm install command from a catalog package name.
4. Keep credentials in the project's existing secret store.
5. Follow the project's execution rules for verification and report what was actually checked.

## Original upstream skill

The following guidance describes @convex-dev/rate-limiter. Its installation commands and APIs refer to the upstream package. Evaluate compatibility with the Bijection source separately.


> Agents: read this skill fully before writing code that uses Rate Limiter. Follow the installation and configuration steps exactly.

# Rate Limiter

## Instructions

Provides type-safe, transactional application-layer rate limiting for Convex apps. Supports both fixed window and token bucket algorithms with configurable sharding for high-throughput scenarios. Features include capacity reservation to prevent starvation, fairness guarantees, and React hooks for client-side rate limit checking.

### Installation

```bash
npm install @convex-dev/rate-limiter
```

Current npm version: `@convex-dev/rate-limiter@0.4.2`

## Use cases

- **Prevent API abuse** - Limit user actions like free trial signups or message sending to deter bots and abuse
- **Protect external API quotas** - Rate limit LLM token consumption and requests to stay within third-party service limits
- **Implement progressive restrictions** - Apply stricter rate limits after failed login attempts or other suspicious activity
- **Handle burst traffic** - Use token bucket strategy to allow short bursts while maintaining long-term consumption limits
- **Scale high-throughput operations** - Shard rate limits across multiple buckets to handle thousands of requests per minute without contention

## How it works

You define rate limits by creating a `RateLimiter` instance with named configurations specifying algorithm type (fixed window or token bucket), rate, period, and optional capacity or sharding parameters. Each rate limit can be global or keyed by user ID, session, or other identifiers.

The core API uses `rateLimiter.limit(ctx, "limitName", options)` within Convex mutations or actions, returning success status and retry timing. Advanced features include `reserve: true` for capacity reservation to prevent request starvation, and configurable sharding to distribute load across multiple database documents for high-throughput scenarios.

The component includes React hooks via `rateLimiter.hookAPI()` for client-side rate limit checking, and utilities like `reset()` for clearing limits and `getValue()` for inspecting current capacity. All operations are transactional and will roll back if the containing Convex function fails.

## When NOT to use

- When a simpler built-in solution exists for your specific use case
- If you are not using Convex as your backend
- When the functionality provided by Rate Limiter is not needed

## Resources

- [npm package](https://www.npmjs.com/package/%40convex-dev%2Frate-limiter)
- [GitHub repository](https://github.com/get-convex/rate-limiter)
- [Convex Components Directory](https://www.convex.dev/components/rate-limiter)
- [Convex documentation](https://docs.convex.dev)