FlowGram.AI - Demo Free Layout

Best-practice demo for free layout

Installation

npx @flowgram.ai/create-app@latest free-layout

Project Overview

Core Tech Stack

Frontend framework: React 18 + TypeScript
Build tool: Rsbuild (a modern build tool based on Rspack)
Styling: Less + Styled Components + CSS Variables
UI library: Semi Design (@douyinfe/semi-ui)
State management: Flowgram’s in-house editor framework
Dependency injection: Inversify

Core Dependencies

@flowgram.ai/free-layout-editor: Core dependency for the free layout editor
@flowgram.ai/free-snap-plugin: Auto-alignment and guide-lines plugin
@flowgram.ai/free-lines-plugin: Connection line rendering plugin
@flowgram.ai/free-node-panel-plugin: Node add-panel rendering plugin
@flowgram.ai/minimap-plugin: Minimap plugin
@flowgram.ai/free-container-plugin: Sub-canvas plugin
@flowgram.ai/free-group-plugin: Grouping plugin
@flowgram.ai/form-materials: Form materials
@flowgram.ai/runtime-interface: Runtime interfaces
@flowgram.ai/runtime-js: JS runtime module
@flowgram.ai/panel-manager-plugin: Sidebar panel management

Code Guide

Directory Structure

src/
├── app.tsx # Application entry file
├── editor.tsx # Main editor component
├── initial-data.ts # Initial data configuration
├── assets/ # Static assets
├── components/ # Component library
│ ├── index.ts
│ ├── add-node/ # Add-node component
│ ├── base-node/ # Base node components
│ ├── comment/ # Comment components
│ ├── group/ # Group components
│ ├── line-add-button/ # Connection add button
│ ├── node-menu/ # Node menu
│ ├── node-panel/ # Node add panel
│ ├── selector-box-popover/ # Selection box popover
│ ├── sidebar/ # Sidebar
│ ├── testrun/ # Test-run module
│ │ ├── hooks/ # Test-run hooks
│ │ ├── node-status-bar/ # Node status bar
│ │ ├── testrun-button/ # Test-run button
│ │ ├── testrun-form/ # Test-run form
│ │ ├── testrun-json-input/ # JSON input component
│ │ └── testrun-panel/ # Test-run panel
│ └── tools/ # Utility components
├── context/ # React Context
│ ├── node-render-context.ts # Current rendering node context
│ ├── sidebar-context # Sidebar context
├── form-components/ # Form component library
│ ├── form-content/ # Form content
│ ├── form-header/ # Form header
│ ├── form-inputs/ # Form inputs
│ └── form-item/ # Form item
│ └── feedback.tsx # Validation error rendering
├── hooks/
│ ├── index.ts
│ ├── use-editor-props.tsx # Editor props hook
│ ├── use-is-sidebar.ts # Sidebar state hook
│ ├── use-node-render-context.ts # Node render context hook
│ └── use-port-click.ts # Port click hook
├── nodes/ # Node definitions
│ ├── index.ts
│ ├── constants.ts # Node constants
│ ├── default-form-meta.ts # Default form metadata
│ ├── block-end/ # Block end node
│ ├── block-start/ # Block start node
│ ├── break/ # Break node
│ ├── code/ # Code node
│ ├── comment/ # Comment node
│ ├── condition/ # Condition node
│ ├── continue/ # Continue node
│ ├── end/ # End node
│ ├── group/ # Group node
│ ├── http/ # HTTP node
│ ├── llm/ # LLM node
│ ├── loop/ # Loop node
│ ├── start/ # Start node
│ └── variable/ # Variable node
├── plugins/ # Plugin system
│ ├── index.ts
│ ├── context-menu-plugin/ # Right-click context menu plugin
│ ├── runtime-plugin/ # Runtime plugin
│ │ ├── client/ # Client
│ │ │ ├── browser-client/ # Browser client
│ │ │ └── server-client/ # Server client
│ │ └── runtime-service/ # Runtime service
│ └── variable-panel-plugin/ # Variable panel plugin
│ └── components/ # Variable panel components
├── services/ # Service layer
│ ├── index.ts
│ └── custom-service.ts # Custom service
├── shortcuts/ # Shortcuts system
│ ├── index.ts
│ ├── constants.ts # Shortcut constants
│ ├── shortcuts.ts # Shortcut definitions
│ ├── type.ts # Type definitions
│ ├── collapse/ # Collapse shortcut
│ ├── copy/ # Copy shortcut
│ ├── delete/ # Delete shortcut
│ ├── expand/ # Expand shortcut
│ ├── paste/ # Paste shortcut
│ ├── select-all/ # Select-all shortcut
│ ├── zoom-in/ # Zoom-in shortcut
│ └── zoom-out/ # Zoom-out shortcut
├── styles/ # Styles
├── typings/ # Type definitions
│ ├── index.ts
│ ├── json-schema.ts # JSON Schema types
│ └── node.ts # Node type definitions
└── utils/ # Utility functions
 ├── index.ts
 └── on-drag-line-end.ts # Handle end of drag line

