DEV Community: Workflow Builder

Parameters change everything: passing data between workflow nodes

Piotr Błaszczyk — Tue, 21 Jul 2026 12:34:45 +0000

TL;DR Workflow Builder is an open-source (Apache 2.0) React SDK for embedding a visual workflow editor in your own product. It is built on React Flow: the canvas comes from React Flow, Workflow Builder is the layer above it (nodes as JSON schemas, properties panel, validation, execution). This article is about one feature, the Variable Picker, which lets one node read another node's output. Type {{ into a field and the editor offers only the data that exists at that point in the graph, already type-checked. Underneath it took output schemas in JSON, a graph reachability walk for scoping, and a strict template resolver. Real code included.

Disclosure: I am the creator of the Workflow Builder SDK and have been building it since the first commit. Keep that in mind while reading.

This article first appeared on the Workflow Builder blog.

Drop a few boxes on a canvas, connect them with arrows, and you have a workflow. Do this, then this, then that. It runs, top to bottom, each box doing its one fixed thing.

It works, but it is a trivial program. Nothing one box produces can reach the next, so no step can build on what another did. It only becomes a real program once one node can use the output of another.

A node is a function

Here is why nothing flows between the boxes. A node is a function, and right now it receives no inputs. Think about how that works in code. A function with no arguments is rarely interesting.

sendEmail();

What does it send? To whom? It is a black box with a label.

Now give it parameters:

sendEmail(to, subject, body);

Suddenly it is a tool. The same function serves a thousand different cases, because the caller decides what flows in. The signature is a contract. It says "give me these three things and I will do the rest."

A node in Workflow Builder is exactly this. An empty action node is sendEmail(). A configured one is sendEmail(to, subject, body). The whole value of the editor lives in that gap.

So the interesting problem in building a workflow editor is not the canvas. It is this: how does a node get its inputs?

Where do the arguments come from

An argument gets its value from one of two sources. The first is a literal. You type the value in by hand. subject = "Welcome aboard". This is fine for constants, and useless for anything that depends on what happened earlier in the run.

The second is a reference. You point at the output of a step that already ran, and let the real value be filled in when the workflow executes. The email subject is not a string you typed. It is "whatever the Classify step decided this request was about."

That second source is the Variable Picker. Say an upstream Classify node has just tagged an incoming support ticket as Billing. In the email node's Subject field you type {{, and instead of guessing at variable names, you get a panel of everything that is actually available at that point in the graph. You pick one. The field shows a friendly chip, {{ Classify · Category }}, while the diagram quietly stores the durable form:

{{nodes.classify-1.category}}

This is the same idea as wiring one function's return value into another function's argument. We made the wiring visual, and we made it impossible to wire to something that is not there.

Types, because data has a shape

As soon as data flows between steps, it has a shape, and shapes can be wrong.

A Decision node comparing "is greater than" only makes sense for numbers and dates. Feeding it a boolean is not a clever edge case. It is a bug the user did not mean to write. So every output a node can emit declares its type, drawn from a small, deliberate set:

type VariableTypePrimitive = 'string' | 'number' | 'boolean' | 'datetime' | 'date';
type VariableType = VariableTypePrimitive | 'object' | 'array';

The picker reads those types and filters itself. When a field expects a number, the panel only offers numbers. When it expects a date, it also offers datetimes, because a datetime is a date with extra precision. The available comparison operators shift with the type too. Strings get "contains." Numbers get "greater than." Dates get "before" and "after." The interface never lets the user assemble a comparison that cannot mean anything.

This is types-as-validation, except the user never sees a red error. They simply are not offered the wrong choice in the first place.

The filter is strict but not naive. User input arrives as strings, so a few cross-type pairings are allowed on purpose:

A number can fill a string field.
A valid date string satisfies a date field, and date and datetime are interchangeable.
The only boolean literals it accepts are '', 'true', and 'false'.

Everything else is refused. The picker coerces where the meaning is unambiguous and refuses where it is not.

A node can only see what runs before it

In a programming language, a variable has a scope. You cannot read a value that has not been assigned yet, and you cannot reach into a block that never ran. A workflow has exactly the same rule, drawn in two dimensions on a canvas, and a serious editor has to respect it.

Some variables are global. Secrets, tenant configuration, an API base URL. Available everywhere, from the first node to the last.

But most variables are earned. A node can only reference the output of a step that genuinely runs before it. Concretely, that means a step somewhere upstream, reachable by walking the arrows backward from the current node. The picker computes this directly. It runs a breadth-first search back through the edges to collect every ancestor of the selected node, and offers their outputs and nothing else:

// BFS backward through edges to find all ancestor nodes
const ancestors = new Set<string>();
const queue = [nodeId];

while (queue.length > 0) {
  const current = queue.shift()!;
  for (const edge of edges) {
    if (edge.target === current && !ancestors.has(edge.source)) {
      ancestors.add(edge.source);
      queue.push(edge.source);
    }
  }
}

