Skip to content
D
Documentation

Build a workflow editor

how-to
3 min readUpdated

Use a diagram as the workflow document: nodes represent steps, typed ports constrain connections, the engine supplies history, and node data records execution state. The result is an editor that renders a connected workflow, rejects invalid links, can run the graph, and can save and restore the document.

When to use this

Use this pattern when users create or edit a directed process rather than view a fixed diagram. The model remains the source of truth: keep the step configuration in data, keep connection rules on ports, and update the live instance after execution changes.

The same engine drives every binding. The JavaScript example uses render;

Define the workflow document

Create a shared module. The two nodes have explicit input and output ports. The output carries dataType: 'event', while the input accepts only event; a connection from the output to the input is therefore legal, and a connection in the reverse direction is not. The live objects below are NodeModel and PortModel; the renderer creates them from these specs. Use NodeSpec and EdgeSpec for the plain data arrays.

ts
import type { EdgeSpec, NodeSpec } from '@grafloria/renderer';

export const nodes: NodeSpec[] = [
  {
    id: 'trigger',
    type: 'workflow-step',
    position: { x: 80, y: 120 },
    size: { width: 170, height: 72 },
    data: { label: 'Receive commit', status: 'idle' },
    ports: [
      { id: 'trigger-out', side: 'right', type: 'output', dataType: 'event' },
    ],
  },
  {
    id: 'deploy',
    type: 'workflow-step',
    position: { x: 380, y: 120 },
    size: { width: 170, height: 72 },
    data: { label: 'Deploy staging', status: 'idle' },
    ports: [
      { id: 'deploy-in', side: 'left', type: 'input', dataType: 'event' },
      { id: 'deploy-out', side: 'right', type: 'output', dataType: 'event' },
    ],
  },
];

export const edges: EdgeSpec[] = [
  {
    id: 'trigger-to-deploy',
    source: 'trigger',
    sourceHandle: 'trigger-out',
    target: 'deploy',
    targetHandle: 'deploy-in',
    type: 'orthogonal',
  },
];

export function setExecutionState(
  instance: import('@grafloria/renderer').DiagramInstance,
  nodeId: string,
  status: 'idle' | 'running' | 'success' | 'failed',
): void {
  const node = instance.getModel().getNode(nodeId);
  if (!node) return;
  node.setData('status', status);
  node.setSelected(status === 'running');
  instance.render();
}

For persistence, use DiagramSerializer in a browser-safe module:

ts
import { DiagramSerializer } from '@grafloria/engine';
import type { DiagramInstance } from '@grafloria/renderer';

export function saveDocument(instance: DiagramInstance): string {
  return JSON.stringify(new DiagramSerializer().serialize(instance.getModel()));
}

export function restoreDocument(instance: DiagramInstance, text: string): void {
  const document = JSON.parse(text) as ReturnType<DiagramSerializer['serialize']>;
  const model = new DiagramSerializer().deserialize(document);
  instance.getEngine().setDiagram(model);
  instance.renderNow();
}

Use the second module in the framework samples. It serializes the complete model, including ports and links. Restoring replaces the engine's diagram and repaints the mounted canvas.

Mount it in JavaScript

Give the host a resolved height. The canvas displays the two connected steps, and the buttons change the live model, validate it, and round-trip it through JSON. The example uses the shipped LIGHT_THEME.

ts
import { render } from '@grafloria/element';
import { LIGHT_THEME } from '@grafloria/renderer';
import { nodes, edges, setExecutionState } from './workflow';
import { saveDocument, restoreDocument } from './workflow-persistence';

const host = document.getElementById('workflow')!;
host.style.height = '420px';
const instance = render({ nodes, edges }, host, {
  theme: LIGHT_THEME,
  interaction: { portVisibility: 'always' },
});
const engine = instance.getEngine();

