Workbench

https://getworkbench.dev/docs
Admin
Workbench is a comprehensive platform providing documentation and guides for various development...
Tokens:8,012
Snippets:137
Trust Score:3.4
Update:3 months ago
Show doc for...
Tokens:
Raw
### Install Workbench MCP

Source: https://getworkbench.dev/docs/packages/mcp

Install the package using npx.

```shell
npx @getworkbench/mcp
```

--------------------------------

### Install Workbench dependencies

Source: https://getworkbench.dev/docs/frameworks/tanstack-start

Install the required packages for Workbench and BullMQ integration in a TanStack Start project.

```shell
npm i @getworkbench/tanstack-start bullmq @tanstack/react-start
```

--------------------------------

### Install Workbench dependencies

Source: https://getworkbench.dev/docs/frameworks/elysia

Install the necessary packages for Workbench, BullMQ, and Elysia using Bun.

```shell
bun add @getworkbench/elysia bullmq elysia
```

--------------------------------

### Install Workbench dependencies

Source: https://getworkbench.dev/docs/frameworks/next

Install the required Workbench Next.js package and BullMQ.

```shell
npm i @getworkbench/next bullmq
```

--------------------------------

### Install Workbench dependencies

Source: https://getworkbench.dev/docs/frameworks/koa

Install the required packages for Workbench, BullMQ, and Koa.

```shell
npm i @getworkbench/koa bullmq koa
```

--------------------------------

### Install Workbench for Bun

Source: https://getworkbench.dev/docs/frameworks/bun

Install the required packages using the Bun package manager.

```shell
bun add @getworkbench/bun bullmq
```

--------------------------------

### Install Workbench for Nuxt

Source: https://getworkbench.dev/docs/frameworks/nuxt

Install the required Workbench Nuxt package and BullMQ dependency.

```shell
npm i @getworkbench/nuxt bullmq
```

--------------------------------

### Run local development environment

Source: https://getworkbench.dev/docs/deployment/standalone-docker

Starts a local Redis instance and runs the standalone development server.

```shell
docker compose up -d redis
REDIS_URL=redis://localhost:6379 bun run --filter @getworkbench/standalone dev
```

--------------------------------

### Install Workbench Fastify dependencies

Source: https://getworkbench.dev/docs/frameworks/fastify

Install the required packages for Workbench, BullMQ, and Fastify.

```shell
npm i @getworkbench/fastify bullmq fastify
```

--------------------------------

### Start Local Redis

Source: https://getworkbench.dev/docs/getting-started/quick-start

Use Docker Compose to spin up a local Redis instance for development.

```shell
docker compose up -d redis
```

--------------------------------

### Run Workbench with Docker

Source: https://getworkbench.dev/docs/deployment/standalone-docker

Starts the Workbench container with required Redis and queue configuration.

```shell
docker run --rm -p 3000:3000 \
  -e REDIS_URL=redis://host.docker.internal:6379 \
  -e QUEUE_NAMES=default \
  ghcr.io/pontusab/workbench-standalone:latest
```

--------------------------------

### Install Workbench h3 dependencies

Source: https://getworkbench.dev/docs/frameworks/h3

Install the required packages for Workbench and h3 integration.

```shell
npm i @getworkbench/h3 bullmq h3
```

--------------------------------

### Install Workbench Dependencies

Source: https://getworkbench.dev/docs/frameworks/nestjs

Install the required Workbench NestJS package and BullMQ dependency.

```shell
npm i @getworkbench/nestjs bullmq
```

--------------------------------

### Install Workbench Express dependencies

Source: https://getworkbench.dev/docs/frameworks/express

Install the required packages for Workbench, BullMQ, and Express via npm.

```shell
npm i @getworkbench/express bullmq express
```

--------------------------------

### Install Workbench Astro package

Source: https://getworkbench.dev/docs/frameworks/astro

Install the necessary dependencies for Workbench and BullMQ in your Astro project.

```shell
npm i @getworkbench/astro bullmq
```

--------------------------------

### Install Workbench dependencies

Source: https://getworkbench.dev/docs/frameworks/adonis

Install the required packages for Workbench and BullMQ in your AdonisJS project.

```shell
npm i @getworkbench/adonis bullmq @adonisjs/core
```