The consequence is exactly the scoping rule you would want. A node sees what flows into it. It cannot see a sibling on a parallel branch that never reaches it. It cannot see a node downstream of itself either, because that data does not exist yet when this step runs. The graph topology is the scope. We did not invent a new mental model. We took the one every programmer already has and rendered it on the canvas.

One honest note on that code. This is really a reachability walk, not a meaningful breadth-first one. Order does not matter, because we collect the whole set of ancestors, so depth-first would behave the same. The inner loop rescans every edge on each step, so it runs in O(ancestors × edges). That is fine at workflow scale. It would not be fine in a general graph library.

Simple when it works, loud when it fails

Everything above is plumbing. For the end user it collapses into one gesture: focus a field, type {{, pick from a panel grouped by upstream step, and keep typing around the chip. The editor only ever offers things that work, and the hard part disappears into a two-character keystroke.

We took one more deliberate stance for the moment things go wrong. A reference is strict by default. If a path cannot be resolved at run time, the run fails loudly with Unresolved template reference, rather than silently substituting an empty string and shipping it to an LLM. A typo in a prompt should break on the first run, not three weeks later in production. When absence is genuinely expected, the user opts into a fallback on purpose:

{{nodes.classify-1.category?}}                          // resolves to '' if missing
{{nodes.classify-1.category | default:'unclassified'}}  // resolves to a default

Strictness needs one more distinction to be safe. The resolver parses in two stages. An outer pass catches anything that looks like a reference: a {{namespace.path}} block with a dot, the marker that the author meant a reference and not literal text. An inner pass checks that body against the real grammar. So a token has three fates, not two:

{{nodes.foo?bar}} looks like a reference but breaks the grammar. It throws Malformed instead of leaking a broken token into a prompt.
{{total}} has no namespace dot, so the outer pass never claims it. It stays literal text.
A well-formed path that points at nothing throws Unresolved. Only the opt-in ? and default: quiet this last case.

Strict by default, lenient on request. The safe thing is automatic, the risky thing is a choice you make with your eyes open.

Because in Workflow Builder, everything is data

None of this would be possible if a node were just a React component with some props hardcoded in its source.

A node in Workflow Builder is a data definition. It always carried a schema, the JSON description of its own configurable inputs, the part that says "I am a function with this signature." Building the Variable Picker meant the other half of that contract had to exist as data too. So we extended the definition with an outputSchema:

type OutputProperty = {
  type: VariableType;
  label: string;
  description?: string;
};

That is the whole trick. The inputs of a node are data. The outputs of a node are now data. And because both halves of the contract are just JSON, the picker can read them, the type filter can reason over them, and the ancestor search can connect one node's outputs to another node's inputs. The SDK stops there. It stores the wiring as text and runs nothing itself. A backend resolves the references when the workflow runs. Workflow Builder ships a reference backend so you can watch the whole loop work, then swap in your own. A node that wants to participate adds an outputSchema. A node that does not, simply never shows up in any downstream picker. No special cases. No component knows about any other component. The graph and the schemas carry all the meaning.

This is how we tend to think on this project. When we want a new capability, the first question is rarely "what component do we build." It is "what does this need to become data, and what can read that data." Make the contract explicit and make it JSON. After that, a new capability is mostly a question of what each node reads and what it exposes.

The Variable Picker looks like a small convenience: two braces and a dropdown. Underneath, it is the feature that finally lets one box pass a value to the next. That is the line between "do this, then this" and a real program. Cross it and you have a tool. Stop short and you have a diagram.

From React Flow to Workflow Builder: what you keep, and what you gain

Dominika Pacholec — Thu, 16 Jul 2026 09:35:23 +0000

TL;DR: I've spent 7+ years building diagram-heavy and node-based UIs, so when I dug into Workflow Builder – our SDK at Synergy Codes – I went to the public source to see what it actually does to a React Flow app. Short version: it's a superset, not a replacement. React Flow stays underneath as a peer dependency, and your React Flow knowledge carries over. Where the work is: graph state moves into the SDK's store, and custom nodes get rewritten as node templates. This is an honest breakdown of what stays, what changes, and what you gain – every claim checked against the public source. If you're a React Flow dev weighing build-vs-buy for a workflow editor, this one's for you.

Disclaimer: I'm a frontend engineer at Synergy Codes, the company behind Workflow Builder. I build diagram and node-based UIs for a living, but I'm not on the Workflow Builder SDK team – I went through the public repo and docs to write this, and kept it honest, including the parts that cost you effort.

Originally published on the Workflow Builder blog.

A production workflow editor on React Flow isn't one feature – it's a properties panel, undo/redo, a palette, persistence, layout, validation. Workflow Builder gives you that whole layer while keeping React Flow underneath.

Can you still do everything you did in React Flow?

Yes. Almost everything you reach for in a React Flow editor works the same way inside Workflow Builder, because React Flow is still doing the work. Here is how the common building blocks map across:

What you do in React Flow	Status	In Workflow Builder
Render custom nodes	This changes	Start from 7 built-in node templates (trigger, action, conditional, decision, delay, notification, AI agent), or write your own as a node template with a schema for its data
Build custom edges (`EdgeProps`)	Same as React Flow	`EdgeProps` straight from React Flow, plus ready components like labeled and self-connecting edges
Configure the canvas and handle events (zoom, pan, fit view, `onNodeClick`, `onPaneClick`)	Same as React Flow	Props pass straight through to the underlying `<ReactFlow>`
Manage graph state (read and update)	This changes	Workflow Builder sits above React Flow and owns its state – the SDK store is the source of truth, and you read and update the graph through it. React Flow's hooks (`useReactFlow`, `useNodes`) stay available for reading and inspecting the live canvas
Build the core editor layer yourself	New in WB	A node library, a schema-driven properties panel, a drag-and-drop palette, read-only mode, and typed persistence (localStorage, REST, or callback)
Wire up editor basics yourself	New in WB	Undo / redo and copy / paste ship as free, open plugins on the public plugin API

Graph state is the one area that works differently. Workflow Builder runs React Flow in controlled mode and owns the graph in its own store, so the store is the source of truth: you read and update the graph through the SDK's actions. React Flow's hooks still return the live canvas state for reads and inspection, but the store – not direct nodes / edges mutation – is how you drive changes. Keeping state in a dedicated store is also a performance choice: it follows the patterns Synergy Codes' guide to optimizing React Flow performance recommends for keeping larger graphs responsive.

Everything else passes through. You hand React Flow props to Workflow Builder, and they land on the underlying canvas untouched. When you build nodes, edges, or plugins, you still import Handle, Position, and EdgeProps from @xyflow/react – same package, same docs, same upgrade path. And when you need the raw canvas API for something the SDK does not surface, it is still reachable.

What you gain on top

Workflow Builder adds the layer React Flow deliberately leaves to you – the part that turns a working canvas into a product. React Flow gives you a fast, flexible renderer. It does not give you a properties panel, history, or a palette, because those are application concerns. That is precisely the layer you would build by hand, and it is what Workflow Builder ships ready.

The table above lists what that layer includes. What a list cannot show is why each piece is worth having ready – most of it is work that looks small and turns out not to be:

A node library – the built-in node types (trigger, action, conditional, decision, delay, notification, AI agent) mean you are not modeling and styling the common workflow primitives from zero. You extend or replace them instead of inventing them.
A schema-driven properties panel – one schema drives the form, its validation, and the node's data shape, so they stay in sync as nodes evolve instead of drifting apart across three hand-maintained places.
Undo / redo – history is one of those features that looks simple and rarely is. You get a working implementation, built on a public change-tracking primitive, to keep as-is, swap for your own model, or drop.
A node palette – a ready drag-and-drop panel for adding nodes to the canvas, already connected to the store so dropped nodes land in the graph correctly.
Read-only mode – locking the canvas for viewers while keeping full inspection is state you would otherwise thread through every interaction by hand.
A typed workflow document – instead of persisting loose JSON and hoping it loads back correctly, the graph has one canonical, typed shape, older formats are migrated forward, and saving to localStorage, a REST endpoint, or a callback is a thin adapter on top.

React Flow renders a canvas but leaves the surrounding UI to you. Workflow Builder ships the same component library and design system it is built on, so the editor and the controls around it share one consistent look out of the box. It is fully tokenized, with theming and white-label support, so you can override tokens to make the editor match the app it is embedded in. That is polish React Flow leaves entirely to you.

The layer is plugin-first: optional features register through a public plugin API and can be added or removed without breaking the editor. The same plugin surface that builds the reference undo / redo also lets you add toolbar buttons, inject UI into known slots, and ship your own translations.

This is not theoretical. The demo app ships two full, open plugins built on the public plugin API – copy / paste and undo / redo – which prove the plugin API works and show the pattern you'd follow for your own. Heavier diagram operations – smart edge routing and node avoidance, edge reshaping, ELK auto-layout, and PDF export – are Enterprise features delivered through Overflow, and the other folders in the demo are placeholders.

Some of the heavier features sit in the Enterprise Edition, and it is worth being clear about the line. The open SDK exposes layout-direction control and fit-view helpers. Production-grade ELK auto-layout, smart edge routing, on-canvas edge reshaping, PDF export, and an in-browser flow runner are delivered through Overflow in the Enterprise Edition. Either way, React Flow stays the renderer underneath – these features layer on top, they do not replace it.

So the trade is the opposite of the one developers fear. You keep React Flow's full range, and you add the editor features that are surprisingly hard to build well. If something is possible in React Flow, it is possible in a Workflow Builder editor – plus a great deal you would otherwise build yourself.

When does moving from React Flow to Workflow Builder make sense?

A React Flow prototype that works eventually has to become a product – and that is when the properties panel, undo / redo, palette, and persistence stop being nice-to-haves. The choice at that point is whether to build the editor layer around React Flow yourself or start from one that already exists.

Adopting Workflow Builder does not mean rebuilding the canvas. It does mean changing where two things live. You mount <WorkflowBuilder.Root> instead of rendering <ReactFlow> yourself, and graph state moves into the SDK store. Your edge components carry over unchanged. Your custom nodes are rewritten as node templates, with their data described as a schema – that is the real migration work, and it is honest to call it work. What transfers is your React Flow knowledge; what changes is where the nodes and state live.

Because the SDK sits on React Flow instead of forking it, you are not locked in. React Flow stays underneath, the raw canvas stays reachable, and you keep its API and upgrade path. Backing out still means unwinding the node and state changes you made, but you are building on the library you already know, not a fork you would have to escape.

Workflow Builder is a production-ready React SDK for embedding visual workflow editors, built by Synergy Codes on top of React Flow. It ships as Community Edition (open source, Apache 2.0) and Enterprise Edition, and the team spent the 14–25 weeks of canvas work so you can start from the layer above. If you are weighing a React Flow workflow editor against building one from scratch, that head start is the whole point.

The open-source Community Edition is a solid start on its own, and enough to ship many editors. If you are building something more complex, Synergy Codes also runs discovery workshops to shape the product with your team – optional help, not a prerequisite for using the SDK.

How we turned our workflow editor into a real SDK

Jan Librowski — Tue, 02 Jun 2026 15:18:42 +0000

Workflow Builder is a visual editor for workflow graphs in React apps. For a long time it was a strong editor that had not yet grown into an SDK. The 2.0 release closes that gap. Same canvas, palette, and properties panel as before – but now it is something you adopt as a library, not a codebase you grow your product inside.

The difference between an editor and an SDK turned out not to be features. It was boundaries. This post is about the three we drew.

In short

A UI component library and an SDK differ by their boundaries, not their features. Workflow Builder could draw, configure, validate, and serialize a workflow graph, but adopting it meant taking the codebase, extending it meant reaching into internals, and running it meant building your own execution. Workflow Builder 2.0 draws three contracts – for installing, extending, and running it – that make it a library you build against.

From editor to SDK: what adoption actually takes

Workflow Builder began as a capable workflow-editor toolkit. Teams liked the canvas right away, then kept meeting the same three edges when they tried to ship it inside their own product.

First, there was no package to install. In practice you took the codebase and grew your product inside it.

Second, extending the editor meant reaching into its internals. Plugins leaned on private files and module load order, so a plugin written for one build rarely moved cleanly to another.

Third, the editor could draw, configure, validate, and serialize a graph, but it could not run one. Every team rebuilt the same execution plumbing – a job runner, retries, audit logs, persistence – in whatever stack they were already on.

None of these are missing features. They are missing boundaries – the contracts a team builds against instead of building around. That is the line between an editor and an SDK.

What makes something an SDK, not just a library

An SDK is defined by its contracts, not its features. Workflow Builder 2.0 draws three – one for installing it, one for extending it, one for running it:

installing it – one public surface, with internals kept private;
extending it – you add behavior by composing values, not by touching internals;
running it – the editor defines what a workflow needs to run, not which engine runs it.

No forking, just install it

Before 2.0, adopting Workflow Builder meant taking its codebase – in practice it was a rich template you forked and grew. 2.0 packages it as a real library with a single public surface: you install it, import from one entry point, and your app stays yours. Internals stay private, so you can't build on something we may change. Giving it the SDK name was part of this move to a package, not a relabel of the old setup.

// npm install @workflowbuilder/sdk

import { WorkflowBuilder } from '@workflowbuilder/sdk';
import '@workflowbuilder/sdk/style.css';

export function App() {
  return <WorkflowBuilder.Root nodeTypes={myNodeTypes} />;
}

Extend it without touching internals

Before, plugins ran side effects the moment they were imported and reached into internal files to do their work. That made them capable and unportable at the same time. The philosophy now is that extension is composition: you hand the editor the behavior you want, you do not patch the editor to get it.

A plugin is a value. You pass an array of them to the editor, and it runs them:

// A plugin is a value – a function that calls the SDK's register* APIs:
const copyPastePlugin: WorkflowBuilderPlugin = () => {
  registerComponentDecorator('OptionalHooks', {
    content: CopyPasteProvider,
    name: 'CopyPasteProvider',
  });
};

// You compose them on the editor:
<WorkflowBuilder.Root plugins={[copyPastePlugin, undoRedoPlugin, helpPlugin]} />

Each plugin registers through documented extension points, never private internals. So a plugin written in our demo drops into your app unchanged.

Run it on any engine

The editor used to draw graphs but never execute them, so every team rebuilt execution from scratch. The fix was to make the editor define the execution contract and stay out of the engine business: submit a workflow, run a node, emit events. Any engine that fulfills the contract can run the graph.

We picked Temporal as the first reference engine on purpose. Temporal has the strictest execution model we know of – a V8 sandbox, determinism constraints, replay-driven recovery. If our port contract holds up against that, easier engines – an in-memory test double, a BullMQ queue, or JSON-first platforms like Inngest or Restate – plug in through the same two interfaces. We're shipping Temporal first; the rest is one adapter away. Temporal also gives us, for free, the primitives every team kept rebuilding by hand: durable retries, idempotent activities, an audit trail by construction, and cancellation as a first-class signal.

The fit on the integration side was uncannily clean. Temporal's Workflow/Activity split maps one-to-one onto our pure-domain runner plus ActivityRunnerPort: the deterministic graph traversal lives in the Workflow, the side-effectful node executions live in Activities. proxyActivities lets us give each activity its own retry profile – short, aggressive retries for database writes; longer timeouts with fewer retries for node executions that may call LLMs. That separation falls out of Temporal's model; we did not engineer around it.

The graph runner itself is just a function. It takes the workflow plus your engine's two runtime hooks – a node runner and an event sink – and nothing else:

// What an engine has to fulfill – two small interfaces:
interface Runner { executeNode(node, ctx): Promise<NodeResult> }
interface Events {
  emitEvent(type, payload?): Promise<void>;
  updateStatus(status): Promise<void>;
}

// The graph runner: a function taking the workflow and those two hooks:
await runGraph(input, runner, events);

The Temporal adapter is what those hooks look like wired to Temporal primitives:

// apps/execution-worker/src/engines/temporal/workflows/run-workflow.ts (abridged)
const databaseActivities = proxyActivities<Pick<Activities, 'emitEvent' | 'updateStatus'>>({
  startToCloseTimeout: '30s',
  retry: { maximumAttempts: 5 },
});

const nodeActivities = proxyActivities<Pick<Activities, 'executeNode'>>({
  startToCloseTimeout: '10m',
  retry: { maximumAttempts: 2 },
});

const runner: ActivityRunnerPort<AiStudioNode> = {
  executeNode: (node, context) => nodeActivities.executeNode(node, context),
};

const events: EventEmitterPort = {
  emitEvent: (executionId, type, payload, nodeId) =>
    databaseActivities.emitEvent(executionId, type, payload, nodeId),
  updateStatus: (executionId, status, errorMessage) =>
    databaseActivities.updateStatus(executionId, status, errorMessage),
};

export async function runWorkflow(input: WorkflowExecutionInput<AiStudioNode>): Promise<void> {
  await runGraph(input, runner, events);
}

Swap Temporal for Inngest, Restate, or an in-memory test double by implementing those two interfaces against that engine's primitives. The editor does not change. We picked Temporal first as the hardest test on purpose – the simpler engines have less to ask of the contract, not more.

We proved it by building on it: AI Studio

The most reliable test of a contract is building something real on it. AI Studio is a full reference app – a workflow palette, real execution against the backend, and a live log that highlights nodes as they run. The AI Agent nodes call an LLM through OpenRouter, so set OPENROUTER_API_KEY in apps/execution-worker/.env before running a workflow (full setup in 'How to try it' below).

It rides the public SDK surface and the shared runtime-contract types – no reaching into editor internals. It runs the graph through the runtime contract, adds its execution UI through documented extension points, and talks to the backend through its own adapter. Nothing reaches around a boundary. That is the proof we wanted: a non-trivial product is buildable on the contract, not on our internals.

How to try it

Source at github.com/synergycodes/workflowbuilder.
Docs at workflowbuilder.io/docs.
The AI Agent nodes call an LLM through OpenRouter, so set a key before the stack runs a workflow end to end:

git clone https://github.com/synergycodes/workflowbuilder
cd workflowbuilder
pnpm install
# copy apps/execution-worker/.env.example to apps/execution-worker/.env and set OPENROUTER_API_KEY
pnpm preflight   # checks Node / pnpm / Docker / ports / .env before the stack starts
pnpm dev:ai-studio
# open http://localhost:4201

FAQ

What is Workflow Builder?

Workflow Builder is a React SDK for embedding visual workflow editors, built by Synergy Codes. It ships as an open-source Community Edition and a commercial Enterprise Edition with full source included.

Can I swap the execution engine?

Yes. The editor defines a runtime contract – submit a workflow, run a node, emit events – and stays out of the engine business. Temporal is the reference engine; implement the same contract to run on another.

Closing

We shipped the SDK before the platform on purpose. The boundary is the product: three contracts you can build against. There is still a lot to do – more reference adapters, more documented extension points, more sharp edges to find – and we are actively iterating. We would rather learn from what you build on the contracts than guess at the features behind them.
If you build something, share it with us or let us know what broke – open an issue.

I built a React circuit editor in a day with Workflow Builder

Kacper Cierzniewski — Mon, 01 Jun 2026 14:00:00 +0000

In short

Workflow Builder is generic enough to build non-workflow tools. In one day I built an interactive electrical-circuit editor with custom Battery, Switch, Lightbulb and Resistor nodes, a sub-200-line plugin that solves Ohm's law on every diagram change, and an LED-vs-incandescent cost comparison showing ~7× lower running cost for LEDs at the same brightness.

Background

As a frontend engineer at Synergy Codes I usually work on projects built from scratch. In my latest project we spent a lot of time building a custom diagram tool for electrical circuits, and I wanted to see how far I could get with Workflow Builder instead, in roughly one day of work.

The end result is a small interactive circuit editor with batteries, switches, resistors, lightbulbs, meters and an energy-cost calculator that compares LED and incandescent bulbs. This is the writeup of that day.

Reading the docs first

Before opening the editor I went through the documentation. Two things stood out.

First, there is a lot of it. Not only an API reference (which I would expect), but a proper introduction, an architecture overview, and a set of guides covering the things you actually need: custom nodes, plugins, persistence, JsonForms control. For a relatively young SDK that was a pleasant surprise.

Second, the docs are very explicit that Workflow Builder is the editor layer and execution is up to you. The framing matters, because it sets expectations: the SDK is going to give you the hooks rather than the answers.

Genericity is the keyword

The thing that makes Workflow Builder usable for something like a circuit editor is that almost nothing about it is workflow-specific.

Building custom nodes

Each node is described by a JSON Schema and a UI schema. There is a long list of building blocks already in the SDK (text inputs, labels, dropdowns, switches, accordions), and you arrange them in a vertical layout that drives the properties panel. The pattern is 4 small files per node, documented in Add a custom node. I will show what that looks like further down.

Embedding it as a React component

Workflow Builder ships as a React component on npm (@workflowbuilder/sdk), so dropping it into an existing app is a one-liner. You install the package, import WorkflowBuilder and its stylesheet, and mount <WorkflowBuilder.Root /> anywhere in your tree. All configuration – node types, plugins, persistence strategy, layout direction – is passed as props on that component, so the editor stays declarative and there is no separate factory or builder step to keep in sync.

import { WorkflowBuilder } from '@workflowbuilder/sdk';
import '@workflowbuilder/sdk/style.css';

import { demoPaletteItems } from './features/workflowbuilder/palette';
import { plugin as circuitSolverPlugin } from './features/workflowbuilder/plugins/circuit-solver/plugin-exports';
import { plugin as circuitReadoutsPlugin } from './features/workflowbuilder/plugins/circuit-readouts/plugin-exports';

function App() {
  return (
    <WorkflowBuilder.Root
      name="Bulb Comparison"
      layoutDirection="RIGHT"
      nodeTypes={demoPaletteItems}
      integration={{ strategy: 'localStorage' }}
      plugins={[circuitSolverPlugin, circuitReadoutsPlugin]}
    />
  );
}

That is the entire App.tsx for the circuit editor. Everything else in this writeup lives in the nodeTypes and plugins arrays.

Different built-in ways of data storing

Another thing that surprised me. Workflow Builder does not force any specific way of saving the diagram. There are 3 persistence strategies, picked via the integration prop on <WorkflowBuilder.Root />.

The first one is localStorage. This is the default, so if you do nothing you already have it. The SDK reads the diagram from localStorage when the editor mounts and writes it back when the user clicks Save (or when they close the tab, thanks to a beforeunload hook). Zero configuration, no backend, everything stays in the browser. Limitations are the obvious ones: data is per-browser and per-origin, capped around 5 MB.

The second one is REST API. You give the SDK 2 endpoints (one to GET the initial diagram from, one to POST the saved diagram to) and it handles the wiring for you.

The third one is callback (props strategy). You pass an onDataSave function and the SDK calls it whenever the diagram needs to persist. This is the escape hatch: if you need auth headers, custom error handling, file uploads, or any non-standard shape, this is the option that gives you full control.

For my one-day experiment I stayed with localStorage, but it is nice to know I will not have to rewrite anything when a real backend comes into the picture.

Let's build something

The starting point is a plain Vite + React app with @workflowbuilder/sdk installed and the snippet above as App.tsx. Standard commands:

pnpm i
pnpm dev

And the editor is up with the default (empty) diagram.

Tinker with the code

The first thing I wanted to modify is the node library. Based on the docs section on Node schemas, it looks like I just need to add a few schema files. Under src/feWorkflow Builder is great as a visualization tool and very generic, so iatures/workflowbuilder/nodes/ I added the nodes I needed for a simple circuit: Battery, Switch, Lightbulb, Ammeter, Voltmeter.

How I did it: the Battery example

For each node I created a folder with 4 files, following the canonical action example in the demo app. For Battery it looks like this.

battery/schema.ts describes the data the node holds:

import { sharedProperties, statusOptions } from '@workflowbuilder/sdk';
import type { NodeSchema } from '@workflowbuilder/sdk';

export const schema = {
  properties: {
    ...sharedProperties,
    status: { type: 'string', options: Object.values(statusOptions) },
    voltage: { type: 'number', minimum: 0 },
  },
} satisfies NodeSchema;

export type BatteryNodeSchema = typeof schema;

The sharedProperties spread gives me the standard label and description fields every node has, so I do not have to redeclare them.
Workflow Builder is great as a visualization tool and very generic, so i
battery/uischema.ts tells the SDK how to render the properties panel, in this case just a Text input for the voltage. battery/default-properties-data.ts holds the default values when the user drags a new Battery onto the canvas (I went with 9 V).

And finally battery/battery.ts ties everything together into a PaletteItem:

import type { PaletteItem } from '@workflowbuilder/sdk';

import { defaultPropertiesData } from './default-properties-data';
import { type BatteryNodeSchema, schema } from './schema';
import { uischema } from './uischema';

export const battery: PaletteItem<BatteryNodeSchema> = {
  type: 'battery',
  icon: 'BatteryFull',
  label: 'Battery',
  description: 'Power source providing voltage to the circuit.',
  defaultPropertiesData,
  schema,
  uischema,
};

The icon name (BatteryFull) is one of many ready-made icons exposed by the SDK – you reference them by string, no extra import needed. The last step is registering the node in src/features/workflowbuilder/palette.ts so it shows up in the left sidebar. That is the whole node. The other 3 (Switch, Lightbulb, Ammeter) follow exactly the same pattern.

Build the schema

Now I can see all the defined nodes in the palette:

I can drag and drop them onto the canvas and try to build something:

It is not interactive yet – this is only a visual presentation – but to this point it took me roughly 2 hours, including reading docs and writing this article, to get a working visualization. As I still had a lot of spare time, I figured I could try to make it more interactive. For example, when I turn off the switch, there should be no current and the bulb should stop glowing. The plugin API is well documented, so this should be doable.

The idea is crystallizing

I started with a simple lightbulb schema, but it looks like we can do a lot more. It should be possible to add some real logic and compare an LED bulb to a traditional one in terms of efficiency and cost. That is what I want to build.

Small adjustments

To make this work I added a few missing nodes. A Wattmeter to read the power going through a load. An Efficiency property on the Lightbulb (lumens per watt) so I can describe LED vs incandescent behavior. A Resistor so the circuit's total resistance is more than just the bulbs. And an Energy Stats node to show how much power and how much money the circuit costs over time.

Let's implement it

To make the circuit actually react to changes I wrote a small plugin called circuit-solver. The pattern is exactly what the docs describe. I registered a hook via the SDK plugin API (the OptionalHooks slot) that runs every time any node or edge in the diagram changes.

import { registerComponentDecorator } from '@workflowbuilder/sdk';

import { CircuitSolverRunner } from './circuit-solver-runner';

export function plugin(): void {
  registerComponentDecorator('OptionalHooks', {
    content: CircuitSolverRunner,
    name: 'CircuitSolver',
  });
}

The runner reads nodes and edges from the SDK store via useStore and runs a pure solver function. The solver walks the diagram starting from every Battery node, follows the outgoing edges around the loop, sums the resistances of every Resistor and Lightbulb it passes through (Lightbulb resistance is derived from V_nominal² / P_nominal), applies Ohm's law (I = V / R), and writes the resulting voltage, current and power back for every node in the loop. A Switch in the loop with isOn === false drops the current to zero everywhere.

The computed values land in a separate Zustand store. The readout plugin (which is the thing that paints the values directly on each node) just subscribes to that store. The solver stays pure, the readout stays React, and the two never collide. The whole solver fits in one file of around 250 lines.

One simplification: this only handles series circuits, one loop per battery, no branches. Parallel circuits and proper mesh analysis need Kirchhoff's laws, which is a much bigger task and not what I want to spend my one day on.

Now I need to draw the whole circuit:

It's alive!

When I turned the switch on, the logic from the plugin kicked in for all the new nodes and it looks like it is working correctly. The bulbs are shining and the Resistor value is taken into account. When I increase the resistance, the bulbs are barely glowing and the Energy Stats reacts:

Compare LED vs traditional bulb

To make a proper comparison I need two separate circuits and then I can check the Energy Stats node on each. Everything is customizable here, so you can easily adjust the electricity cost in your area and how many hours per day each bulb is on.

One small thing about the Energy Stats node. When I first built it, the cost was just a number with no currency unit, which on a diagram looks a bit weird. I went back and added a currency text field that defaults to $ but accepts anything: PLN, €, zł, whatever fits. It is a tiny change, but a nice example of how cheap adding a property is in this architecture. One new entry in the schema, one in the UI schema, one default value, and the readout picks it up.

Cost comparison

To compare costs properly I tuned the bulbs' nominal power so both produce the same brightness in lumens. To keep it realistic I aimed for 1000 lm, which is a moderate amount of light for a small room.

The focus now is on the Energy Stats nodes. About $20 per year for the traditional bulb running 5 hours a day, and only about $3 for the LED. That is roughly 7 times less cost for the same brightness. And that is one bulb.

Efficiency comparison

I already added the logic that makes a bulb dimmer when it runs below its rated voltage, so I can also check how efficient the LED is compared to the traditional bulb at the same power consumption.

Of course this is just a representation, real bulbs do not literally glow at these exact intensities, but Workflow Builder is flexible enough that I can adjust it for my needs. The point comes across: the LED produces much more visible light for the same wattage, while the Energy Stats confirms identical consumption.

Summary

Overall, a great experience

The architecture is generic enough to build well outside the workflow domain – this article is one example. An electrical circuit editor is about as far from a "workflow" as you can get, and I did not have to fight the SDK at any point. At the same time the genericity does not come at the cost of structure. There are clear patterns to follow (the 4-file node, the plugin decorators), so you are not dropped into a freeform mess. Without too much effort I was able to create proper node schemas to represent my needs.

The plugin API let me add domain-specific logic without touching the app core, which is a sign of good architecture. With more time I can imagine designing more nodes for other electrical devices and building a full home circuit that calculates how much power it draws.
Workflow Builder ships with a design system, including dark mode out of the box:

Idea for improvement

The default node template gives you one input on the left and one output on the right, which fits a workflow but not a symmetric domain like circuits, where a battery has + and -, a switch has two poles, and a resistor has two terminals. In this writeup I worked around it by placing nodes carefully on the canvas. The SDK has a proper way to do this: defineNodeTemplate lets you author a custom React component for a node type and declare whatever port topology you need, registered through the nodeTemplates prop on <WorkflowBuilder.Root />. A natural next step for this project would be a dedicated two-terminal template for the passive components so the wiring matches real schematics instead of relying on layout tricks.

FAQ

Is it possible to check the source code?

Yes, here are the links:

Can Workflow Builder be used for non-workflow domains?

Yes. The SDK is generic – nodes are described by JSON Schema and a UI schema, and plugins can react to any diagram change. The only constraint I hit was port topology (one input on the left, one output on the right), which is limiting for symmetric domains like electrical circuits.

How long does it take to add a new node type?

About 15-20 minutes per node once you know the pattern. Each node is 4 files (data schema, UI schema, default-properties, PaletteItem) plus 1 line in palette.ts to register it.

How does the plugin API work?

Plugins register decorators through registerComponentDecorator(slot, { content, name }). The slot tells the SDK where to mount your component – OptionalHooks runs every time nodes or edges change. From there you read the SDK store with useStore and write derived data back into your own Zustand store. The circuit-solver in this article fits in around 250 lines this way.

Which persistence strategies does Workflow Builder support?

3 strategies, picked via the integration prop on <WorkflowBuilder.Root />: localStorage (default, ~5 MB cap), REST API (you supply a GET and a POST endpoint), and props callback (you pass onDataSave and handle everything yourself).

Can Synergy Codes build a domain-specific editor like this?

Yes. Synergy Codes specializes in diagramming interfaces, workflow editors, and visualization tools, and has delivered 170+ custom editors for clients including Siemens, BMW, and Canon. Workflow Builder, ngDiagram, and Overflow are the open-source products we use as starting points – see synergycodes.com for case studies.

DEV Community: Workflow Builder

Parameters change everything: passing data between workflow nodes

A node is a function

Where do the arguments come from

Types, because data has a shape

A node can only see what runs before it

Simple when it works, loud when it fails

Because in Workflow Builder, everything is data

From React Flow to Workflow Builder: what you keep, and what you gain

Can you still do everything you did in React Flow?

What you gain on top

When does moving from React Flow to Workflow Builder make sense?

How we turned our workflow editor into a real SDK

In short

From editor to SDK: what adoption actually takes

What makes something an SDK, not just a library

No forking, just install it

Extend it without touching internals

Run it on any engine

We proved it by building on it: AI Studio

How to try it

FAQ

What is Workflow Builder?

Can I swap the execution engine?

Closing

I built a React circuit editor in a day with Workflow Builder

In short

Background

Reading the docs first

Genericity is the keyword

Building custom nodes

Embedding it as a React component

Different built-in ways of data storing

Let's build something

Tinker with the code

How I did it: the Battery example

Build the schema

The idea is crystallizing

Small adjustments

Let's implement it

It's alive!

Compare LED vs traditional bulb

Cost comparison

Efficiency comparison

Summary

Overall, a great experience

Idea for improvement

FAQ

Is it possible to check the source code?

Can Workflow Builder be used for non-workflow domains?

How long does it take to add a new node type?

How does the plugin API work?

Which persistence strategies does Workflow Builder support?

Can Synergy Codes build a domain-specific editor like this?

See also