QueueDash Documentation

repository·main·Indexed 19 days ago

A compact dashboard for monitoring and managing job queues, supporting Bull, BullMQ, Bee-Queue, and GroupMQ. It provides features such as job retries, statistics, and a top-level overview of all queues. QueueDash includes server adapters for Express, Fastify, Hono, and Elysia, as well as integration support for Next.js (App and Pages Router) and a Docker image for rapid deployment.

Tokens: 11.7K
Snippets: 38
Records: 44
Agent score: 65%

What's inside QueueDash

Setup QueueDash with Express

main

To integrate QueueDash into an Express application, install @queuedash/api and use the createQueueDashExpressMiddleware function. You must provide a ctx object containing an array of queues. Each queue object requires the queue instance, a displayName, and a type (one of bull, bullmq, bee, or groupmq).

import express from "express";
import Bull from "bull";
import { createQueueDashExpressMiddleware } from "@queuedash/api";

const app = express();
const reportQueue = new Bull("report-queue");

app.use(
  "/queuedash",
  createQueueDashExpressMiddleware({
    ctx: {
      queues: [
        {
          queue: reportQueue,
          displayName: "Reports",
          type: "bull" as const,
        },
      ],
    },
  }),
);

app.listen(3000, () => {
  console.log("Listening on port 3000");
  console.log("Visit http://localhost:3000/queuedash");
});

import express from "express";
import Bull from "bull";
import { createQueueDashExpressMiddleware } from "@queuedash/api";

const app = express();

const reportQueue = new Bull("report-queue");

app.use(
  "/queuedash",
  createQueueDashExpressMiddleware({
    ctx: {
      queues: [
        {
          queue: reportQueue,
          displayName: "Reports",
          type: "bull" as const,
        },
      ],
    },
  }),
);

app.listen(3000, () => {
  console.log("Listening on port 3000");
  console.log("Visit http://localhost:3000/queuedash");
});

Setup QueueDash with Next.js (App and Pages Router)

main

To use QueueDash in Next.js, you need both @queuedash/api and @queuedash/ui. The setup involves two parts: a client-side component using <QueueDashApp /> and a server-side API route using appRouter from @queuedash/api via a tRPC adapter.

App Router

Client Component:

// app/admin/queuedash/[[...slug]]/page.tsx
"use client";

import { QueueDashApp } from "@queuedash/ui";
import "@queuedash/ui/dist/styles.css";

function getBaseUrl() {
  if (process.env.VERCEL_URL) {
    return `https://${process.env.VERCEL_URL}/api/queuedash`;
  }
  return `http://localhost:${process.env.PORT ?? 3000}/api/queuedash`;
}

export default function QueueDashPages() {
  return <QueueDashApp apiUrl={getBaseUrl()} basename="/admin/queuedash" />;
}

API Route:

// app/api/queuedash/[...trpc]/route.ts
import { fetchRequestHandler } from "@trpc/server/adapters/fetch";
import { appRouter } from "@queuedash/api";

const reportQueue = new Bull("report-queue");

function handler(req: Request) {
  return fetchRequestHandler({
    endpoint: "/api/queuedash",
    req,
    router: appRouter,
    allowBatching: true,
    createContext: () => ({
      queues: [
        {
          queue: reportQueue,
          displayName: "Reports",
          type: "bull" as const,
        },
      ],
    }),
  });
}

export { handler as GET, handler as POST };

Pages Router

Page Component:

// pages/admin/queuedash/[[...slug]].tsx
import { QueueDashApp } from "@queuedash/ui";

function getBaseUrl() {
  if (process.env.VERCEL_URL) {
    return `https://${process.env.VERCEL_URL}/api/queuedash`;
  }
  return `http://localhost:${process.env.PORT ?? 3000}/api/queuedash`;
}

const QueueDashPages = () => {
  return <QueueDashApp apiUrl={getBaseUrl()} basename="/admin/queuedash" />;
};

export default QueueDashPages;

API Route:

// pages/api/queuedash/[trpc].ts
import * as trpcNext from "@trpc/server/adapters/next";
import { appRouter } from "@queuedash/api";

const reportQueue = new Bull("report-queue");

export default trpcNext.createNextApiHandler({
  router: appRouter,
  batching: {
    enabled: true,
  },
  createContext: () => ({
    queues: [
      {
        queue: reportQueue,
        displayName: "Reports",
        type: "bull" as const,
      },
    ],
  }),
});

