Chatbot Flow Builder Starter Kit

A modern, extensible starter kit for building chatbot flow editors using React, React Flow, Zustand, and TypeScript.

Table of Contents

• Live Demo
• Features
  • Nodes
  • Sidebars
  • Flow
• Tech Stack
• Getting Started
• Extending the Starter Kit
  • Add a New Node Type
  • Add-or-Register-Property-Panels
  • Customize Flow Logic
  • Add Sidebar Panels or Features
  • General Tips
• Contributing
• Author

Live Demo

See the live demo

Features

Nodes

• Start Node: Entry point of the flow.
• Message Node: Displays a message to the user.
• Conditional Path Node: Branches the flow based on conditions (showcases dynamic handles).
• End Node: Terminates the flow.

Sidebars

• Node Sidebar: List of available nodes to add.
• Node Properties Sidebar: Edit properties of the selected node.

Flow

• Validation: Ensures the flow has a start and end node.
• Auto Adjust: Automatically arranges nodes to avoid overlap (does not adjust edges).

Tech Stack

• React
• React Flow
• Zustand
• TypeScript
• UnoCSS

Getting Started

1. Install dependencies:

   pnpm install
   

2. Start the development server:

   pnpm dev
   

3. Open http://localhost:5173 in your browser.

Extending the Starter Kit

This starter kit is designed to be easily extensible. Here are some common ways to extend the codebase:

Add a New Node Type

Here's how you can add a new node, using the Start Node as a reference:

1. Define the node type:
   • Add a new entry in src/modules/nodes/types.ts:

     export enum BuilderNode {
       START = 'start',
       // ...other nodes...
       CUSTOM = 'custom',
     }
     

2. Create the node component and metadata:
   • Create a new folder for your node in src/modules/nodes/nodes/, e.g. custom-node/.
   • Add your component as custom.node.tsx inside that folder. For example:

     // src/modules/nodes/nodes/custom-node/custom.node.tsx
     import type { Node, NodeProps } from '@xyflow/react'
     import type { BaseNodeData, RegisterNodeMetadata } from '~/modules/nodes/types'
     import { Position } from '@xyflow/react'
     import { nanoid } from 'nanoid'
     import { memo, useMemo, useState } from 'react'
     import { cn } from '~@/utils/cn'
     import CustomHandle from '~/modules/flow-builder/components/handles/custom-handle'
     import { BuilderNode } from '~/modules/nodes/types'
     import { getNodeDetail } from '~/modules/nodes/utils'
     
     export interface CustomNodeData extends BaseNodeData {
       label?: string;
     }
     
     const NODE_TYPE = BuilderNode.CUSTOM
     
     type CustomNodeProps = NodeProps<Node<CustomNodeData, typeof NODE_TYPE>>
     
     export function CustomNode({ data, selected, isConnectable }: CustomNodeProps) {
       const meta = useMemo(() => getNodeDetail(NODE_TYPE), [])
       const [sourceHandleId] = useState<string>(nanoid())
       return (
         <>
           <div
             data-selected={selected}
             className="flex items-center border border-dark-100 rounded-full bg-dark-300 px-4 py-2 shadow-sm transition data-[selected=true]:(border-teal-600 ring-1 ring-teal-600/50)"
           >
             <div className={cn(meta.icon, 'size-4.5 shrink-0 mr-2 scale-130')} />
             <span className="mr-1">
               {data.label || meta.title}
             </span>
           </div>
           <CustomHandle
             type="source"
             id={sourceHandleId}
             position={Position.Right}
             isConnectable={isConnectable}
           />
         </>
       )
     }
     
     // eslint-disable-next-line react-refresh/only-export-components
     export const metadata: RegisterNodeMetadata<CustomNodeData> = {
       type: NODE_TYPE,
       node: memo(CustomNode),
       detail: {
         icon: 'i-custom:icon',
         title: 'Custom',
         description: 'A custom node example',
       },
       connection: {
         inputs: 0,
         outputs: 1,
       },
       available: true,
       defaultData: {
         label: 'Custom',
         deletable: true,
       },
     }
     

Folder Structure Example:

src/modules/nodes/nodes/
  start-node/
    start.node.tsx
  text-message-node/
    text-message.node.tsx
  conditional-path-node/
    conditional-path.node.tsx

Add or Register Property Panels

To add a custom property panel for your node:

1. Create the property panel component:

   • Add a new component in src/modules/sidebar/panels/node-properties/property-panels/, e.g. custom-node-property-panel.tsx.
   • The component should accept id, type, data, and updateData props. See text-message-property-panel.tsx for a reference implementation.

2. Link the property panel to your node:

   • In your node's metadata (e.g., in custom.node.tsx), set the propertyPanel field to your panel component:

     import CustomNodePropertyPanel from '~/modules/sidebar/panels/node-properties/property-panels/custom-node-property-panel'
     // ...
     export const metadata = {
       // ...existing metadata fields...
       propertyPanel: CustomNodePropertyPanel,
     }
     

3. Registration is automatic:

   • The codebase auto-registers property panels by mapping the propertyPanel field from each node's metadata into NODE_PROPERTY_PANEL_COMPONENTS.
   • When a node is selected, the sidebar will automatically render the correct property panel if it is linked in the node's metadata.

Reference:

• See src/modules/sidebar/panels/node-properties/constants/property-panels.ts for how property panels are mapped.
• See src/modules/nodes/nodes/text-message-node/text-message.node.tsx for an example of linking a property panel to a node.

Customize Flow Logic

• Modify hooks in src/modules/flow-builder/hooks/ to change validation, auto-adjust, or connection logic.
• Update UI components in src/modules/flow-builder/components/ to change controls, menus, or edge behavior.

Add Sidebar Panels or Features

• Add new panels in src/modules/sidebar/panels/ and register them in the sidebar.

General Tips

• The codebase is modular and uses TypeScript for type safety.
• Use the existing node and sidebar implementations as references for your extensions.

Contributing

Contributions are welcome! Please open issues or submit pull requests for improvements and new features.

Author

Denish Sharma

• Email: [email protected]
• LinkedIn: denish-sharma
• GitHub: denish-sharma