How we turned our workflow editor into a real SDK

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.

推荐订阅源

DEV Community