Getting started

Quickstart

Queuebird runs your background jobs as plain functions in your existing app. This guide takes you from zero to a retried, observable job in about five minutes.

1. Install the SDK

terminal

$ npm i queuebird

Then add your project key to .env.local as QUEUEBIRD_KEY. You'll find it on the dashboard under Settings → API keys.

2. Define a job

A job is a named async function. Its argument is its payload, and it's typed end to end.

jobs/welcome.ts

import { queue } from "queuebird";

export const sendWelcome = queue("send-welcome", async (user: User) => {
  await email.send({ to: user.email, template: "welcome" });
});

3. Enqueue it

Call enqueue from a route handler, a server action, or another job. It returns as soon as the job is persisted. If the function throws, Queuebird retries it with exponential backoff — five attempts by default.

app/api/signup/route.ts

// Runs in ten minutes, retried on failure.
await sendWelcome.enqueue(user, { delay: "10m" });

Note: jobs must be idempotent. A retried job can run more than once if it fails after doing part of its work.

Cron

Swap queue for cron and pass a schedule. Schedules are deployed with your code, so a preview deploy never fires production cron.

Workflows

A workflow is a job made of steps. Each step retries on its own, and step.sleep can wait for days without holding a worker.

Changelog

2.0.0 — Multi-step workflows.
1.8.0 — Per-key concurrency limits.
1.7.0 — Replay failed runs from the dashboard.

Last updated 3 days agoNext: Pricing →