Queue Worker Builder

---
name: queue-worker-builder
description: |
  Trigger when the user asks to set up background jobs, a job queue, or move
  work out of the request cycle. Phrases: "background job", "queue worker",
  "async task", "BullMQ", "Inngest", "move out of request".
allowed-tools:
  - Read
  - Write
  - Edit
  - Bash(pnpm add *)
---

# Queue Worker Builder

Stand up a background-job queue for work that shouldn't run in the request
cycle. Cover Inngest (recommended for Next.js) and BullMQ (Redis-backed).

## Prerequisites

- Work identified that's slow or needs retry (emails, webhooks, image
  processing, batch exports)
- Redis or equivalent available (for BullMQ), or Inngest Cloud account

## Steps

1. **Decide if you actually need a queue.** Some signs you do:
   - Request handlers timing out on IO-heavy work
   - Work that must retry on failure (webhooks to third parties)
   - Work that should run on a schedule (nightly rollups)
   - Work the user shouldn't wait for (email sends, file conversions)

   Sign you don't: everything finishes in under 500ms.

2. **Pick the runtime:**
   - **Inngest** - durable, serverless-friendly, good Next.js integration.
     Picks itself for most greenfield apps.
   - **BullMQ** - Redis-backed, classic queue model, good when you already
     run Redis.
   - **Temporal** - long-running workflows with deterministic replay.
     Overkill for simple queues, essential for complex ones.

3. **Inngest pattern:**
   ```ts
   import { inngest } from "@/lib/inngest";

   export const sendWelcomeEmail = inngest.createFunction(
     { id: "send-welcome-email", retries: 3 },
     { event: "user/signed-up" },
     async ({ event, step }) => {
       const user = await step.run("fetch-user", () => getUser(event.data.userId));
       await step.run("send-email", () => resend.emails.send({ ... }));
     },
   );
   ```

4. **Every job is idempotent.** Queues retry. A job that sends an email
   twice on retry is a bug. Use an idempotency key or check-then-act.

5. **Every job has an explicit timeout.** Jobs that hang forever clog the
   queue. Default to a sensible upper bound per job type.

6. **Observability per job.** Log job start/finish/fail with enough context
   to debug. Inngest has a dashboard; BullMQ has Arena or Taskforce.

## Jobs that should not be in a queue

- Anything that needs the user to wait (synchronous response)
- Anything that must run exactly once without idempotency hooks
- Heavy CPU work that blocks the worker for minutes (use a separate pool)

## Output

- Queue client set up
- One job function written + tested
- Error-and-retry path verified
- Dashboard or log path documented for ops