DEV Community

Cover image for Embed a Full Workflow Editor in Your React App With One Component
ByteChef
ByteChef

Posted on Originally published at blog.bytechef.io AI-assisted

Embed a Full Workflow Editor in Your React App With One Component

Building a visual workflow editor is the most expensive part of any integration product. Canvas, node palette, property forms, data mapping, test runs, versioning. Teams spend years on it.

Here's the shortcut: create a workflow with one REST call, then render ByteChef's own editor inside your page with one React component. Your users get the full canvas. You write a dialog, a fetch and a page.

This is part 11 of the ByteChef Embedded series. All code comes from the open-source embedded sample app. The full original is on the ByteChef blog.

The 30-second version

<EmbeddedWorkflowBuilder
  baseUrl="https://bytechef.your-company.com"
  environment="PRODUCTION"
  jwtToken={jwtToken}
  workflowUuid={workflowUuid}
/>
Enter fullscreen mode Exit fullscreen mode
  • It's an iframe that loads workflow-builder.html#/embedded/builder/{uuid} from your ByteChef host.
  • The user's JWT goes in over postMessage, never in the URL.
  • Inside, the user gets the real editor: triggers, actions, flow controls, data pills, connections, Test and Publish.
  • You decide which components show up, whether users can create connections, and where the editor sits in your layout.

Where it fits

The sample app has five ways to create a workflow. All five end in the same place: a workflow in the connected user's own project. They differ in who does the authoring.

Sample app Automations page with the create menu open: New from Template, New from Embedded Workflow Builder, New from Prompt, New from Chat, New from Custom Workflow Builder

Option Who authors the steps Best when
New from Template You, ahead of time You know the common automations up front
New from Embedded Workflow Builder The user, on ByteChef's canvas Users who think in triggers and steps and need the full catalog
New from Prompt ByteChef's agent, from one sentence Short, clear requests
New from Chat ByteChef's agent, together with the user Fuzzy requests
New from Custom Workflow Builder The user, in forms you designed You want full control of the UX

The embedded builder is the most powerful option for the user and one of the cheapest for you.

The flow

  1. The user clicks New from Embedded Workflow Builder and enters a label and description.
  2. Your app calls POST /api/embedded/v1/automation/workflows. ByteChef stores a draft in the user's project and returns its UUID.
  3. Your app opens /automations/{uuid}, which renders EmbeddedWorkflowBuilder.
  4. The user builds, tests and publishes inside the editor.
  5. Back in your list, the user flips a toggle to enable it.

Steps 1 to 3 are yours. Step 4 is ByteChef's. Step 5 is yours again.

Step 1: Create the workflow

POST /api/embedded/v1/automation/workflows
Authorization: Bearer <connected user's JWT>
X-Environment: DEVELOPMENT
Content-Type: application/json

{"definition": "{\"label\": \"Sync new notes\", \"description\": \"\", \"triggers\": [], \"tasks\": []}"}
Enter fullscreen mode Exit fullscreen mode

The response is the new workflow's UUID as a JSON string. Note that definition is the workflow JSON as a string.

What ByteChef does with it:

  • Finds or creates the user's project. Every connected user gets one personal project per environment, named after their external user ID.
  • Adds the workflow as a draft. No published version yet, so it can't be enabled.
  • Fills in a blank definition if you send an empty string. The editor then shows a Manual trigger placeholder on a clean canvas.

The sample app's create call is a demo shortcut. It hardcodes a Productboard trigger, builds JSON by string interpolation (a label with a " in it breaks it), and throws the returned UUID away. Do this instead:

export async function createBlankWorkflow(label: string, description: string): Promise<string> {
  const response = await fetchWithAuth('/api/embedded/v1/automation/workflows', {
    method: 'POST',
    headers: {'Content-Type': 'application/json'},
    body: JSON.stringify({
      definition: JSON.stringify({description, label, tasks: [], triggers: []}),
    }),
  });

  if (!response.ok) {
    throw new Error(`Failed to create workflow: ${response.status}`);
  }

  return response.json();
}

// in your submit handler
const workflowUuid = await createBlankWorkflow(values.label, values.description);

router.push(`/automations/${workflowUuid}`);
Enter fullscreen mode Exit fullscreen mode

fetchWithAuth is a small wrapper that adds Authorization: Bearer <JWT> and X-Environment. Now the user lands on the canvas the moment they click Create.

Step 2: Embed the editor

The whole integration is one Next.js page:

import {EmbeddedWorkflowBuilder} from '@bytechef/embedded';
import {getToken} from '@/lib/api';
import {BYTECHEF_APP_BASE_URL, BYTECHEF_ENVIRONMENT} from '@/lib/config';

