Introduction to bunqueue

bunqueue is a high-performance job queue written in TypeScript, designed specifically for the Bun runtime.

Why bunqueue?

• Native Bun - Built from the ground up for Bun, leveraging bun:sqlite for maximum performance
• Zero Redis - No external dependencies. SQLite provides persistence with WAL mode for concurrent access
• BullMQ-Compatible API - Familiar patterns if you’re migrating from BullMQ
• Production Ready - Stall detection, DLQ, rate limiting, webhooks, and S3 backups

Architecture

┌─────────────────────────────────────────────────────────────┐
│                      bunqueue server                        │
├─────────────────────────────────────────────────────────────┤
│  HTTP API (Bun.serve)  │  TCP Protocol (Bun.listen)        │
├─────────────────────────────────────────────────────────────┤
│                     Core Engine                             │
│  ┌─────────┐ ┌─────────┐ ┌──────────┐ ┌─────────┐         │
│  │ Queues  │ │ Workers │ │ Scheduler│ │   DLQ   │         │
│  └─────────┘ └─────────┘ └──────────┘ └─────────┘         │
├─────────────────────────────────────────────────────────────┤
│   bun:sqlite (WAL mode)    │   S3 Backup (optional)        │
└─────────────────────────────────────────────────────────────┘

Two Modes of Operation

	Embedded	TCP Server
Use case	Single process apps	Multi-process / Microservices
Setup	Zero config	Run bunqueue start
Option	embedded: true	Default (no option)
Persistence	DATA_PATH env var	--data-path flag

Embedded Mode

Use bunqueue as a library directly in your application:

import { Queue, Worker } from 'bunqueue/client';

// ⚠️ BOTH must have embedded: true
const queue = new Queue('tasks', { embedded: true });
const worker = new Worker('tasks', async (job) => {
  // Process job
}, { embedded: true });

Best for:

• Single-process applications
• Serverless functions
• Simple use cases

Server Mode

Run bunqueue as a standalone server:

# Start the server
bunqueue start --data-path ./data/queue.db

Then connect from your application:

import { Queue, Worker } from 'bunqueue/client';

// No embedded option = connects to localhost:6789
const queue = new Queue('tasks');
const worker = new Worker('tasks', async (job) => {
  // Process job
});

Best for:

• Multi-process workers
• Microservices architecture
• Language-agnostic clients (HTTP API)

Feature Comparison with BullMQ

Feature	bunqueue	BullMQ
Runtime	Bun	Node.js
Storage	SQLite	Redis
External deps	None	Redis server
Priority queues	✅	✅
Delayed jobs	✅	✅
Retries with backoff	✅	✅
Cron/repeatable jobs	✅	✅
Rate limiting	✅	✅
Stall detection	✅	✅
Parent-child flows	✅	✅
Advanced DLQ	✅	Basic
S3 backups	✅	❌
Sandboxed workers	✅	✅
Durable writes	✅	✅ (Redis AOF)

Next Steps

• Installation - Get bunqueue installed
• Quick Start - Create your first queue