---
name: bijection-workpool
description: "Evaluate and integrate the Workpool component with Bijection."
---

# Workpool

Concurrency-limited background work

- Package: @bijectionhq/workpool
- Category: Durable Functions
- Status: Included
- License: Apache-2.0
- Bijection source (repository access required): https://github.com/bijectionhq/workpool/tree/6a3017e219b3a8e4af82079ce39186de5fc9f0b4
- Upstream: https://github.com/convex/workpool/tree/fe6f2b822927c0d81e060aec1084f8acd6bb8044
- Documentation: https://docs.bijection.com/components/using
- Directory: https://bijection.com/components/workpool

## Get the source

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

```sh
git clone https://github.com/bijectionhq/workpool.git
cd workpool
git checkout 6a3017e219b3a8e4af82079ce39186de5fc9f0b4
```

## 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 source is included in Bijection's workspace. 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/workpool. 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 Workpool. Follow the installation and configuration steps exactly.

# Workpool

## Instructions

Workpool manages parallel execution of Convex actions and mutations by organizing them into separate, customizable queues with configurable parallelism limits. It provides built-in retry logic with backoff and jitter for idempotent operations, plus completion callbacks for building reliable workflows. This prevents resource contention between high-priority work (like emails) and background tasks (like data scraping) while avoiding overwhelming your backend during third-party outages.

### Installation

```bash
npm install @convex-dev/workpool
```

Current npm version: `@convex-dev/workpool@0.4.14`

## Use cases

- **Prioritize critical async operations** - Separate email verification, payment processing, or notifications into high-priority pools while running data scraping or analytics in lower-priority queues
- **Build reliable workflows with retries** - Handle payment processing, webhook delivery, or third-party API calls with automatic retry logic and backoff to avoid overwhelming systems during outages
- **Reduce database write conflicts** - Serialize mutations that read and write the same data (like counters or inventory) by running them in a workpool with maxParallelism: 1
- **Control resource usage** - Throttle background jobs to stay within function execution limits while ensuring live user traffic isn't blocked by batch operations
- **Create durable multi-step processes** - Chain together actions using onComplete callbacks to build workflows that survive failures and track completion status reactively

## How it works

You install the component via `app.use(workpool, { name: "myWorkpool" })` in convex.config.ts and create workpool instances with specific parallelism limits. Each workpool acts as a separate queue - for example, `emailPool` with 10 parallel slots and `scrapePool` with 5 slots to prevent scraping from blocking emails.

Instead of calling `ctx.scheduler.runAfter()`, you enqueue work with `pool.enqueueAction(ctx, internal.myFunction, args)`. The workpool respects parallelism limits and provides retry configuration via `retryActionsByDefault` and `defaultRetryBehavior` with exponential backoff. Actions that fail while retrying don't consume parallelism slots during backoff periods.

The `onComplete` callback system enables reliable workflows - you can chain operations, log results, or trigger follow-up actions regardless of success or failure. The component stores job status reactively in the database, letting you build UIs that show real-time progress. Status data is kept for a configurable TTL (default 1 day) and can be queried using `pool.status(workId)`.

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

## Resources

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