Configuration File — bunqueue.config.ts

Configure your entire bunqueue server from a single typed file — no more scattered environment variables.

Quick Start

Create a bunqueue.config.ts in your project root:

import { defineConfig } from 'bunqueue';

export default defineConfig({
  server: {
    tcpPort: 6789,
    httpPort: 6790,
  },
  storage: {
    dataPath: './data/queue.db',
  },
});

Then start normally:

bunqueue start

The config file is auto-discovered — no flags needed.

Priority Order

Configuration values are resolved in this order (first wins):

CLI flags — bunqueue start --tcp-port 8000
Config file — bunqueue.config.ts
Environment variables — TCP_PORT=8000
Defaults — built-in defaults

This means you can use the config file as your baseline and override specific values per-environment with env vars or CLI flags.

Explicit Config Path

# Use a specific config file
bunqueue start --config ./config/production.config.ts

# Short form
bunqueue start -c ./config/staging.config.ts

Supported File Formats

bunqueue looks for these files in your project root (in order):

bunqueue.config.ts
bunqueue.config.js
bunqueue.config.mjs

Full Configuration Reference

Every section is optional. Only specify what you need.

`server`

TCP and HTTP server settings.

defineConfig({
  server: {
    tcpPort: 6789,           // TCP server port (default: 6789)
    httpPort: 6790,           // HTTP/REST API port (default: 6790)
    host: '0.0.0.0',         // Bind address (default: 0.0.0.0)
    tcpSocketPath: undefined, // Unix socket for TCP (overrides host/port)
    httpSocketPath: undefined, // Unix socket for HTTP (overrides host/port)
  },
});

`auth`

Authentication and security.

defineConfig({
  auth: {
    tokens: ['my-secret-token'],   // Auth tokens for TCP/HTTP
    requireAuthForMetrics: false,   // Require auth for /metrics endpoint
  },
});

`storage`

Database persistence.

defineConfig({
  storage: {
    dataPath: './data/queue.db',  // SQLite database path (undefined = in-memory)
  },
});

`cors`

Cross-Origin Resource Sharing for the HTTP API.

defineConfig({
  cors: {
    origins: ['https://myapp.com', 'https://admin.myapp.com'],
  },
});

`backup`

S3-compatible backup settings.

defineConfig({
  backup: {
    enabled: true,
    bucket: 'my-bunqueue-backups',
    accessKeyId: process.env.S3_ACCESS_KEY_ID,
    secretAccessKey: process.env.S3_SECRET_ACCESS_KEY,
    region: 'eu-west-1',              // Default: us-east-1
    endpoint: undefined,              // Custom S3 endpoint (MinIO, R2, etc.)
    interval: 6 * 60 * 60 * 1000,    // Backup interval in ms (default: 6h)
    retention: 7,                     // Backups to keep (default: 7)
    prefix: 'backups/',               // S3 key prefix (default: 'backups/')
  },
});

`timeouts`

Timeout settings for various operations.

defineConfig({
  timeouts: {
    shutdown: 30000,   // Graceful shutdown timeout in ms (default: 30000)
    stats: 300000,     // Stats logging interval in ms (default: 300000)
    worker: 30000,     // Worker timeout (default: 30000)
    lock: 5000,        // Lock timeout (default: 5000)
  },
});

`webhooks`

Webhook delivery settings.

defineConfig({
  webhooks: {
    maxRetries: 3,       // Max delivery retries (default: 3)
    retryDelay: 1000,    // Retry delay in ms (default: 1000)
  },
});

`logging`

Log output configuration.

defineConfig({
  logging: {
    level: 'info',     // 'debug' | 'info' | 'warn' | 'error'
    format: 'json',    // 'text' | 'json'
  },
});

Complete Examples

Development

import { defineConfig } from 'bunqueue';

export default defineConfig({
  server: {
    tcpPort: 6789,
    httpPort: 6790,
  },
  storage: {
    dataPath: './data/dev.db',
  },
  logging: {
    level: 'debug',
  },
});

Production

import { defineConfig } from 'bunqueue';

export default defineConfig({
  server: {
    tcpPort: 6789,
    httpPort: 6790,
    host: '0.0.0.0',
  },
  auth: {
    tokens: [process.env.BUNQUEUE_AUTH_TOKEN!],
    requireAuthForMetrics: true,
  },
  storage: {
    dataPath: '/data/bunqueue/queue.db',
  },
  cors: {
    origins: [process.env.FRONTEND_URL!],
  },
  backup: {
    enabled: true,
    bucket: process.env.S3_BUCKET!,
    accessKeyId: process.env.S3_ACCESS_KEY_ID,
    secretAccessKey: process.env.S3_SECRET_ACCESS_KEY,
    region: 'eu-west-1',
    interval: 3600000,  // Every hour
    retention: 30,
  },
  logging: {
    level: 'info',
    format: 'json',
  },
  timeouts: {
    shutdown: 60000,
  },
});

Docker / Kubernetes

When deploying with containers, you can mix the config file with environment variables:

// bunqueue.config.ts — static settings in the image
import { defineConfig } from 'bunqueue';

export default defineConfig({
  server: { host: '0.0.0.0' },
  logging: { format: 'json' },
  backup: {
    enabled: true,
    region: 'eu-west-1',
  },
});

# Dynamic settings from environment (override config file)
docker run \
  -e TCP_PORT=6789 \
  -e S3_BUCKET=my-bucket \
  -e S3_ACCESS_KEY_ID=xxx \
  -e S3_SECRET_ACCESS_KEY=xxx \
  my-bunqueue-image

Importing `defineConfig`

Available from both package exports:

// From the main package
import { defineConfig } from 'bunqueue';

// From the client package
import { defineConfig } from 'bunqueue/client';

bunqueue Cloud

When bunqueue Cloud is available, this is how you’ll configure it:

defineConfig({
  cloud: {
    url: 'https://cloud.bunqueue.io',
    apiKey: process.env.BUNQUEUE_CLOUD_API_KEY,
    instanceId: process.env.BUNQUEUE_CLOUD_INSTANCE_ID,
  },
});

These three fields are all you need. Everything else is managed automatically by the cloud dashboard.

Configuration File — bunqueue.config.ts

Quick Start

Priority Order

Explicit Config Path

Supported File Formats

Full Configuration Reference

server

auth

storage

cors

backup

timeouts

webhooks

logging