export default async function AutomationPage({params}: {params: {workflowUuid: string}}) {
  const {workflowUuid} = await params;

  const jwtToken = await getToken();

  return (
    <EmbeddedWorkflowBuilder
      baseUrl={BYTECHEF_APP_BASE_URL}
      connectionDialogAllowed={true}
      environment={BYTECHEF_ENVIRONMENT}
      jwtToken={jwtToken}
      workflowUuid={workflowUuid}
    />
  );
}
Enter fullscreen mode Exit fullscreen mode

It's a server component that fetches the JWT while rendering. The SDK marks the component 'use client', so you don't need a wrapper.

Props (@bytechef/embedded 0.4.0)

Prop Type Default What it does
jwtToken string required The connected user's JWT, sent to the iframe over postMessage
workflowUuid string required The workflow to open
baseUrl string https://app.bytechef.io Your ByteChef host. Self-hosted installs must set it
environment `'DEVELOPMENT' \ 'STAGING' \ 'PRODUCTION'`
includeComponents string[] all components Limits the palette, e.g. ['slack', 'googleMail']
connectionDialogAllowed boolean required Whether users can create connections inside the editor

That's the full list. No onSave, onPublish or onClose callbacks, and no theme prop. Everything the user does is saved by ByteChef inside the iframe.

Size the container yourself

The component renders a 100% x 100% iframe inside a wrapper with Tailwind classes (absolute inset-0 lg:pl-72). The SDK ships no CSS for those, so they only work if your stylesheet happens to define them. Give it a positioned parent with a real height:

<div style={{height: 'calc(100vh - 64px)', position: 'relative'}}>
  <EmbeddedWorkflowBuilder {...props} />
</div>
Enter fullscreen mode Exit fullscreen mode

How the iframe gets the user's identity

The iframe URL carries only the workflow UUID. The JWT travels through a two-message handshake:

  1. Iframe to parent: EMBED_READY. The editor reads the allowed parent origins from your ByteChef server and posts only to those.
  2. Parent to iframe: EMBED_INIT. The SDK ignores EMBED_READY unless it comes from the origin of baseUrl, then replies with {connectionDialogAllowed, environment, includeComponents, jwtToken}, addressed to that origin only.
  3. The editor initializes. It accepts EMBED_INIT only from its parent window and an allowed origin, stores the token and loads the workflow.

From then on every request the editor makes carries Authorization: Bearer <JWT> and X-Environment. The editor has no ByteChef login of its own. The token is the session, scoped to one connected user in one environment. Loading, saving, testing and publishing only ever touch that user's project.

Refresh the token without a reload

The SDK re-sends EMBED_INIT whenever its props change. Pass a new jwtToken and the editor swaps it in without reloading the iframe. The sample fetches a single token that lives for an hour, so an editor left open longer starts failing. The fix is a small client wrapper:

'use client';

import {EmbeddedWorkflowBuilder} from '@bytechef/embedded';
import {useEffect, useState} from 'react';

export default function WorkflowEditor({initialToken, workflowUuid}: WorkflowEditorPropsI) {
  const [jwtToken, setJwtToken] = useState(initialToken);

  useEffect(() => {
    const interval = setInterval(async () => setJwtToken(await fetchFreshToken()), 5 * 60 * 1000);

    return () => clearInterval(interval);
  }, []);

  return (
    <div style={{height: 'calc(100vh - 64px)', position: 'relative'}}>
      <EmbeddedWorkflowBuilder
        baseUrl={BYTECHEF_APP_BASE_URL}
        environment={BYTECHEF_ENVIRONMENT}
        jwtToken={jwtToken}
        workflowUuid={workflowUuid}
      />
    </div>
  );
}
Enter fullscreen mode Exit fullscreen mode

fetchFreshToken calls your own token endpoint. Refresh well before the token's exp.

Lock down who can frame it

BYTECHEF_EMBEDDED_ALLOWED_PARENT_ORIGINS=https://app.example.com,https://admin.example.com
Enter fullscreen mode Exit fullscreen mode

Exact origins with scheme and port, no paths, no wildcards. ByteChef then sends Content-Security-Policy: frame-ancestors with those origins and accepts EMBED_INIT only from them. Leave it empty and any site can frame your editor.

If the editor is blank, check the console:

  • frame-ancestors violation: your app's origin isn't on the list.
  • Stuck on loading: the editor never got EMBED_INIT from an allowed origin. Check http vs https and the port.
  • Empty list plus Referrer-Policy: no-referrer: the editor can't announce itself. Set the list.

Match the environment to the token

ByteChef verifies the JWT against the signing key registered for the request's environment. A Development token used with environment="PRODUCTION" is rejected. The prop defaults to PRODUCTION, so set it explicitly.

What the user sees inside

The same canvas ByteChef's own users build with, scoped to one workflow:

