---
name: bijection-sharded-counter
description: "Evaluate and integrate the Sharded Counter component with Bijection."
---

# Sharded Counter

High-throughput counters

- Package: @bijectionhq/sharded-counter
- Category: Database & Backend
- Status: Preview
- License: Apache-2.0
- Bijection source (repository access required): https://github.com/bijectionhq/sharded-counter/tree/1f7533d42600fecdf559f3e1263479bbf8ee19c6
- Upstream: https://github.com/convex/sharded-counter/tree/d8f0718e7fd1ebcbe340e85b152af920d256c437
- Documentation: https://docs.bijection.com/components/using
- Directory: https://bijection.com/components/sharded-counter

## Get the source

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

```sh
git clone https://github.com/bijectionhq/sharded-counter.git
cd sharded-counter
git checkout 1f7533d42600fecdf559f3e1263479bbf8ee19c6
```

## 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/sharded-counter. 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 Sharded Counter. Follow the installation and configuration steps exactly.

# Sharded Counter

## Instructions

A scalable counter component that distributes count operations across multiple document shards to achieve high throughput. It provides atomic increment/decrement operations that can run in parallel without contention, while maintaining consistency and reactivity through Convex's built-in systems. The component includes methods for precise counting, estimated counting to reduce read contention, and rebalancing for optimal shard distribution.

### Installation

```bash
npm install @convex-dev/sharded-counter
```

Current npm version: `@convex-dev/sharded-counter@0.2.3`

## Use cases

- **Real-time voting or rating systems** where thousands of users might vote simultaneously on content, requiring high-throughput counter updates without blocking
- **Live engagement tracking** like counting active users, page views, or social media interactions that need to update frequently with minimal latency
- **Game leaderboards and scoring** where player actions generate rapid score updates that must remain consistent across concurrent gameplay sessions
- **Resource usage monitoring** such as tracking API calls, file downloads, or system events where accurate counts are needed despite high-frequency updates
- **Social media metrics** like counting likes, shares, or comments on viral content that experiences sudden traffic spikes

## How it works

The component distributes counter values across multiple document shards to avoid write contention when multiple mutations modify the same counter simultaneously. You configure the number of shards per counter key, with more shards providing higher write throughput at the cost of slower read operations.

The main API provides methods like `counter.inc()`, `counter.add()`, and `counter.count()` for basic operations, plus `counter.estimateCount()` for faster reads that sample fewer shards. For counter-specific operations, you can create focused instances with `counter.for("keyName")` that operate on a single key.

To integrate with existing tables, the component supports three patterns: manual counter updates in mutations, encapsulated write functions that always update counters, or automatic triggers that respond to table changes. For backfilling existing data, it provides strategies for both append-only and mutable datasets using cursor-based batch processing.

## 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 Sharded Counter is not needed

## Resources

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