---
name: bijection-convex-mq
description: "Evaluate and integrate the convex-mq component with Bijection."
---

# convex-mq

A typed message queue component for Convex with reactive consumers, visibility timeouts, and automatic retries.

This is an upstream package. It has not been adapted or qualified for Bijection.

- Package: convex-mq
- Source: https://github.com/gergesh/convex-mq
- npm: https://www.npmjs.com/package/convex-mq
- Directory: https://bijection.com/components/convex-mq

Read the upstream README for setup, license, and compatibility before using it.

## 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-mq. Its installation commands and APIs refer to the upstream package. Evaluate compatibility with the Bijection source separately.


# convex-mq

## Instructions

ConvexMQ is a typed message queue component that enables reliable background job processing with reactive consumption, visibility timeouts, and automatic retries. It offers two deployment modes: component mode for isolated queue tables, or library mode for custom schemas with filtered consumption via custom indexes. The component generates typed Convex functions for publishing, claiming, and acknowledging messages while handling lease tokens to prevent race conditions.

### Installation

```bash
npm install convex-mq
```

## Use cases

• **Background email processing** - Queue email jobs from user signup mutations and process them in external services with automatic retries if the SMTP provider fails
• **Image processing pipelines** - Enqueue image resize tasks with metadata like file size, then use filtered consumption to route large files to high-memory workers
• **Multi-tenant job routing** - Use custom indexes to consume only messages for specific tenants or worker types, enabling dedicated processing lanes
• **Dead letter handling** - Automatically retry failed jobs with configurable max attempts, then handle permanently failed messages in dead letter queues
• **Batch operations** - Publish multiple messages at once for bulk operations like sending welcome emails to new user cohorts

## How it works

The component operates in two modes: component mode uses isolated tables via `app.use(messageQueue)` in your Convex config, while library mode integrates with your schema using `messageQueueTable()`. You define message schemas with Convex validators, then call `messageQueue.api(query, mutation)` to generate typed functions like `publish`, `claim`, `ack`, and `nack`.

Messages follow a claim-ack pattern where consumers call `claim()` to reserve messages with visibility timeouts, process them externally, then call `ack()` or `nack()` to complete or retry. The component uses lease tokens (`claimId`) to prevent stale consumers from acknowledging messages they no longer own. Library mode supports filtered consumption via custom indexes, letting you consume subsets of messages with additional query parameters.

Consumers can operate reactively via WebSocket subscriptions using `consume(client, api.queue, handler)` or poll with `consumePolling()`. Authentication typically uses internal functions with deploy keys for consumers and authenticated mutations for publishers. The component automatically handles retries up to `maxAttempts` and returns dead letter messages when retries are exhausted.

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

## Resources

- [npm package](https://www.npmjs.com/package/convex-mq)
- [GitHub repository](https://github.com/gergesh/convex-mq)
- [Convex Components Directory](https://www.convex.dev/components/convex-mq)
- [Convex documentation](https://docs.convex.dev)