Workflow Node Setup

intent

this skill tunes React Flow workflow nodes without breaking React Flow semantics or the existing canvas interaction model. use it when building custom node components, adjusting handle positioning and ids, styling edges, resizing node dimensions, configuring drag behavior, or rendering markdown content inside nodes. apply this skill before deploying node changes to production or when debugging edge connection failures, handle misalignment, or unexpected canvas behavior.

inputs

• react flow node component source code and the node definition in the flow model
• the flow model json or typescript definitions (where node dimensions, positions, edge source/target handles, and edge styles live)
• access to the canvas component that wraps react flow
• shared project primitives: WorkflowHandle, NodeResizer, edge style constants if they exist
• browser dev tools and a local dev server running the workflow canvas
• optional: backend markdown content or mock markdown strings for output nodes
• optional: vercel ai sdk docs (current version) if streaming integration is planned

procedure

1. inspect the current node component file, the shared helpers directory, and the flow model before editing anything. note which handles already exist on the node, which edges reference the node, and which style constants are shared across the project.

2. if the node renders input/output connections, prefer the shared WorkflowHandle component over custom Handle styling unless the product explicitly requires a different visual system.

3. for multi-channel nodes, render multiple handles with distinct ids and place each handle at a meaningful vertical position aligned to content rows:

   <WorkflowHandle
     id="source-preview-test-case"
     type="source"
     position="right"
     style={{ top: 85 }}
   />
   <WorkflowHandle
     id="source-style"
     type="source"
     position="right"
     style={{ top: 108 }}
   />
   

4. sync react flow ids: every edge sourceHandle and targetHandle in the flow model must match an actual rendered Handle id on the target node. if an id mismatch exists, react flow logs error #008 and the edge will not render.

5. apply visual changes in the narrowest place:

   • node content and layout belong in the node component file.
   • node dimensions, positions, edge handle ids, and edge visual style belong in the flow model.
   • canvas pan/zoom behavior and global canvas interaction belong in the canvas component.

6. if the node has resizable dimensions, use NodeResizer inside the component and gate it by the selected prop so it only appears when the node is selected:

   <NodeResizer
     isVisible={selected}
     minHeight={MIN_HEIGHT}
     minWidth={MIN_WIDTH}
     handleStyle={HANDLE_STYLE}
     lineStyle={LINE_STYLE}
   />
   

7. if the node must retain its size after reload, store controlled width and height in the flow model; use initialWidth and initialHeight only as fallback defaults. do not store resizer state in local component state if persistence is required.

8. for edges, use explicit sourceHandle and targetHandle in the edge definition. if the design calls for muted dashed connections without arrows, apply the standard edge style and set markerEnd to undefined:

   const WORKFLOW_EDGE_STYLE = {
     stroke: "rgba(145, 147, 151, 0.72)",
     strokeDasharray: "9 9",
     strokeWidth: 2,
   };
   

9. if only one node needs a different edge style, create a separate edge style constant instead of changing the global edge style.

10. for content-heavy nodes, enable drag-by-header only: add dragHandle: ".node-specific__drag-handle" to the node definition and apply that class to the header element. add nodrag class to all buttons and clickable controls so they do not trigger node movement.

11. for internal scroll containers, add nowheel class so canvas pan/zoom does not steal mouse wheel events. for nested horizontal table scroll, keep the table scroller local and handle deltaX or Shift+wheel only within that table component.

12. if the node renders markdown output from the backend, treat backend text as markdown, not html. use react-markdown with remark-gfm and skipHtml: true:

    function StyleOutput({ markdown }: { markdown: string }) {
      return (
        <ReactMarkdown remarkPlugins={[remarkGfm]} skipHtml>
          {markdown}
        </ReactMarkdown>
      );
    }
    

13. keep markdown renderer component mappings local to the node until reused by more than one node. tables should have their own horizontal overflow wrapper; avoid one large horizontal scroller around the whole markdown body unless the entire content is meant to scroll sideways.

14. do not render backend-provided html in workflow nodes. if the backend sends markdown containing html, keep skipHtml enabled.

15. keep node output components ready to receive a plain markdown string prop, even when the current source is a mock constant. do not add vercel ai sdk dependencies until there is an implemented backend endpoint or the task explicitly asks for streaming integration.