--------------------------------

### Install Workbench Hono dependencies

Source: https://getworkbench.dev/docs/frameworks/hono

Install the required packages for Workbench and BullMQ integration in a Hono project.

```shell
npm i @getworkbench/hono bullmq hono
```

--------------------------------

### Workbench CLI Options

Source: https://getworkbench.dev/docs/getting-started/quick-start

Available flags for customizing the initialization process.

```shell
workbench init [options]

  --cwd <path>      Project directory (default: cwd)
  --mount <path>    Mount path for the dashboard (default: /jobs)
  --no-auth         Skip basic auth setup
  --no-docker       Skip docker-compose Redis setup
  --yes             Skip all prompts, use defaults
```

--------------------------------

### Non-interactive CLI Initialization

Source: https://getworkbench.dev/docs/getting-started/quick-start

Use the --yes flag to skip prompts and apply default configurations.

```shell
npx @getworkbench/cli init --yes --no-docker
```

--------------------------------

### Configure Workbench options

Source: https://getworkbench.dev/docs/guides/configuration

Initialize the workbench with required queues, base path, and authentication settings.

```typescript
workbench({
  queues: [emailQueue],
  basePath: "/jobs",
  auth: { username: "admin", password: "secret" },
  title: "My Queues",
  readonly: false,
  tags: ["tenantId", "region"],
  alerts: { /* ... */ },
});
```

--------------------------------

### Project Directory Layout

Source: https://getworkbench.dev/docs/frameworks/ssr-workers

Recommended file structure for separating the web server and worker process in a monorepo.

```text
my-app/
├── app/                    # Next.js app with Workbench at /jobs
├── worker/
│   └── index.ts            # BullMQ Worker bootstrap
└── package.json            # "dev": "concurrently "next dev" "bun worker/index.ts""
```

--------------------------------

### Mount Workbench on Bun Server

Source: https://getworkbench.dev/docs/frameworks/bun

Initialize the Workbench handler with BullMQ queues and integrate it into the Bun.serve fetch function. Requires Bun 1.1 or higher.

```typescript
import { Queue } from "bullmq";
import { workbench } from "@getworkbench/bun";

const emailQueue = new Queue("email", {
  connection: { url: process.env.REDIS_URL! },
});

const handler = workbench({ queues: [emailQueue], basePath: "/jobs" });

Bun.serve({
  port: 3000,
  fetch(req) {
    return handler(req, () => new Response("home"));
  },
});
```

--------------------------------

### Configure basic authentication in code

Source: https://getworkbench.dev/docs/getting-started/authentication

Pass username and password credentials directly to the workbench adapter configuration.

```typescript
workbench({
  queues: [emailQueue],
  auth: {
    username: process.env.WORKBENCH_USER!,
    password: process.env.WORKBENCH_PASS!,
  },
});
```

--------------------------------

### Initialize WorkbenchCore with Auto-Discovery

Source: https://getworkbench.dev/docs/guides/redis-auto-discovery

Use the core API to initialize Workbench with auto-discovery enabled.

```typescript
import { WorkbenchCore } from "@getworkbench/core";

const core = await WorkbenchCore.fromOptions({
  redis: process.env.REDIS_URL!,
  prefix: "bull",
  maxQueues: 100,
});
```

--------------------------------

### Build Workbench from source

Source: https://getworkbench.dev/docs/deployment/standalone-docker

Builds the Docker image from the monorepo root using the standalone Dockerfile.

```shell
docker build -f apps/standalone/Dockerfile -t workbench-standalone .
```

--------------------------------

### Configure Claude Desktop MCP

Source: https://getworkbench.dev/docs/packages/mcp

Add the server configuration to the Claude Desktop configuration file.

```json
{
  "mcpServers": {
    "workbench": {
      "command": "npx",
      "args": ["-y", "@getworkbench/mcp"],
      "env": {
        "WORKBENCH_URL": "http://localhost:3000/jobs"
      }
    }
  }
}
```

--------------------------------

### Run the Workbench CLI migration

Source: https://getworkbench.dev/docs/guides/migrating-from-bull-board

Executes the automated migration process to detect bull-board, remove it, and scaffold the Workbench mount.

```bash
npx @getworkbench/cli init
```

--------------------------------

