API reference

• Entry points
• CLI
• Components: WorkflowRunsDashboard · RunsTable · RunDetail · StatusSummary · FilterBar · Pagination · LiveToggle · StatusBadge
• WorkflowRunsProvider
• Hooks: useWorkflowRuns · useWorkflowRun · useWorkflowRunStats · useRunActions · useRunFilters · useWorkflowRunsClient
• Helpers
• createFetchClient
• Server adapters
• HTTP API
• Security
• Styling & customization
• Architecture

Entry pointsCopy Anchor Link

Client code never imports the server entries, so a browser bundle does not pull in the engine.

Peer dependencies: react >= 18, react-dom >= 18, @tanstack/react-query >= 5, tailwindcss ^4, pg-workflows >= 0.13.0. pg-workflows in turn needs pg.

CLICopy Anchor Link

npx @pg-workflows/ui [--database-url=<url>] [--port=3777]

• The server binds to 127.0.0.1 only. It has no authentication and no resolveContext, so anyone who can reach the port can read and change every run. Do not expose it.
• It starts an engine with no registered workflows. engine.start() runs migrations if needed. Because no workflows are registered, the runs table shows step progress only from each run's timeline.
• engine.start() also starts queue workers on the shared run queue. A job those workers pick up fails with Workflow <id> not found, because the CLI has no definitions. Prefer it for local databases, and embed the components in your app when it runs against a live queue.
• It serves the API under /workflow-runs and the prebuilt dashboard on every other path.

ComponentsCopy Anchor Link

Every component takes className, style, and render (see Styling & customization) and forwards a ref to its root element. StatusSummary is the exception when it renders nothing.

WorkflowRunsDashboardCopy Anchor Link

Self-contained dashboard. It creates its own QueryClient (with query retries off) and WorkflowRunsProvider. Pass exactly one of baseUrl or client.

The workflow filter lists the workflow IDs on the current page. Style state: { selected: boolean }.

RunsTableCopy Anchor Link

Columns: Workflow, Run ID (copyable), Resource ID, Status, Started, Completed, Duration. The Workflow cell shows step progress for running, paused, and failed runs, using the larger of the timeline's step count and totalSteps. Style state: { empty: boolean, loading: boolean }.

RunDetailCopy Anchor Link

Must render under WorkflowRunsProvider. It calls useWorkflowRun(runId) and useRunActions().

It renders:

• A header with the workflow ID, run ID, and step progress.
• A details grid: workflow, resource ID, status, timestamps, duration, retries, priority, job, and error. Priority 100, 0, and -100 display as high, normal, and low.
• The actions: Cancel, Pause, Resume, Fast-forward, and Trigger. All are disabled once the run is terminal. Pause is enabled only while the run is running, and Resume only while it is paused. Each action shows a success or error message.
• The step timeline, and input and output JSON. A failed run's error is shown above the steps.

Fast-forward sends no data. The engine completes the current wait step only when the run is paused on one, and otherwise returns the run unchanged. Trigger always sends an event named resume with no data. To send another event, call useRunActions().trigger yourself.

Style state: { phase: 'loading' | 'error' | 'ready', status?: string }.

StatusSummaryCopy Anchor Link

Renders one button per status with a count above zero. When every count is 0, it renders nothing, so there is no element for ref. Style state: { empty: boolean } (always false while rendered).

FilterBarCopy Anchor Link

Style state: { active: boolean }.

PaginationCopy Anchor Link

Style state: { hasPrev, hasNext, fetching }.

LiveToggleCopy Anchor Link

A Base UI Toggle.

Style state: Base UI toggle state (pressed, disabled). Also sets data-pressed and data-fetching.

StatusBadgeCopy Anchor Link

Sets data-status. Style state: { status }.

WorkflowRunsProviderCopy Anchor Link

The hooks use TanStack Query, so the provider must render inside a QueryClientProvider.

HooksCopy Anchor Link

Every hook must run under WorkflowRunsProvider.

useWorkflowRuns(params)Copy Anchor Link

List query. Returns UseQueryResult<ListRunsResult>.

data is { items, nextCursor, prevCursor, hasMore, hasPrev }. The hook refetches while pollIntervalMs > 0 and keeps the previous page on screen while the next one loads. Each item is a WorkflowRun from pg-workflows, plus totalSteps? when the workflow is registered on the server's engine.

useWorkflowRun(id)Copy Anchor Link

Single run. Returns UseQueryResult<WorkflowRun>. The query is disabled while id is empty. It polls on the provider interval and stops once the status is terminal (completed, failed, or cancelled).

useWorkflowRunStats(params?)Copy Anchor Link

