Quickstart

Go from zero to a running background job in under 5 minutes.

1. Install

npm install @bullrun/sdk
npx bullrun init

This generates a bullrun.config.ts in your project root:

// bullrun.config.ts
import { defineConfig } from "@bullrun/sdk";

export default defineConfig({
  tasks: "./src/tasks/**/*.ts",
  redis: {
    host: "localhost",
    port: 6379,
  },
});

npx bullrun login

3. Define a task

// src/tasks/send-email.ts
import { defineTask } from "@bullrun/sdk";

export const sendEmail = defineTask({
  name: "send-email",
  queue: "emails",
  retry: { attempts: 3, backoff: { type: "exponential", delay: 1000 } },
  handler: async (payload: { to: string; subject: string; body: string }) => {
    // Your email sending logic
    await emailService.send(payload);
    return { sent: true };
  },
});

4. Trigger it

import { BullRun } from "@bullrun/sdk";

const client = new BullRun({ apiKey: "br_..." });

const { data } = await client.trigger("send-email", {
  to: "user@example.com",
  subject: "Welcome!",
  body: "Thanks for signing up.",
});

console.log("Job ID:", data.jobId);

5. Test locally

npx bullrun dev

This starts a local worker that processes your tasks using a local Redis instance. Changes to task files are hot-reloaded automatically.

6. Deploy

npx bullrun deploy