### Mount Workbench in Elysia

Source: https://getworkbench.dev/docs/frameworks/elysia

Initialize the Elysia application and mount the Workbench dashboard. Ensure the basePath option matches the mount path.

```typescript
import { Elysia } from "elysia";
import { Queue } from "bullmq";
import { workbench } from "@getworkbench/elysia";

const emailQueue = new Queue("email", {
  connection: { url: process.env.REDIS_URL! },
});

new Elysia()
  .mount("/jobs", workbench({ queues: [emailQueue], basePath: "/jobs" }))
  .listen(3000);
```

--------------------------------

### Mount Workbench in Express

Source: https://getworkbench.dev/docs/frameworks/express

Initialize the Workbench middleware with a list of BullMQ queues and mount it to a specific route in the Express application.

```typescript
import express from "express";
import { Queue } from "bullmq";
import { workbench } from "@getworkbench/express";

const app = express();
const emailQueue = new Queue("email", {
  connection: { url: process.env.REDIS_URL! },
});

app.use("/jobs", workbench({ queues: [emailQueue] }));
app.listen(3000);
```

--------------------------------

### Configure Cursor MCP

Source: https://getworkbench.dev/docs/packages/mcp

Add the server configuration to the Cursor MCP settings file.

```json
{
  "mcpServers": {
    "workbench": {
      "command": "npx",
      "args": ["-y", "@getworkbench/mcp"],
      "env": {
        "WORKBENCH_URL": "http://localhost:3000/jobs",
        "WORKBENCH_USERNAME": "admin",
        "WORKBENCH_PASSWORD": "hunter2"
      }
    }
  }
}
```

--------------------------------

### Mount Workbench in Next.js

Source: https://getworkbench.dev/docs/frameworks/next

Create a catch-all route handler to expose Workbench endpoints. The basePath must match the directory structure of the route file.

```typescript
// app/jobs/[[...workbench]]/route.ts
import { Queue } from "bullmq";
import { workbench } from "@getworkbench/next";

const emailQueue = new Queue("email", {
  connection: { url: process.env.REDIS_URL! },
});

export const { GET, POST, PUT, PATCH, DELETE } = workbench({
  queues: [emailQueue],
  basePath: "/jobs",
});
```

--------------------------------

### Manual Workbench Configuration

Source: https://getworkbench.dev/docs/getting-started/quick-start

Configure the dashboard manually by passing queue instances and authentication credentials to the adapter function.

```typescript
workbench({
  queues: [emailQueue],
  basePath: "/jobs",
  auth: {
    username: process.env.WORKBENCH_USER!,
    password: process.env.WORKBENCH_PASS!,
  },
});
```

--------------------------------

### Mount Workbench in Koa

Source: https://getworkbench.dev/docs/frameworks/koa

Initialize the Koa application and mount the Workbench middleware. A basePath is required to ensure the middleware correctly matches its prefix.

```typescript
import Koa from "koa";
import { Queue } from "bullmq";
import { workbench } from "@getworkbench/koa";

const app = new Koa();
const emailQueue = new Queue("email", {
  connection: { url: process.env.REDIS_URL! },
});

app.use(workbench({ queues: [emailQueue], basePath: "/jobs" }));
app.listen(3000);
```

--------------------------------

### workbench(options)

Source: https://getworkbench.dev/docs/frameworks/astro

The workbench function is used to mount the dashboard within an Astro route file. It accepts an object containing the BullMQ queues to monitor and the base path for the dashboard.

```APIDOC
## workbench(options)

### Description
Mounts the Workbench dashboard in an Astro server route. This function returns the necessary handlers (GET, POST, PUT, PATCH, DELETE) and the prerender configuration required by Astro.

### Parameters
- **options** (object) - Required
  - **queues** (Array<Queue>) - Required - An array of BullMQ Queue instances to be managed by the dashboard.
  - **basePath** (string) - Required - The URL path prefix where the dashboard will be mounted (e.g., "/jobs").

### Usage Example
```typescript
import { Queue } from "bullmq";
import { workbench } from "@getworkbench/astro";

const emailQueue = new Queue("email", { connection: { url: process.env.REDIS_URL! } });

export const { GET, POST, PUT, PATCH, DELETE, prerender } = workbench({
  queues: [emailQueue],
  basePath: "/jobs",
});
```
```