Counts by status. Returns UseQueryResult<Record<WorkflowRunStatus, number>>. params is { workflowId?: string }. Polls on the provider interval.

useRunActions()Copy Anchor Link

Returns { cancel, pause, resume, fastForward, trigger }. Each is its own UseMutationResult<WorkflowRun>, so isPending and error are tracked per action. On success, the run and every runs list are invalidated.

useRunFilters(initial?)Copy Anchor Link

Local filter state. initial: Partial<RunFilters> is merged over the defaults { limit: 20, sort: 'createdAt', dir: 'desc' }.

RunFilters:

Client-side fields apply to the current page only, because the engine paginates by cursor. Apply them with applyClientFilters and sortRuns.

Returns:

useWorkflowRunsClient()Copy Anchor Link

Returns { client, pollIntervalMs } from the provider. Throws outside WorkflowRunsProvider.

HelpersCopy Anchor Link

Exported from @pg-workflows/ui. <WorkflowRunsDashboard/> uses them to apply the client-side filters:

const rows = sortRuns(
  applyClientFilters(runs.data?.items ?? [], {
    search: filters.search,
    datePreset: filters.datePreset,
    durationPreset: filters.durationPreset,
  }),
  filters.sort,
  filters.dir,
)

createFetchClient(options)Copy Anchor Link

From @pg-workflows/ui or @pg-workflows/ui/client (no React). Returns a WorkflowRunsClient that calls the HTTP API.

interface WorkflowRunsClient {
  listRuns(params: ListRunsParams): Promise<ListRunsResult>
  getRun(id: string): Promise<WorkflowRun>
  getStats(params?: { workflowId?: string }): Promise<WorkflowRunStats>
  cancelRun(id: string): Promise<WorkflowRun>
  pauseRun(id: string): Promise<WorkflowRun>
  resumeRun(id: string): Promise<WorkflowRun>
  fastForwardRun(id: string, body?: { data?: Record<string, unknown> }): Promise<WorkflowRun>
  triggerEvent(id: string, body: { eventName: string; data?: Record<string, unknown> }): Promise<WorkflowRun>
}

Any non-2xx response throws an Error with the status code in its message. To back the components with something other than HTTP, implement the interface yourself.

Server adaptersCopy Anchor Link

engine only needs the methods the API calls (getRuns, getRun, getStats, cancelWorkflow, pauseWorkflow, resumeWorkflow, fastForwardWorkflow, triggerEvent) and optionally workflows, which supplies totalSteps. A WorkflowEngine has all of them.

The adapters use Web Request / Response and send no CORS headers. Serve the dashboard and the API from the same origin, for example with a Vite dev-server proxy.

Next.js App RouterCopy Anchor Link

Add it to your app covers the App Router setup: an engine singleton in lib/engine.ts and one catch-all route.

• Pass getEngine, not getEngine(). The handler calls it on every request, so it must return the same engine each time.
• The first request awaits engine.start(), and later requests reuse that promise.
• <WorkflowRunsDashboard/> can be imported from a Server Component. The components carry their own 'use client' directives.

Next.js Pages RouterCopy Anchor Link

Set basePath to the public URL Next puts on the request:

// pages/api/workflow-runs/[[...path]].ts
import { createPagesApiHandler } from '@pg-workflows/ui/next'
import { getEngine } from '@/lib/engine'

export default createPagesApiHandler({ engine: getEngine, basePath: '/api/workflow-runs' })

<WorkflowRunsDashboard baseUrl="/api/workflow-runs" />

ExpressCopy Anchor Link

import express from 'express'
import { createWorkflowRunsApi, toNodeHandler } from '@pg-workflows/ui/server'
import { engine } from './engine'

const runsApi = createWorkflowRunsApi({ engine, basePath: '/workflow-runs' })

const app = express()
app.use('/workflow-runs', toNodeHandler(runsApi))

• basePath must match the mount. toNodeHandler reads req.originalUrl, which keeps the prefix that Express strips from req.url.
• Don't run express.json() on this path. It consumes the body before the handler can read it.

HonoCopy Anchor Link

app.all('/workflow-runs', (c) => runsApi.fetch(c.req.raw))
app.all('/workflow-runs/*', (c) => runsApi.fetch(c.req.raw))

TanStack StartCopy Anchor Link

The list path and the splat are separate files, because /workflow-runs/$ does not match GET /workflow-runs.

// src/routes/workflow-runs.index.ts
export const Route = createFileRoute('/workflow-runs')({
  server: { handlers: { GET: ({ request }) => runsApi.fetch(request) } },
})