// Example App Router Client Component
"use client";
import { QueueDashApp } from "@queuedash/ui";
import "@queuedash/ui/dist/styles.css";

export default function QueueDashPages() {
  return <QueueDashApp apiUrl="http://localhost:3000/api/queuedash" basename="/admin/queuedash" />;
}

Enable HTTP Basic Authentication
main
The Express, Fastify, Hono, and Elysia adapters support optional HTTP Basic authentication. When configured, it protects both the dashboard UI and its tRPC API. Use HTTPS whenever Basic authentication is enabled.
To enable it, pass an auth object to createQueueDash<*>Middleware:
```
createQueueDashExpressMiddleware({
  auth: {
    username: process.env.QUEUEDASH_AUTH_USERNAME!,
    password: process.env.QUEUEDASH_AUTH_PASSWORD!,
  },
  ctx: {
    queues: [
      {
        queue: reportQueue,
        displayName: "Reports",
        type: "bull",
      },
    ],
  },
});
```
For direct @queuedash/ui integrations (like Next.js), you can pass request credentials through the headers prop of <QueueDashApp />.
https://github.com/alexbudure/queuedash/blob/main/README.md
Run QueueDash via Docker
main
The fastest way to get started is using the official Docker image. You can configure queues via environment variables.
```
docker run -p 3000:3000 \
  -e QUEUEDASH_AUTH_USERNAME='admin' \
  -e QUEUEDASH_AUTH_PASSWORD='change-me' \
  -e QUEUES_CONFIG_JSON='{"queues":[{"name":"my-queue","displayName":"My Queue","type":"bullmq","connectionUrl":"redis://localhost:6379"}]}' \
  ghcr.io/alexbudure/queuedash:latest
```
Environment Variables
- QUEUES_CONFIG_JSON: JSON string containing queue configuration. (Optional if QUEUES_CONFIG_FILE_PATH is set).
- QUEUES_CONFIG_FILE_PATH: Path to a JSON file containing queue configuration. (Optional if QUEUES_CONFIG_JSON is set).
- QUEUEDASH_AUTH_USERNAME: Username for HTTP Basic authentication. Must be set with QUEUEDASH_AUTH_PASSWORD.
- QUEUEDASH_AUTH_PASSWORD: Password for HTTP Basic authentication. Must be set with QUEUEDASH_AUTH_USERNAME.
https://github.com/alexbudure/queuedash/blob/main/README.md
Configure Redis service via Docker Compose
main
The docker-compose.yml file defines a redis service used by QueueDash. By default, it uses the official redis image and maps port 6379 on the host to port 6379 in the container.
```
services:
  redis:
    image: redis
    ports:
      - "6379:6379"
```
https://github.com/alexbudure/queuedash/blob/main/docker-compose.yml

Reference: <QueueDashApp /> Props

main

Props for the <QueueDashApp /> React component used in client-side integrations (e.g., Next.js).

Prop	Type	Description
`apiUrl`	`string`	URL to the API endpoint
`basename`	`string`	Base path for the app
`headers`	`Record<string, string> \| (() => Record<string, string> \| Promise<Record<string, string>>)` (optional)	Optional tRPC request headers for authentication or context.

type QueueDashAppProps = {
  apiUrl: string;
  basename: string;
  headers?:
    | Record<string, string>
    | (() => Record<string, string> | Promise<Record<string, string>>);
};

Reference: QueueDashMiddlewareOptions

main

Configuration options for createQueueDash<*>Middleware.

Key	Type	Description
`ctx`	`QueueDashContext`	Context for the UI (contains the queues)
`auth`	`QueueDashAuthOptions` (optional)	HTTP Basic authentication credentials
`baseUrl`	`string` (required for Fastify, Hono, Elysia)	The base URL for the middleware

QueueDashAuthOptions:

username: string
password: string

QueueDashContext:

queues: QueueDashQueue[] (Array of queues to display)

QueueDashQueue:

queue: Bull.Queue | BullMQ.Queue | BeeQueue (The actual queue instance)
displayName: string (Human-readable name)
type: 'bull' | 'bullmq' | 'bee' | 'groupmq' (The queue type)

type QueueDashMiddlewareOptions = {
  ctx: QueueDashContext;
  auth?: QueueDashAuthOptions;
  baseUrl?: string;
};

type QueueDashAuthOptions = {
  username: string;
  password: string;
};