ByteChef embedded workflow editor with a V1 DRAFT badge, Test and Publish buttons, and a canvas with a webhook trigger, a Slack step and a Gmail step

  • Header: workflow label with a V1 DRAFT badge, Saving... / Offline, Test, Publish, the output panel and a settings menu to rename the workflow.
  • No way out. No project sidebar, no workflow switcher, no navigation to the rest of ByteChef. Your app owns navigation. The AI Copilot and the workflow inputs panel are turned off.
  • Autosave. There's no Save button. The DRAFT badge tells the user they're editing the draft, not what's running.

Narrow the palette

By default the palette lists every component on your ByteChef instance, not only the integrations you configured. Narrow it:

<EmbeddedWorkflowBuilder
  // ...
  includeComponents={['googleMail', 'slack', 'hubspot']}
/>
Enter fullscreen mode Exit fullscreen mode

Flow controls stay available either way. Treat includeComponents as product design, not as a permission: it comes from your page, and the server doesn't check saved workflows against it.

Control connection creation in the token

On a step that needs an account, the user picks from their own connections and any a tenant admin shared. No other user's connections ever appear. If there are none, a Create Connection button opens ByteChef's connection form inside the iframe.

connectionDialogAllowed={false} hides that button. But a page is easy to change. For a rule the server enforces, put it in the JWT:

const token = jwt.sign(
  {
    connectionDialogAllowed: false,
    sub: externalUserId,
  },
  privateKey,
  {algorithm: 'RS256', expiresIn: '10m', keyid: signingKeyId}
);
Enter fullscreen mode Exit fullscreen mode
  • Claim missing or true: users can create connections.
  • Claim false: existing connections only, and the API answers create attempts with 403.
  • Claim not a boolean: the token is invalid.

A false prop hides creation even when the token allows it. A true prop can't override a token that says false. The claim is per token, so mint separate tokens for surfaces with different rules.

Test and publish

Test runs the current draft with the connections chosen on each step. These are real calls: a test that sends a Slack message sends a Slack message from the user's account. Say so in your onboarding.

Publish freezes the current definition as the next version (V1, V2 and so on) and deploys it with the chosen connections. The user keeps editing a new draft, and nothing reaches the running workflow until they publish again.

Enabling happens in your app

The editor has no on/off switch. That's deliberate: where an automation is turned on and what you show next to it are product decisions.

// Turn it on (DELETE to turn it off)
const response = await fetchWithAuth(`/api/embedded/v1/automation/workflows/${workflowUuid}/enable`, {
  method: 'POST',
});
Enter fullscreen mode Exit fullscreen mode

If the published version has validation errors, you get 409 with a body like {"invalidWorkflowErrorCount": 2}. Show the count and link back to the editor. A workflow that was never published can't be enabled.

Theming

There's no theme prop, and your CSS can't reach inside the iframe. You control placement and the catalog. You don't control colors, fonts or copy in the standalone editor. If you need it in your brand colors, the Automation Hub (part 12) applies a theme to the same editor.

Server-to-server variant

Want to prepare a workflow before the user arrives, like a starter automation during onboarding? Call POST /api/embedded/v1/{externalUserId}/automation/workflows with your environment's API key instead of the user's JWT. Same body, same UUID back. Then open it with EmbeddedWorkflowBuilder and the user's token.

Production checklist

  • Create a real blank workflow. Drop the hardcoded trigger.
  • Build the definition with JSON.stringify. Never interpolate user input into JSON.
  • Navigate to the editor with the returned UUID.
  • Wrap the component in a positioned container with an explicit height.
  • Refresh the token while the editor is open.
  • Set BYTECHEF_EMBEDDED_ALLOWED_PARENT_ORIGINS.
  • Set environment explicitly so it matches the token.
  • Pass includeComponents.
  • Decide on connection creation in the token claim, and set the prop to match.
  • Handle the 409 on enable and keep the toggle disabled until the workflow has a version.
  • Tell users that test runs are real.

Who owns what

You own: the entry point and create dialog, the page the editor lives in, token minting and refresh, the environment, the palette, connection rules, the workflow list, enabling, and the allowed parent origins.

ByteChef owns: the editor (canvas, palette, properties, data pills, flow controls, validation), the connection picker and form, test runs, autosave, versioning, publishing, the per-user project and the engine that runs every published workflow.

Your code is a dialog, one fetch and one component. The most expensive piece of any iPaaS, the visual editor, becomes a dependency you keep current with npm update.


Try it: clone the embedded sample app, open Automations → New from Embedded Workflow Builder, give the workflow a label and click Create. Click its title, replace the trigger, add a step, hit Test, then Publish.

ByteChef is an open-source (Apache 2.0) workflow automation and AI agent platform. If this was useful, a ⭐ on GitHub helps a lot.

Next up: the Automation Hub, one embedded component that renders a complete, themed end-user automation page with your templates, the user's connections and this same builder inside it.

Top comments (0)