DOCSEARCHbyAlgolia
Submit Docs

Workflow Builder SDK

repository·main·Indexed 42 days ago

https://github.com/synergycodes/workflowbuilder

An Apache 2.0 React SDK for embedding visual, drag-and-drop workflow editors into digital products. It features a plugin-first, back-end agnostic architecture with a reference execution engine powered by Temporal. The SDK includes a reference AI Studio application and a demo showcase for implementing visual workflows with React Flow.

Tokens
115.2K
Snippets
283
Records
530
Agent score
56%

What's inside Workflow Builder

  1. Overview of Diagram Component building blocks

    main

    Workflow Builder provides several specialized components for constructing the canvas UI:

    • NodePanel: A container for nodes that provides structured slots for Root, Header, Content, and Handles.
    • Edge: Handles the rendering of edge labels, including support for hover and selected states.
    • NodeAsPortWrapper: A utility component that transforms an entire node into a connection port.
    • NodeDescription: A specialized text block designed to reside inside a node.
    • NodeIcon: A specialized icon block designed to reside inside a node.

  2. What is Workflow Builder?

    main

    Workflow Builder is a React SDK designed for building and embedding visual workflow editors into your applications. It provides a production-ready frontend editor layer, including a canvas, nodes, edges, layout tools, and configuration panels, allowing you to implement drag-and-drop workflow UIs without building the UX from scratch.

    Core Responsibility: Workflow Builder focuses exclusively on the frontend editor layer. It outputs workflow definitions as JSON, which your backend then consumes and executes. Execution, orchestration, and business logic remain under your control.

    Key Capabilities:

    • Visual canvas with drag-and-drop interactions.
    • Node library featuring triggers, actions, conditions, branching, and delays.
    • Dynamic properties panel driven by JSON Schema.
    • Auto-save functionality (to local storage or external APIs).
    • Read-only mode for viewing workflows.
    • Optional Flow Runner plugin for in-editor graph traversal and step-by-step execution (Enterprise feature).
    • Advanced canvas features like zoom, auto-layout, smart edge routing, and edge reshaping.

  3. Overview of Workflow Builder plugins

    main

    Workflow Builder uses a plugin system to extend core functionality without increasing the base bundle size. Plugins are optional and can be enabled via a single import. Only the plugins you explicitly use are included in your application bundle.

    Available Built-in Plugins

    PluginFunctionality
    Undo / RedoProvides session history to step backwards and forwards through edits.
    Copy & PasteEnables cut, copy, and paste functionality for nodes and edges using keyboard shortcuts.
    Avoid Nodes & EdgesUses WASM and a Worker to provide automatic orthogonal edge routing around nodes.
    Auto LayoutProvides one-click node arrangement using the ELK layout engine.
    Reshapable EdgesAdds drag handles to edges for manual adjustment of connection paths.
    WidgetsAllows attaching rich content blocks directly onto node cards.
    Flow RunnerA reference implementation for parsing and executing workflow diagrams.
    ValidationProvides diagram-based validation for JSON forms.
    Download PDFAllows exporting the current diagram as a PDF file.

    Note: Some plugins may require an Enterprise license. Contact the Workflow Builder team for licensing details.

  4. Overview of built-in Workflow Builder nodes

    main

    Workflow Builder provides several production-ready node types designed to cover common workflow patterns. Each node includes a full configuration UI, built-in validation, and JSON serialization, making them ready for immediate use in your application.

    Available node types include:

    • Trigger: Initiates a workflow based on an event, schedule, or specific condition.
    • Action: Performs tasks such as executing scripts, calling APIs, or sending emails.
    • Conditional: Implements branching logic by splitting the workflow into two paths based on a true/false condition.
    • Decision: Routes the workflow execution to one of several named branches.
    • Delay: Pauses workflow execution for a fixed, dynamic, or conditional duration.
    • Notification: Dispatches alerts via email, SMS, push notifications, webhooks, or Slack.
    • AI Agent: Delegates workflow steps to an AI model equipped with tool access.

  5. Understand the AI Studio application

    main

    AI Studio is a reference frontend for the Workflow Builder AI Studio product. Unlike the minimal apps/demo showcase, AI Studio is a complete, runnable AI workflow product built on top of the @workflowbuilder/sdk.

    Key characteristics include:

    • Backend Dependency: Requires a backend (Hono + Temporal) to function, unlike the pure SPA apps/demo.
    • Node Types: Uses AI Studio-specific node types: ai-studio/trigger, ai-studio/ai-agent, and ai-studio/decision.
    • UI Features: Provides a live execution UI including Play/Stop controls, a log panel, per-node status markers, edge highlighting, and a node-detail overlay.
    • Architecture: It consumes the SDK like an external user would, composing the app-shell UI directly via JSX. It uses the plugin API primarily for per-node markers and translations rather than decorating the editor.

  6. Understand the Workflow Builder documentation structure

    main

    The documentation is organized by user audience and journey to help you find relevant information quickly:

    • Overview: High-level features and architecture for evaluators.
    • Get Started: Onboarding for first-time integrators (Installation, Persistence, Theming, Side effects).
    • Guides: Recipe-style how-tos for the building team (e.g., adding custom nodes, configuring the editor).
    • Plugins: Documentation for per-plugin development.
    • Built-in Nodes: Demos and usage for existing nodes.
    • API Reference: Auto-generated technical catalogue of all types and methods.

    Note on Schema Authoring: If you are building custom nodes, the documentation for Data schema (JSON Schema) and UISchema (visual layer) is located within the Guides section to keep them adjacent to the 'Add a custom node' recipe.

  7. Explore the @workflowbuilder/sdk API Reference

    main

    The @workflowbuilder/sdk provides a comprehensive set of tools for building and customizing workflow editors. The API is organized into several functional categories to help you find the right tools for your integration:

    • Core: Contains the main entry points like the WorkflowBuilder compound component, WorkflowBuilderRoot, and their associated props and plugin types.
    • Plugins: Defines the three register* extension points used to extend the editor's functionality.
    • Components: Provides UI building blocks (edge/node primitives) and *Props types for typing decorators on built-in slots (e.g., DiagramContainerProps, PropertiesBarProps).
    • Hooks: React hooks for interacting with the editor state, such as useStore selectors, useFitView, and change-trackers.
    • Store: One-shot accessors for direct state manipulation, including getStoreNodes, setStoreNodes, selection helpers, and openModal.
    • Listeners: Event hooks for reacting to diagram changes, such as addNodeChangedListener and addNodeDragStartListener.
    • Forms: Helpers for form authoring (getScope, DynamicCondition) and re-exported JsonForms primitives for custom renderers.
    • Integration: Types for defining persistence strategies and save-callback shapes.
    • Types: Core domain types like NodeData, NodeSchema, UISchema, and PaletteItem.
    • Utilities: Reusable schema fragments and small helpers like getHandleId or DeepPartial.
    • Constants: Edge-routing constants and reserved keys.
    • i18n: TranslationKey for type-safe translation calls.
    • Icons: The Icon component and WBIcon name union.

  8. Explore Workflow Builder typical use cases

    main

    Workflow Builder is designed as a foundation for various workflow-driven products. Common use cases include:

    • Embedding workflow editors into B2B SaaS products.
    • Building visual rule engines and configuration tools.
    • Designing AI agent and automation workflow platforms.
    • Serving as a foundation for workflow-driven products and standalone apps.

  10. Explore the @workflow-builder/demo application structure

    main

    The @workflow-builder/demo application serves as a reference implementation. Understanding its directory structure helps in locating core logic, data definitions, and plugin implementations:

    • data/nodes: Contains node definitions used by the application and the palette.
    • data/template: Contains pre-made, ready-to-use workflow templates.
    • features: Houses the core functionalities of Workflow Builder.
      • features/diagram: Contains the logic for displaying the diagram via ReactFlow.
      • features/json-form: Manages rendering and validation for the properties sidebars. This is the location for adding new UI controls.
      • features/plugins-core: Implements the core logic for optional plugins (handles the orchestration, not the plugin implementations themselves).
    • plugins: Contains optional features that can be removed without breaking the application, thanks to the use of adapters and stub imports.
    • store: Defines the main Zustand store used by the application.

  11. Use general-purpose UI components from @workflowbuilder/ui

    main

    The @workflowbuilder/ui package provides a collection of general-purpose interface components designed for building workflow-related interfaces. These components include common patterns such as inputs, buttons, navigation elements, and feedback indicators. Each component is available with various props and can be customized using CSS variables.

    Available components include:

    • Layout & Structure: Accordion, Collapsible, Separator, Modal
    • Form Controls: Button, Checkbox, DatePicker, Input, Radio, Select, SegmentPicker, Switch, TextArea
    • Navigation: Menu, NavButton
    • Feedback & Status: Avatar, Snackbar, Status, Tooltip

  12. What is Workflow Builder and how does it differ from SaaS automation tools?

    main

    Workflow Builder is a white-label frontend SDK designed to be embedded into your own product. Unlike SaaS platforms like n8n, Make, or Zapier—which provide hosted execution and tightly coupled frontends—Workflow Builder is execution-agnostic. It provides the visual drag-and-drop editor, node library, and properties panel, but it does not include a database or a runtime.

    It serializes workflows into a JSON format that you can then consume with your own custom execution engine, backend, and business logic.