Key Directory Functions

1. `/components` - Component Library

base-node: Base rendering components for all nodes
testrun: Complete test-run module, including status bar, form, and panel
sidebar: Sidebar components providing tools and property panels
node-panel: Node add panel with drag-to-add capability

2. `/nodes` - Node System

Each node type has its own directory, including:

Node registration (index.ts)
Form metadata (form-meta.ts)
Node-specific components and logic

3. `/plugins` - Plugin System

runtime-plugin: Supports both browser and server modes
context-menu-plugin: Right-click context menu
variable-panel-plugin: Variable management panel

4. `/shortcuts` - Shortcuts System

Complete keyboard shortcut support, including:

Basic actions: copy, paste, delete, select-all
View actions: zoom-in, zoom-out, collapse, expand
Each shortcut has its own implementation module

Application Architecture

Core Design Patterns

1. Plugin Architecture

Highly modular plugin system; each feature is an independent plugin:

plugins: () => [
 createFreeLinesPlugin({ renderInsideLine: LineAddButton }),
 createMinimapPlugin({ /* config */ }),
 createFreeSnapPlugin({ /* alignment config */ }),
 createFreeNodePanelPlugin({ renderer: NodePanel }),
 createContainerNodePlugin({}),
 createFreeGroupPlugin({ groupNodeRender: GroupNodeRender }),
 createContextMenuPlugin({}),
 createRuntimePlugin({ mode: 'browser' }),
 createVariablePanelPlugin({})
]

2. Node Registry Pattern

Manage different workflow node types via a registry:

export const nodeRegistries: FlowNodeRegistry[] = [
 ConditionNodeRegistry, // Condition node
 StartNodeRegistry, // Start node
 EndNodeRegistry, // End node
 LLMNodeRegistry, // LLM node
 LoopNodeRegistry, // Loop node
 CommentNodeRegistry, // Comment node
 HTTPNodeRegistry, // HTTP node
 CodeNodeRegistry, // Code node
 // ... more node types
];

3. Dependency Injection

Use Inversify for service DI:

onBind: ({ bind }) => {
 bind(CustomService).toSelf().inSingletonScope();
}

Core Features

1. Editor Configuration System

useEditorProps is the configuration center of the editor:

export function useEditorProps(
 initialData: FlowDocumentJSON,
 nodeRegistries: FlowNodeRegistry[]
): FreeLayoutProps {
 return useMemo<FreeLayoutProps>(() => ({
 background: true, // Background grid
 readonly: false, // Readonly mode
 initialData, // Initial data
 nodeRegistries, // Node registries
 // Core feature configs
 playground: { preventGlobalGesture: true /* Prevent Mac browser swipe gestures */ },
 nodeEngine: { enable: true },
 variableEngine: { enable: true },
 history: { enable: true, enableChangeNode: true },
 // Business rules
 canAddLine: (ctx, fromPort, toPort) => { /* Connection rules */ },
 canDeleteLine: (ctx, line) => { /* Line deletion rules */ },
 canDeleteNode: (ctx, node) => { /* Node deletion rules */ },
 canDropToNode: (ctx, params) => { /* Drag-and-drop rules */ },
 // Plugins
 plugins: () => [/* Plugin list */],
 // Events
 onContentChange: debounce((ctx, event) => { /* Auto save */ }, 1000),
 onInit: (ctx) => { /* Initialization */ },
 onAllLayersRendered: (ctx) => { /* After render */ }
 }), []);
}

2. Node Type System

The app supports multiple workflow node types:

export enum WorkflowNodeType {
 Start = 'start', // Start node
 End = 'end', // End node
 LLM = 'llm', // Large language model node
 HTTP = 'http', // HTTP request node
 Code = 'code', // Code execution node
 Variable = 'variable', // Variable node
 Condition = 'condition', // Conditional node
 Loop = 'loop', // Loop node
 BlockStart = 'block-start', // Sub-canvas start node
 BlockEnd = 'block-end', // Sub-canvas end node
 Comment = 'comment', // Comment node
 Continue = 'continue', // Continue node
 Break = 'break', // Break node
}

Each node follows a unified registration pattern:

export const StartNodeRegistry: FlowNodeRegistry = {
 type: WorkflowNodeType.Start,
 meta: {
 isStart: true,
 deleteDisable: true, // Not deletable
 copyDisable: true, // Not copyable
 nodePanelVisible: false, // Hidden in node panel
 defaultPorts: [{ type: 'output' }],
 size: { width: 360, height: 211 }
 },
 info: {
 icon: iconStart,
 description: 'The starting node of the workflow, used to set up information needed to launch the workflow.'
 },
 formMeta, // Form configuration
 canAdd() { return false; } // Disallow multiple start nodes
};

3. Plugin Architecture

App features are modularized via the plugin system:

Core Plugin List

FreeLinesPlugin - Connection rendering and interaction
MinimapPlugin - Minimap navigation
FreeSnapPlugin - Auto-alignment and guide-lines
FreeNodePanelPlugin - Node add panel
ContainerNodePlugin - Container nodes (e.g., loop nodes)
FreeGroupPlugin - Node grouping
ContextMenuPlugin - Right-click context menu
RuntimePlugin - Workflow runtime
VariablePanelPlugin - Variable management panel

4. Runtime System

Two run modes are supported:

createRuntimePlugin({
 mode: 'browser', // Browser mode
 // mode: 'server', // Server mode
 // serverConfig: {
 // domain: 'localhost',
 // port: 4000,
 // protocol: 'http',
 // },
})

Design Philosophy and Advantages

1. Highly Modular

Plugin architecture: Each feature is an independent plugin, easy to extend and maintain
Node registry system: Add new node types without changing core code
Componentized UI: Highly reusable components with clear responsibilities

2. Type Safety

Full TypeScript support: End-to-end type safety from configuration to runtime
JSON Schema integration: Node data validated by schemas
Strongly typed plugin interfaces: Clear type constraints for plugin development

3. User Experience

Real-time preview: Run and debug workflows live
Rich interactions: Dragging, zooming, snapping, shortcuts for a complete editing experience
Visual feedback: Minimap, status indicators, line animations

4. Extensibility

Open plugin system: Third parties can easily develop custom plugins
Flexible node system: Custom node types and form configurations supported
Multiple runtimes: Both browser and server modes

5. Performance

On-demand loading: Components and plugins support lazy loading
Debounce: Performance optimizations for high-frequency operations like auto-save

Technical Highlights

1. In-house Editor Framework

Based on @flowgram.ai/free-layout-editor, providing:

Free-layout canvas system
Full undo/redo functionality
Lifecycle management for nodes and connections
Variable engine and expression system

2. Advanced Build Configuration

Using Rsbuild as the build tool:

export default defineConfig({
 plugins: [pluginReact(), pluginLess()],
 source: {
 entry: { index: './src/app.tsx' },
 decorators: { version: 'legacy' } // Enable decorators
 },
 tools: {
 rspack: {
 ignoreWarnings: [/Criticaldependency/] // Ignore specific warnings
 }
 }
});

3. Internationalization

Built-in multilingual support:

i18n: {
 locale: navigator.language,
 languages: {
 'zh-CN': {
 'Never Remind': '不再提示',
 'Hold {{key}} to drag node out': '按住 {{key}} 可以将节点拖出',
 },
 'en-US': {},
 }
}

Name		Name	Last commit message	Last commit date
src		src
.eslintrc.js		.eslintrc.js
.gitignore		.gitignore
README.md		README.md
README.zh_CN.md		README.zh_CN.md
index.html		index.html
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
rsbuild.config.ts		rsbuild.config.ts
tsconfig.json		tsconfig.json

Uh oh!

Latest commit

History

Folders and files

Repository files navigation