--------------------------------

### Configure Redis Auto-Discovery

Source: https://getworkbench.dev/docs/guides/redis-auto-discovery

Pass a Redis connection string to the workbench configuration to enable automatic queue discovery.

```typescript
workbench({
  redis: process.env.REDIS_URL!,
  prefix: "bull", // optional, default "bull"
  maxQueues: 100, // optional cap for large deployments
});
```

--------------------------------

### Mount Workbench in NestJS

Source: https://getworkbench.dev/docs/frameworks/nestjs

Initialize the Workbench dashboard by passing the NestJS app instance and configured BullMQ queues to the workbench function.

```typescript
import { NestFactory } from "@nestjs/core";
import { Queue } from "bullmq";
import { workbench } from "@getworkbench/nestjs";
import { AppModule } from "./app.module";

async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  const emailQueue = new Queue("email", {
    connection: { url: process.env.REDIS_URL! },
  });

  await workbench(app, "/jobs", { queues: [emailQueue] });
  await app.listen(3000);
}
bootstrap();
```

--------------------------------

### Mount Workbench in Fastify

Source: https://getworkbench.dev/docs/frameworks/fastify

Register the Workbench plugin with a configured BullMQ queue instance.

```typescript
import Fastify from "fastify";
import { Queue } from "bullmq";
import { workbench } from "@getworkbench/fastify";

const app = Fastify();
const emailQueue = new Queue("email", {
  connection: { url: process.env.REDIS_URL! },
});

await app.register(workbench({ queues: [emailQueue] }), {
  prefix: "/jobs",
});
await app.listen({ port: 3000 });
```

--------------------------------

### Mount Workbench in Hono

Source: https://getworkbench.dev/docs/frameworks/hono

Configure the Workbench dashboard as a sub-app route using the workbench middleware.

```typescript
import { Hono } from "hono";
import { Queue } from "bullmq";
import { workbench } from "@getworkbench/hono";

const app = new Hono();
const emailQueue = new Queue("email", {
  connection: { url: process.env.REDIS_URL! },
});

app.route("/jobs", workbench({ queues: [emailQueue] }));

export default app;
```

--------------------------------

### Configure MCP authentication

Source: https://getworkbench.dev/docs/getting-started/authentication

Provide credentials via environment variables when connecting the MCP server to an authenticated dashboard.

```shell
WORKBENCH_URL=http://localhost:3000/jobs \
WORKBENCH_USERNAME=admin \
WORKBENCH_PASSWORD=hunter2 \
npx @getworkbench/mcp
```

--------------------------------

### Register Workbench on server routes

Source: https://getworkbench.dev/docs/frameworks/tanstack-start

Register the handlers on both the base route and the catch-all route to ensure proper path resolution.

```typescript
// src/routes/jobs.ts
import { createFileRoute } from "@tanstack/react-router";
import { workbenchHandlers } from "../lib/workbench-handlers";

export const Route = createFileRoute("/jobs")({
  server: { handlers: workbenchHandlers },
});
```

```typescript
// src/routes/jobs/$.ts
import { createFileRoute } from "@tanstack/react-router";
import { workbenchHandlers } from "../../lib/workbench-handlers";

export const Route = createFileRoute("/jobs/$")({
  server: { handlers: workbenchHandlers },
});
```

--------------------------------

### Mount Workbench in Nuxt Server Routes

Source: https://getworkbench.dev/docs/frameworks/nuxt

Configure the Workbench handler in a Nitro server route file, providing the necessary BullMQ queues.

```typescript
// server/routes/jobs/[...].ts
import { Queue } from "bullmq";
import { workbench } from "@getworkbench/nuxt";

const emailQueue = new Queue("email", {
  connection: { url: process.env.REDIS_URL! },
});

export default workbench({
  queues: [emailQueue],
  basePath: "/jobs",
});
```

--------------------------------

### Mount Workbench in Astro routes

Source: https://getworkbench.dev/docs/frameworks/astro

Configure the Workbench dashboard within an Astro API route file. Ensure the project is set to server or hybrid output mode.

