Configuration

worker.config.ts is the single source of truth for a worker. The CLI loads it for dev, build, and start; pass --config <path> to use a different file.

worker.config.ts

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

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

Reference

Field	Description
`namespace`	Prefix for every key this worker touches. Lets multiple apps share one backend.
`dirs`	Directories scanned for exported `task()` definitions.
`tasks`	Explicit task modules (`{ module, export? }`) instead of — or alongside — directory scanning.
`exclude`	Glob patterns removed from discovery (tests, fixtures).
`redis.url`	Redis connection string. Sugar for a BullMQ world; XOR with `world`.
`redis.bullPrefix`	Override the BullMQ key prefix.
`world`	A world factory (e.g. `worldPostgres({ url })`) — the non-BullMQ path. XOR with `redis`. When set, the world owns durable state, so `storage` is not accepted.
`storage`	A `QueueStorage` — use `postgresAdapter` to persist run history alongside the `redis` transport.
`drains`	Sinks for run lifecycle events; `consoleDrain()` ships in the box, `composeDrains()` combines several.
`retention`	Age-based pruning of durable run history — `{ completed: 30, failed: 90, logs: 30 }` days by default, `false` keeps a category forever. See Retention.
`concurrency.global`	Worker-wide cap on parallel jobs.
`concurrency.queues`	Per-queue caps, by queue name.
`api.token`	Bearer token(s) for the `/openqueue/v1` control API. Sugar for a leading `apiKey()` strategy. Unset = open in dev, 401 in production.
`api.auth`	Ordered `AuthStrategy` walk for the control API. Empty array = always 401 (fail-closed).
`metrics`	Toggle metric collection and key prefix.
`workbench`	Dashboard options — see below.
`build`	`outDir`, `extraFiles`, `external` for `openqueue build`.

Workbench options

Field	Description
`enabled`	Serve the dashboard from this worker.
`title`	Name shown in the dashboard chrome.
`basePath`	Mount path, for example `/workbench`.
`readonly`	Disable mutating actions (retry, enqueue, pause).
`auth`	`{ username, password }` for basic auth, or an ordered `AuthStrategy` walk. Unset = dashboard open.
`tagFields`	Payload field names that Workbench can extract as filterable tags.

Persistent run history

Redis keeps recent state; Postgres keeps the paper trail. Wire the Drizzle adapter to persist runs, schedules, and alerts:

import { defineConfig, postgresAdapter } from '@openqueue/sdk';
import { db } from './src/db';
import { queueSchema } from './src/queue-schema';

export default defineConfig({
  namespace: 'my-app',
  dirs: ['./worker'],
  redis: { url: process.env.REDIS_URL! },
  storage: postgresAdapter({ db, schema: queueSchema }),
});

See Persistence for the table definitions, how to generate the Drizzle migrations, and retention patterns.

Reference

Workbench options

Persistent run history

On this page