bunqueue

library2.8.6jsnpmunverified

Bunqueue is a high-performance job queue for the Bun runtime (≥1.3.9), built specifically for AI agents and automation. Version 2.8.6 provides SQLite persistence, cron scheduling, priorities, retries, dead-letter queues, webhooks, and a native MCP server — all with zero external runtime dependencies (only croner and msgpackr). It is a Redis/BullMQ alternative that ships as ESM-only TypeScript types. The package is actively maintained with frequent releases and benchmarks showing sub-millisecond job processing. Key differentiators: embedded/Simple Mode (queue+worker in one object), optional MCP SDK peer dependency, and a tiny footprint (7 packages, 5.4 MB) unlike Redis-backed alternatives.

messaging devops

npm install bunqueue

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · BUNQUEUE

bunqueue

messagingjavascriptv2.8.6

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Bunqueue

✓ import { Bunqueue } from 'bunqueue/client'

✗ const Bunqueue = require('bunqueue/client')

The package is ESM-only; require() will fail. Use the /client path for the Simple Mode combined queue+worker.

Queue

✓ import { Queue } from 'bunqueue'

✗ import { Queue } from 'bunqueue/client'

The base Queue class is exported from the main package. Queue is distinct from Bunqueue; it's used for distributed systems.

Worker

✓ import { Worker } from 'bunqueue'

✗ import Worker from 'bunqueue'

Worker is a named export from 'bunqueue', not a default export. For distributed setups, use Queue + Worker separately.

type Job

✓ import type { Job } from 'bunqueue'

✗ import { Job } from 'bunqueue'

Job is a TypeScript type, not a runtime value. Use 'import type' for correct type-only import.

Shows how to create a Simple Mode Bunqueue with an embedded worker that processes a job immediately.

import { Bunqueue } from 'bunqueue/client'; const app = new Bunqueue('emails', { embedded: true, processor: async (job) => { console.log(`Sending email to ${job.data.to}`); return { sent: true, id: job.id }; }, }); await app.add('send', { to: 'alice@example.com' }); console.log('Job added and processed by embedded worker');

Debug

Known issues

breakingRequires Bun >=1.3.9 — does not run on Node.js, Deno, or older Bun versions.

fix

Install Bun from https://bun.sh and run scripts with 'bun' command.

affects: >=0.0.0

gotchaAll imports must use ESM syntax; 'require()' throws an error because the package ships only ESM with extensionless specifiers.

fix

Use dynamic import() or configure TypeScript/Node to support ESM.

affects: >=2.0.0

gotchaWhen using separate Queue and Worker in distributed mode, the Queue must be instantiated before adding jobs to avoid race conditions.

fix

Ensure 'new Queue(...)' is called and the queue is ready before calling 'queue.add(...)'.

affects: >=2.0.0

deprecatedThe `Bunqueue` Simple Mode class is the recommended approach; using `Queue` + `Worker` separately is for advanced distributed setups only.

fix

Migrate to `Bunqueue` from 'bunqueue/client' for a simpler API.

affects: >=2.8.0

Errors

Common errors & fixes

Error: Cannot find module 'bunqueue/client'

Using CommonJS (require) instead of ESM import, or forgetting to install the package.

fix

Run 'bun add bunqueue' and ensure your code uses 'import { Bunqueue } from "bunqueue/client";'

TypeError: Bunqueue is not a constructor

Default import used instead of named import, or the import path is wrong.

fix

Use 'import { Bunqueue } from "bunqueue/client";' (curly braces for named import)

Error: Bunqueue requires Bun runtime >= 1.3.9

Running the code with Node.js or an older version of Bun.

fix

Install Bun 1.3.9+ from https://bun.sh and run with 'bun' command.

Upgrade

Version history

2.8.6latest on npm

Audit

Dependencies

@modelcontextprotocol/sdkoptionalOptional peer dependency required for MCP server functionality

Agent activity

32 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/egeominotti/bunqueue ↗

packagebunqueue ↗

homepagehttps://bunqueue.dev ↗