Embedded Mode

Use embedded mode when your app already creates Bull or BullMQ queues and should own their lifecycle.

In embedded mode:

You pass queue adapters to Bullstudio.
Bullstudio only shows supplied queues.
Your app owns the queue and Redis connection lifecycle.
The dashboard UI and private dashboard API are served from one mount path.

Install

Install one framework adapter and one queue adapter. The example below uses Express and BullMQ.

pnpm add @bullstudio/express @bullstudio/bullmq-adapter bullmq ioredis

For Bull v4 queues:

pnpm add @bullstudio/bull-adapter bull

Minimal BullMQ setup

import { createBullMqQueueAdapter } from "@bullstudio/bullmq-adapter";
import { Queue } from "bullmq";
import IORedis from "ioredis";

const connection = new IORedis(process.env.REDIS_URL!, {
  maxRetriesPerRequest: null,
});

const emailQueue = new Queue("email", { connection });

export const bullstudioQueues = [
  createBullMqQueueAdapter(emailQueue, {
    key: "email",
    label: "Email",
  }),
];

Pass bullstudioQueues to the framework adapter for your app.

Framework adapters

Express

Fastify

Hono

Next.js

NestJS

Production baseline

Use a stable mount path, read-only mode when operators do not need mutations, and explicit credentials.

bullstudio({
  queues: bullstudioQueues,
  readOnly: true,
  protection: {
    type: "session",
    username: process.env.BULLSTUDIO_USERNAME!,
    password: process.env.BULLSTUDIO_PASSWORD!,
    sessionSecret: process.env.BULLSTUDIO_SESSION_SECRET!,
  },
  dashboardIdentity: {
    title: "Production Queues",
  },
  documentIdentity: {
    title: "Queue Ops",
    favicon: "/favicon.ico",
  },
});

Set readOnly: true when operators should inspect queues without retrying, removing, pausing, or resuming jobs.