type QueueDashContext = {
  queues: QueueDashQueue[];
};

type QueueDashQueue = {
  queue: Bull.Queue | BullMQ.Queue | BeeQueue;
  displayName: string;
  type: "bull" | "bullmq" | "bee" | "groupmq";
};

Integrate QueueDash with Fastify using fastifyQueueDashPlugin
main
To use QueueDash in a Fastify application, register the fastifyQueueDashPlugin. This plugin sets up the QueueDash UI routes and the underlying tRPC API.
Configuration Options
When calling fastifyQueueDashPlugin, you must provide a baseUrl and a ctx (tRPC Context). You can optionally provide uiHooks to inject Fastify hooks into the UI routes and auth to enable authentication.
- baseUrl: The base path where the QueueDash UI and tRPC API will be served.
- ctx: The tRPC context used by the QueueDash backend.
- uiHooks: An object containing optional Fastify hooks (onRequest or preHandler) that will be applied to the QueueDash UI routes.
- auth: An object of type QueueDashAuthOptions to enable authorization. If provided, the plugin adds an onRequest hook that validates the Authorization header. If unauthorized, it returns a 401 status with the QUEUEDASH_AUTH_CHALLENGE header.
Usage Example
```
import { fastifyQueueDashPlugin } from '@queuedash/api/server-adapters/fastify';

// Inside your Fastify setup
fastify.register(fastifyQueueDashPlugin, {
  baseUrl: '/queue-dash',
  ctx: myTrcpContext,
  auth: {
    // your auth options here
  },
  uiHooks: {
    onRequest: async (request, reply) => {
      // custom logic for UI routes
    }
  }
});
```
```
import { fastifyQueueDashPlugin } from '@queuedash/api/server-adapters/fastify';

fastify.register(fastifyQueueDashPlugin, {
  baseUrl: '/queue-dash',
  ctx: myTrcpContext,
  auth: {
    // your auth options here
  },
  uiHooks: {
    onRequest: async (request, reply) => {
      // custom logic for UI routes
    }
  }
});
```
https://github.com/alexbudure/queuedash/blob/main/packages/api/src/server-adapters/fastify.ts
Manage Job Schedulers in BullMQ
main
If your BullMQ setup uses repeatable jobs/schedulers, you can manage them via:
- getSchedulers(): Returns an array of SchedulerInfo (including id, name, pattern, every, next, etc.).
- addScheduler(name, opts, template): Upserts a new job scheduler.
- removeScheduler(key): Removes a scheduler by its key.
```
const schedulers = await adapter.getSchedulers();
await adapter.addScheduler('daily-cleanup', { cron: '0 0 * * *' }, { task: 'cleanup' });
```
https://github.com/alexbudure/queuedash/blob/main/packages/api/src/queue-adapters/bullmq.adapter.ts
Configure the QueueDash Context
main
The Context object is the primary way to pass queue information into the QueueDash system. It consists of an array of queues that you want to expose to the dashboard.
This context is used during the initialization of the tRPC server to bridge your application's queue instances with the QueueDash UI.
```
export type Context = {
  queues: Queue[];
};
```
https://github.com/alexbudure/queuedash/blob/main/packages/api/src/trpc.ts
Retrieve BullMQ metrics and Redis info
main
The adapter allows monitoring the health and performance of your queue:
- getJobCounts(): Returns counts for active, waiting, completed, failed, delayed, paused, prioritized, and waiting-children.
- getMetrics(type, start, end): Retrieves metrics for completed or failed jobs within a time range. The returned object includes a count field which is the sum of all data points in the range.
- getRedisInfo(): Returns parsed information from the underlying Redis instance, including maxclients.
```
const counts = await adapter.getJobCounts();
const redisInfo = await adapter.getRedisInfo();
const metrics = await adapter.getMetrics('failed', startTime, endTime);
```
https://github.com/alexbudure/queuedash/blob/main/packages/api/src/queue-adapters/bullmq.adapter.ts
Use QueueDash server adapters for Express, Fastify, and Elysia
main
QueueDash provides built-in support for several web frameworks via server adapters. You can import the corresponding adapter to integrate QueueDash into your existing server instance. Supported frameworks include Express, Fastify, and Elysia.
https://github.com/alexbudure/queuedash/blob/main/packages/api/src/main.ts

QueueDash Documentation

What's inside QueueDash

App Router

Pages Router

Environment Variables

Configuration Options

Usage Example