document.getElementById('run')!.addEventListener('click', () => {
  setExecutionState(instance, 'trigger', 'success');
  setExecutionState(instance, 'deploy', 'running');
});
document.getElementById('validate')!.addEventListener('click', () => {
  console.log(engine.validateDiagram({ validateTypes: true, validateConnections: true }));
});
document.getElementById('save')!.addEventListener('click', () => {
  localStorage.setItem('workflow', saveDocument(instance));
});
document.getElementById('load')!.addEventListener('click', () => {
  const text = localStorage.getItem('workflow');
  if (text) restoreDocument(instance, text);
});
document.getElementById('undo')!.addEventListener('click', () => {
  void engine.undo();
});
html
<div id="workflow" style="height: 420px"></div>
<button id="run">Run</button>
<button id="validate">Validate</button>
<button id="save">Save</button>
<button id="load">Load</button>
<button id="undo">Undo</button>
<script type="module" src="./main.ts"></script>
The mounted canvas shows two workflow steps joined by a connecting edge.

Clicking Run changes the trigger to a success state and selects the deploy step as the running step; the renderer repaints the model change. A custom node can read the stored status to draw its own success or running badge. Dragging or connecting nodes creates engine history entries, and Undo removes the latest user edit.

Mount it in Angular, Qwik, React, and Vue

Each binding mounts a real component with the same nodes and edges. Store the instance in the binding's mount callback; do not create it in render code. The host styles give the canvas height.

ts
import { Component } from '@angular/core';
import { GrafloriaDiagramComponent } from '@grafloria/angular';
import type { RenderOptions } from '@grafloria/element';
import type { DiagramInstance } from '@grafloria/renderer';
import { nodes, edges } from './workflow';

@Component({
  standalone: true,
  imports: [GrafloriaDiagramComponent],
  template: '<grafloria-diagram [spec]="spec" [options]="options" (ready)="ready($event)"></grafloria-diagram>',
  styles: ['grafloria-diagram { display: block; height: 420px; }'],
})
export class WorkflowComponent {
  readonly spec = { nodes, edges };
  readonly options: RenderOptions = { interaction: { portVisibility: 'always' } };
  instance?: DiagramInstance;

  ready(instance: DiagramInstance): void { this.instance = instance; }
}

All five mounted canvases show the same connected workflow. Call getEngine() through the stored instance for validation and undo, call getModel() to inspect or update step data, and call renderNow() when a subsequent measurement must observe the change synchronously.

Add validation and execution

Port direction, dataType, and connection limits provide structural validation while a user draws. For a complete document check, call validateDiagram() on the DiagramEngine and display its returned validation result. Your executor can walk from a trigger, set each node's status with setData(), and call render() after each step. The renderer then shows the state your node template reads from data.

Keep execution separate from editing: a run changes status data, while a drag or connection is a command on the shared history. For a toolbar action that edits the document, use a shipped command through the engine's command manager so the action participates in the same undo stack. See Commands, events, and undo for the command boundary and Ports and validation for custom rules.

Persistence and next steps

Store the string returned by saveDocument() in your database or browser storage. On load, call restoreDocument() on a mounted instance. Re-register any custom renderer before mounting the document; serialized data contains the model, not JavaScript renderer functions.

See the live workflow automation builder for insertion, editing, grouping, run state, and save/load in one editor.

The n8n-style workflow builder shows item counts, branch execution, pause/step controls, and a per-node details view.

For a smaller execution-state example, open Execute flow.

Pitfalls

  • A host without a resolved height renders a blank canvas. Give it a fixed height, a viewport height, or a flex/grid size; see Style a diagram.
  • undo() belongs to the engine, not DiagramInstance; call instance.getEngine().undo().
  • Changing node data does not rerun a declarative layout. Call the engine layout method explicitly, then repaint if you use the imperative layout path; see Auto-layout a diagram.
  • A custom node needs the custom-node flag and its renderer must be registered before mount; see Create custom nodes.

Was this page helpful?