Provider and Renderer

🎯

Goal: Learn how to quickly set up a workflow.

There are two crucial components required for set up:

WorkflowProvider — Sets up all the necessary infrastructure for the part of the application that requires workflow capabilities.
WorkflowRenderer — Acts as the stage conductor, rendering the right UI nodes.

Look at the UI/UX section for a deep dive into WorkflowRenderer’s capabilities.

Quick Use Code

app/page.tsx


'use client'
import { clientWorkflowConfig } from '@/graphs/client/config';
import { WorkflowProvider, WorkflowRenderer } from '@cascaide-ts/react';
 
export default function HomePage() {
  return (
    <WorkflowProvider
      initialNodeId="chat_init"
      initialNodeName="chat"
      config={clientWorkflowConfig}
      actionRelayEndpoint='/api/workflow/action'
      hydrationEndpoint='/api/workflow/hydrate'
      persistenceEndpoint='/api/workflow/persistence'
    >
      <WorkflowRenderer />
    </WorkflowProvider>
  );
}

WorkflowProvider

WorkflowProvider is the required root component that sets up the Cascaide environment for your application.

Purpose

🚀 Initialise State — Creates and configures the workflow state.
⚙️ Load Configuration — Makes the client workflow config available to the workflow.
▶️ Initiate Workflow — Kicks off the first node.

Props

Prop Name	Type	Required	Description
`children`	`React.ReactNode`	Yes	The components rendered within the provider that need access to the workflow state and context.
`initialNodeId`	`string`	Yes	A unique ID assigned to the initial active node instance in the workflow. User defined for the first node.
`initialNodeName`	`string`	Yes	The defined name of the starting node type (must match a key in the `workflowGraph`).
`initialContext`	`WorkflowContext`	No	An object containing the initial data or context to be loaded into the state. Defaults to `{}`.
`config`	`WorkflowConfig`	Yes	The configuration object containing the `workflowGraph` (node definitions) and `uiComponentRegistry` (UI components).

WorkflowRenderer

The WorkflowRenderer is responsible for observing the workflow state and rendering the appropriate UI components defined in the configuration.

Purpose

Subscribes to the workflow state to get the list of activeNodes.
Dynamically renders the corresponding React component for each active UI node.

Rendering Logic

The WorkflowRenderer will render a div containing all active isUINode: true components. If there are no active UI nodes, it returns null.

💡

WorkflowRenderer is more than just a display screen. It turns the entire workflow into a Dynamic User Interface. Because it renders components based on the live activeNodes list, it enables several novel UX patterns that are difficult with traditional routing or static chat interfaces:

🤖 Background agents as overlays
🌀 Dynamic portalling
🛠️ UI tools
⏳ Asynchronous task completion UI
📡 Multi-agent to user communication via toasts
⚡ Zero-latency component swap
🧠 Smart components