@bpmn-sdk/operate

Monitoring and operations frontend for Camunda 8 clusters — real-time SSE, zero dependencies

Documentation · GitHub · Changelog

Overview

@bpmn-sdk/operate is a zero-dependency monitoring and operations frontend for Camunda 8. Mount it into any HTML element to get a full process monitoring UI — live dashboard, instance browser, incident management, job queue, and user tasks.

It pairs with the @bpmn-sdk/proxy local server, which polls the Camunda REST API server-side and pushes updates via Server-Sent Events. The frontend stays clean with no polling timers.

A mock mode (mock: true) ships fixture data without any running proxy or cluster — useful for demos and local development.

Features

• Dashboard — real-time stats: active instances, open incidents, active jobs, pending tasks
• Process Definitions — deployed process list with name, version, and tenant
• Process Instances — paginated list with state filter (Active / Completed / Terminated)
• Instance Detail — BPMN canvas via @bpmn-sdk/canvas with live token-highlight overlay; active elements glow amber, visited elements show green tint
• Incidents — error type, message, process, and resolution state
• Jobs — job type, worker, retries, state, error message
• User Tasks — name, assignee, state, due date, priority
• Profile switcher — header dropdown populated from the proxy /profiles endpoint; switches reconnect all SSE streams
• Mock/demo mode — fully self-contained fixture data, no cluster required
• SSE architecture — proxy polls server-side; frontend opens one EventSource per view, gets pushed updates
• Hash router — #/, #/instances, #/instances/:key, #/definitions, etc.
• Themeable — light / dark / auto via --bpmn-* CSS custom properties from @bpmn-sdk/ui; theme choice persisted to localStorage

Installation

npm install @bpmn-sdk/operate @bpmn-sdk/proxy

Quick Start

Demo mode (no cluster needed)

import { createOperate } from "@bpmn-sdk/operate"

createOperate({
  container: document.getElementById("app")!,
  mock: true,
  theme: "auto",
})

Connected to a real Camunda cluster via proxy

import { createOperate } from "@bpmn-sdk/operate"

createOperate({
  container: document.getElementById("app")!,
  proxyUrl: "http://localhost:3033",   // default
  profile: "production",               // optional, uses active profile if omitted
  pollInterval: 15_000,                // ms between server-side polls (default: 30 000)
  theme: "dark",
})

The proxy must be running (pnpm proxy) and have at least one profile configured via the casen CLI.

How it works

Browser  ──── EventSource ────▶  @bpmn-sdk/proxy  ──── CamundaClient ────▶  Camunda cluster
         ◀─── SSE events ──────  (polls on interval, pushes results)

1. Each view opens an SSE connection to /operate/stream?topic=<view>&interval=<ms>.
2. The proxy creates a CamundaClient using the configured profile's auth credentials.
3. On each polling tick, the proxy fetches the relevant Camunda data and emits a { type: "data", payload } SSE event.
4. The store updates and the view re-renders.

API Reference

createOperate(options)

interface OperateOptions {
  container: HTMLElement
  proxyUrl?: string        // default: "http://localhost:3033"
  profile?: string         // profile name; uses active profile if omitted
  theme?: "light" | "dark" | "auto"  // default: "auto"
  pollInterval?: number    // ms between polls; default: 30 000
  mock?: boolean           // use built-in fixture data; default: false
}

Returns an OperateApi:

interface OperateApi {
  el: HTMLElement
  setProfile(name: string | null): void
  setTheme(theme: "light" | "dark" | "auto"): void
  navigate(path: string): void  // e.g. "/instances/123456789"
  destroy(): void
}

Related Packages

License

MIT © bpmn-sdk