// src/routes/workflow-runs/$.ts
const handle = ({ request }: { request: Request }) => runsApi.fetch(request)
export const Route = createFileRoute('/workflow-runs/$')({
  server: { handlers: { GET: handle, POST: handle } },
})

Bun and DenoCopy Anchor Link

Bun.serve({ fetch: (request) => runsApi.fetch(request) })
Deno.serve((request) => runsApi.fetch(request))

Requests outside basePath get a 404 from the adapter.

HTTP APICopy Anchor Link

All paths are under basePath (default /workflow-runs). Responses are JSON.

Errors return { error, message?, issues? }. issues lists validation failures. An in_progress error also carries workflowId and runId.

SecurityCopy Anchor Link

The adapter leaves authentication to your app, so put the routes behind your own middleware.

For scoping, use resolveContext. The resourceId it returns is passed to every read and every action, so a caller only sees and changes their own runs. The adapter never reads resourceId from the request.

createWorkflowRunsApi({
  engine,
  // Return the caller's tenant. Throw to respond with 401.
  resolveContext: async (req) => ({ resourceId: await getTenantId(req) }),
})

getTenantId stands for your own session lookup.

Open by default. Without resolveContext, the adapter reads and changes every run in the database. That is fine for a single-tenant dashboard behind your auth. Pass resolveContext when several tenants share the database.

Styling & customizationCopy Anchor Link

The components are Base UI parts with a default theme: square corners, a 1px ink border, neutral surfaces, and a hard offset shadow. Status color is the only chroma.

• className and style take a value, or a function of the component's state (listed with each component above).
• render replaces the root element instead of wrapping it. The part's props and behavior move to the element you pass.
• State is also written as data-* attributes, so plain CSS can target it.
• Style the public root and documented parts (stat on StatusSummary). Markup inside a part may change between releases.

Recolor with CSS variables. Override any --pgw-* token on :root or a closer scope:

:root {
  --pgw-accent: #6d28d9;
  --pgw-accent-fg: #fff;
  --pgw-border: #e5e5e5;
  --pgw-radius: 0.5rem;
  --pgw-font: 'IBM Plex Sans', sans-serif;
  --pgw-focus: #6d28d9;
  --pgw-status-running: #2563eb;
}

The other tokens are --pgw-bg, --pgw-fg, --pgw-card, --pgw-muted, --pgw-muted-fg, --pgw-hover, --pgw-active, --pgw-disabled, --pgw-shadow, --pgw-on-status, --pgw-status-completed, --pgw-status-failed, --pgw-status-paused, --pgw-status-cancelled, and --pgw-status-pending.

Dark mode follows prefers-color-scheme. There is no toggle yet.

Restyle one component with the style hooks:

<StatusBadge
  status={run.status}
  className={(state) => (state.status === 'failed' ? 'ring-2 ring-red-600' : undefined)}
/>

<StatusSummary counts={counts} stat={{ className: 'uppercase tracking-wide' }} />

.pgw-badge[data-status='failed'] { color: #b91c1c; }
.pgw-live[data-pressed] { border-color: var(--pgw-status-running); }

Use the tokens in your own markup. styles.css registers them with Tailwind v4 @theme: bg-pgw-bg, text-pgw-fg, border-pgw-border, text-pgw-status-running, shadow-pgw, font-pgw, and more.

<span className="bg-pgw-status-running px-2 text-pgw-on-status">running</span>

Add pgw-root to your container when you compose the components yourself. It sets the background, foreground, and font. <WorkflowRunsDashboard/> already applies it. The stable classes .pgw-button, .pgw-badge, .pgw-input, .pgw-popup, .pgw-filters, .pgw-stat, and .pgw-live live in @layer components, so your utilities override them.

With a JS Tailwind config instead of @source, add the preset and the package to content. The preset covers a subset of the color tokens. It omits pgw-card, pgw-accent-fg, and pgw-disabled, and adds no shadow-pgw or font-pgw.

import pgwPreset from '@pg-workflows/ui/tailwind'

export default {
  presets: [pgwPreset],
  content: ['./node_modules/@pg-workflows/ui/dist/**/*.js'],
}

ArchitectureCopy Anchor Link

flowchart LR
  UI["Components and hooks"] --> Client["createFetchClient"]
  Client --> HTTP["HTTP /workflow-runs"]
  HTTP --> API["createWorkflowRunsApi"]
  API --> Engine["WorkflowEngine"]
  Engine --> DB[("PostgreSQL")]

The components call the hooks, the hooks call the HTTP API through the client, and the server adapter calls WorkflowEngine. Only the server connects to Postgres.