guide · integrations

bunqueue in your stack.

One pattern works everywhere: create a queue, add jobs from your HTTP handlers, process them in a worker. This page shows the smallest version, then points you to the detailed guides.

This page is the hub for integrations. It shows the one pattern every integration shares, then links to the framework, storage, and AI agent guides.

The smallest integration

bunqueue in embedded mode runs inside your app’s process, backed by a local SQLite file, so there is no queue server to install or run. This works in any Bun app, whatever framework you use:

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

// The queue: where jobs wait
const emails = new Queue('emails', { embedded: true });

// The worker: runs your function on each job
new Worker('emails', async (job) => {
  await sendEmail(job.data);
}, { embedded: true });

// Anywhere in your app (an HTTP handler, for example):
await emails.add('welcome', { to: 'user@example.com' });

The HTTP response returns immediately; the email is sent in the background, with automatic retries if it fails.

Embedded mode required for in-process queues

All framework examples use embedded: true. Without it, bunqueue tries to connect to a TCP server instead. If you do run a standalone server, drop embedded: true and pass connection: { host, port }.

Web frameworks

The pattern above plus each framework’s idioms (typed context, validation, plugins):

Framework	What the guide adds	Guide
Hono	Routes, job status endpoints, typed middleware	Hono Integration
Elysia	Schema validation with t.Object(), plugin pattern	Elysia Integration

Using another framework? The smallest example above works as is; only the routing syntax changes.

Databases

bunqueue needs no external database. Persistence is a single local SQLite file. If you were expecting a Postgres or MySQL backend, or you deploy on a platform without a durable disk, read Storage: SQLite by Design. It explains why, and shows three patterns for serverless and ephemeral filesystems.

AI agents (MCP)

bunqueue ships an MCP server, so AI agents like Claude can add jobs, manage crons, retry failures, and monitor queues directly:

claude mcp add bunqueue -- bunx --package=bunqueue bunqueue-mcp

The same command shape works for Claude Desktop, Cursor, Windsurf, and any MCP client over stdio. Setup for each client, plus the full tool list, is in the MCP Server guide.

Note

bunqueue-mcp is a binary inside the bunqueue package, not a separate npm package. The MCP SDK is an optional peer dependency: run bun add @modelcontextprotocol/sdk once before starting the MCP server.

Shared patterns

These apply to any framework.

Define queues in one module

Create each queue once at startup and import it where needed. Do not create a new Queue(...) inside a request handler.

queues.ts

import { Queue } from 'bunqueue/client';

export const queues = {
  emails: new Queue('emails', {
    embedded: true,
    defaultJobOptions: { attempts: 3, backoff: 5000 },
  }),
  reports: new Queue('reports', {
    embedded: true,
    defaultJobOptions: { timeout: 300_000 },
  }),
} as const;

defaultJobOptions sets the retry and timeout defaults for every job added to that queue; per-job options override them.

Graceful shutdown

On shutdown, close workers first (they wait for active jobs to finish), then release the embedded queue manager:

import { shutdownManager } from 'bunqueue/client';

async function shutdown() {
  await Promise.all(workers.map((w) => w.close()));
  shutdownManager();
  process.exit(0);
}

process.on('SIGINT', shutdown);
process.on('SIGTERM', shutdown);

Next steps

• Hono Integration - Routes, workers, and status endpoints
• Elysia Integration - Validation and the plugin pattern
• Storage: SQLite by Design - Postgres questions answered
• MCP Server - Full AI agent setup
• CPU-Intensive Workers - Heavy jobs without dropped connections