Quickstart

You need a Redis URL and Bun (or Node). That's it.

1. Install and initialize

bun add @openqueue/sdk
bun add -d @openqueue/cli
bunx openqueue init

The CLI package ships the openqueue binary — once it's installed locally, bunx openqueue resolves it from your node_modules. (Without installing first, use bunx @openqueue/cli init.)

init scaffolds a config, a starter task, .env files, and a Dockerfile, and adds worker:dev / worker:build / worker:start scripts to your package.json. The two files you'll touch:

worker.config.ts

import { defineConfig } from '@openqueue/sdk';

export default defineConfig({
  namespace: process.env.OPENQUEUE_NAMESPACE ?? 'my-app',
  dirs: ['./worker'],
  redis: { url: process.env.REDIS_URL! },
  concurrency: {
    global: 8,
  },
  workbench: {
    enabled: true,
    title: 'Jobs',
    basePath: '/workbench',
  },
});

worker/example.ts

import { task } from '@openqueue/sdk';
import { z } from 'zod';

export const exampleTask = task({
  id: 'example',
  schema: z.object({
    message: z.string().default('Hello from OpenQueue'),
  }),
  run: async (payload, ctx) => {
    ctx.logger.info('received message', { message: payload.message });
    await ctx.progress({ step: 'done' });
    return { ok: true };
  },
});

2. Run the worker

bunx openqueue dev

dev loads worker.config.ts, discovers every exported task under dirs, starts the BullMQ workers, and serves Workbench. It watches your task files and restarts on change.

Open Workbench at the printed URL and you'll see your queue, live counters, and a Test page with an editable JSON body — enqueue a job straight from the browser.

3. Trigger from your app

import { exampleTask } from './worker/example';

await exampleTask.trigger({ message: 'deploy finished' });

trigger validates the payload against the schema, enqueues the job, and returns an EnqueueResult with the job id. Options let you delay or deduplicate:

await exampleTask.trigger(payload, { delay: 60_000 });

4. Ship it

bunx openqueue build   # bundles tasks into .openqueue/build/manifest.mjs
bunx openqueue start   # runs the worker from the manifest

See Deployment for Docker and production notes.

1. Install and initialize

2. Run the worker

3. Trigger from your app

4. Ship it

On this page