```typescript
// src/pages/jobs/[...workbench].ts
import { Queue } from "bullmq";
import { workbench } from "@getworkbench/astro";

const emailQueue = new Queue("email", {
  connection: { url: process.env.REDIS_URL! },
});

export const { GET, POST, PUT, PATCH, DELETE, prerender } = workbench({
  queues: [emailQueue],
  basePath: "/jobs",
});
```

--------------------------------

### Mount Workbench in AdonisJS routes

Source: https://getworkbench.dev/docs/frameworks/adonis

Register the Workbench dashboard route in start/routes.ts by providing the router instance and configured BullMQ queues.

```typescript
// start/routes.ts
import router from "@adonisjs/core/services/router";
import { Queue } from "bullmq";
import { mountWorkbench } from "@getworkbench/adonis";

const emailQueue = new Queue("email", {
  connection: { url: process.env.REDIS_URL! },
});

mountWorkbench(router, "/jobs", { queues: [emailQueue] });
```

--------------------------------

### Mount Workbench in h3

Source: https://getworkbench.dev/docs/frameworks/h3

Configure the Workbench handler and register it with the h3 router. Ensure the handler is registered at both the base path and the wildcard path to correctly match sub-segments.

```typescript
import { createServer } from "node:http";
import { createApp, createRouter, toNodeListener } from "h3";
import { Queue } from "bullmq";
import { workbench } from "@getworkbench/h3";

const emailQueue = new Queue("email", {
  connection: { url: process.env.REDIS_URL! },
});

const handler = workbench({ queues: [emailQueue], basePath: "/jobs" });

const router = createRouter()
  .use("/jobs", handler)
  .use("/jobs/**", handler);
const app = createApp().use(router);

createServer(toNodeListener(app)).listen(3000);
```

--------------------------------

### Configure Custom Redis Prefix

Source: https://getworkbench.dev/docs/guides/redis-auto-discovery

Specify a custom prefix if the BullMQ deployment does not use the default value.

```typescript
workbench({ redis: process.env.REDIS_URL!, prefix: "myapp" });
```

--------------------------------

### Verify container health

Source: https://getworkbench.dev/docs/deployment/standalone-docker

Checks the status of the running Workbench instance.

```shell
curl http://localhost:3000/healthcheck
```

--------------------------------

### Seed Alerts in TypeScript

Source: https://getworkbench.dev/docs/guides/alerts

Define contact points and alerting rules within the workbench configuration object. These settings seed Redis only when the store is empty.

```typescript
workbench({
  queues: [emailQueue],
  basePath: "/jobs",
  alerts: {
    dashboardUrl: "https://jobs.example.com/jobs",
    contactPoints: [
      {
        id: "slack-prod",
        name: "Slack #ops",
        preset: "slack",
        url: process.env.SLACK_WEBHOOK_URL!,
        enabled: true,
        createdAt: Date.now(),
        updatedAt: Date.now(),
      },
    ],
    rules: [
      {
        id: "failed-jobs",
        name: "Job failed",
        enabled: true,
        trigger: "job_failed",
        severity: "warning",
        contactPointIds: ["slack-prod"],
        createdAt: Date.now(),
        updatedAt: Date.now(),
      },
    ],
  },
});
```

--------------------------------

### Export Workbench handlers

Source: https://getworkbench.dev/docs/frameworks/tanstack-start

Define the Workbench handlers in a shared module, specifying the queues and base path.

```typescript
// src/lib/workbench-handlers.ts
import { Queue } from "bullmq";
import { workbench } from "@getworkbench/tanstack-start";

const emailQueue = new Queue("email", {
  connection: { url: process.env.REDIS_URL! },
});

export const workbenchHandlers = workbench({
  queues: [emailQueue],
  basePath: "/jobs",
});
```

--------------------------------

### Image registry naming convention

Source: https://getworkbench.dev/docs/deployment/standalone-docker

The naming format for versioned and latest images published to GHCR.

```text
ghcr.io/<owner>/workbench-standalone:<version>
ghcr.io/<owner>/workbench-standalone:latest
```

--------------------------------

### Enable read-only mode

Source: https://getworkbench.dev/docs/getting-started/authentication

Set the readonly flag to true to disable all write actions like retrying, removing, or promoting jobs in the UI.

```typescript
workbench({
  queues: [emailQueue],
  readonly: true,
});
```
Tokens:
Raw