16. if streaming integration is planned, prefer useChat from @ai-sdk/react and concatenate streamed text parts into the same markdown string consumed by the node output renderer. keep the renderer independent from transport details and place endpoint calls and message state outside low-level visual node sections.

17. when implementing vercel ai sdk integration, verify against current official vercel ai sdk docs before editing because api names and transports change frequently.

18. run the smallest relevant checks (lint/type) before finishing. for behavior or layout changes that touch react flow wiring, run a full build.

19. use a browser against a dev server when available and run the following verification checks:

    • react flow console has no missing handle errors.
    • all expected handles exist in the dom with the ids used by edges.
    • edges attach to the intended handles.
    • NodeResizer handles remain clickable.
    • header drag works if dragHandle is configured.
    • buttons do not drag nodes.
    • vertical and horizontal scroll areas work without moving the canvas.

20. commit changes with a message describing which node(s) were modified, which handles or edges were added/removed, and which visual or interaction changes were made.

decision points

• if the node needs standard handle styling, use the shared WorkflowHandle component; else if the product requires a custom visual system, create a custom handle component at the project level and document why the standard component is insufficient.

• if the node has multiple output channels, render multiple source handles with distinct ids aligned to content rows; else use a single target-left handle for incoming edges.

• if the node must be resizable, use NodeResizer with selected gating and store width/height in the flow model; else keep the node at a fixed size and omit NodeResizer.

• if an edge definition references a missing handle id, add the missing handle to the node component and sync its id to the edge definition; else if the handle exists and the id matches but the edge still does not render, check for react flow error #008 in the console and trace the source/target handle path in the dom.

• if the node renders backend markdown, use react-markdown with skipHtml: true and keep the renderer independent from transport; else if the node receives html from the backend, reject it and request markdown from the backend.

• if streaming from vercel ai sdk is implemented, concatenate streamed text into a single markdown string and pass it to the renderer; else if streaming is not yet implemented, keep the output component ready to accept a markdown string prop from a future endpoint call.

• if the node contains a horizontal scroll container, apply nowheel class and handle horizontal scroll locally; else if the node has no internal scrolling, add nowheel to the root only if the canvas uses wheel events for zoom.

• if resizer placement conflicts with clipped content, move NodeResizer to a direct child of the root node or remove the clip wrapper around the resizer; else if the resizer is already at the root level, verify that its handles remain clickable during testing.

output contract

• the node component file exports a react component that accepts selected, data, and standard react flow node props.
• the flow model contains node entries with id, position, data, type, and optional width/height keys.
• the flow model contains edge entries with id, source, target, sourceHandle, targetHandle, and optional style and markerEnd keys.
• all sourceHandle and targetHandle ids in edges match id props on actual rendered Handle or WorkflowHandle components in the target node.
• if markdown output is used, the node component accepts a markdown: string prop and renders it via ReactMarkdown with remark-gfm and skipHtml.
• the node component applies nodrag class to buttons and clickable controls.
• the node component applies nowheel class to internal scroll containers.
• if NodeResizer is used, it is gated by the selected prop and stores size in the flow model, not in component state.
• if dragHandle is configured, the node definition includes dragHandle: ".node-specific__drag-handle" and that class is applied to the header.
• no console errors or warnings from react flow appear after node configuration changes.

outcome signal

• browser dev tools show no react flow error #008 or missing handle warnings in the console.
• the node renders on the canvas with all expected handles visible and positioned at the correct vertical alignment.
• edges connect to the node and terminate at the correct handle ids without visual misalignment.
• if the node is resizable, the NodeResizer handles appear when the node is selected and disappear when deselected; resizing changes the node dimensions immediately and persists after reload.
• if drag behavior is configured, clicking and dragging the header moves the node without moving it when clicking buttons or other controls.
• if the node contains internal scroll areas, scrolling inside those areas does not pan or zoom the canvas.
• if the node renders markdown, the markdown renders correctly with gfm tables and links, html is stripped, and code blocks are syntax-highlighted.
• if streaming is implemented, the markdown output updates in real time as chunks arrive from the backend without blocking canvas interaction.
• the node layout remains stable and handles do not clip or hide when content changes or the canvas is panned/zoomed.

original author: clawhub (source)