JavaScript is required
relation-graph Relational Data Visualization and Editing
Sign in 中文 GitHub

Platform Integration

This document provides an overview of relation-graph’s multi-platform architecture. The system supports Vue 2, Vue 3, React, Svelte, and Web Components through a single framework-agnostic core with thin platform-specific adapters. This design ensures consistent functionality across all platforms while leveraging each framework’s native reactivity system.

For detailed integration information for specific frameworks, see:

For core architecture details, see Core Architecture. For build and distribution processes, see Build System & Distribution.

Multi-Platform Design

Relation-graph achieves cross-platform compatibility by separating graph logic from framework-specific rendering. The relation-graph-models package contains all core functionality, while platform packages provide integration layers.

Architectural Layers

System Architecture Overview

graph TB
    subgraph PlatformLayer["Platform Layer"]
        Vue2["@relation-graph/vue2
Vue 2 Components"]
        Vue3["@relation-graph/vue
Vue 3 Components"]
        React["@relation-graph/react
React Components"]
        Svelte["@relation-graph/svelte
Svelte Components"]
        WC["@relation-graph/web-components
Web Components"]
    end
    
    subgraph IntegrationLayer["Integration Layer"]
        DataProviders["Framework-Specific Data Providers
RGDataProvider4Vue2/Vue3/React/Svelte"]
        Hooks["Framework Hooks & Context
useRelationGraph, RGProvider"]
    end
    
    subgraph CoreLayer["Core Library - relation-graph-models"]
        RGCore["RelationGraphCore
RelationGraphFinal"]
        DataModel["Data Management
RGDataProvider, RGNode, RGLine"]
        Layouts["Layout Algorithms
RGTreeLayout, RGForceLayout"]
        Events["Event System
RelationGraphWith7Event"]
    end
    
    Vue2 --> DataProviders
    Vue3 --> DataProviders
    React --> DataProviders
    Svelte --> DataProviders
    WC --> DataProviders
    
    DataProviders --> Hooks
    Hooks --> RGCore
    
    RGCore --> DataModel
    RGCore --> Layouts
    RGCore --> Events

Sources: packages/platforms/vue2/src/index.ts:1-142, packages/platforms/vue3/src/index.ts:1-139, packages/platforms/react/src/index.ts:1-153, Diagram 1 from high-level architecture

Core Library Structure

The relation-graph-models package provides:

Component Purpose
RelationGraphCore / RelationGraphFinal Main graph instance class with all capabilities
RGDataProvider Abstract base for reactive data integration
Layout classes RGTreeLayout, RGForceLayout, RGCenterLayout, etc.
Type definitions RGNode, RGLine, RGLink, RGOptions
Utility modules RGGraphMath, RGNodesAnalytic, path generators

Sources: packages/platforms/vue2/src/index.ts:34-77, packages/platforms/vue3/src/index.ts:33-72, packages/platforms/react/src/index.ts:39-83

Data Provider System

The data provider system bridges the framework-agnostic core with each platform’s reactivity system. RelationGraphWith2Data provides integration methods for each framework, which instantiate the appropriate RGDataProvider subclass.

Provider Architecture

Data Provider Integration Flow

graph LR
    subgraph CoreInit["Initialization in RelationGraphWith2Data"]
        SetVue2["setReactiveData4Vue2()"]
        SetVue3["setReactiveData4Vue3()"]
        SetReact["setReactiveData4React()"]
        SetSvelte["setReactiveData4Svelte()"]
    end
    
    subgraph ProviderInstances["Provider Instances"]
        Vue2Prov["RGDataProvider4Vue2"]
        Vue3Prov["RGDataProvider4Vue3"]
        ReactProv["RGDataProvider4React"]
        SvelteProv["RGDataProvider4Svelte"]
    end
    
    subgraph ReactivitySystems["Framework Reactivity"]
        Vue2React["Vue.set / Vue.delete"]
        Vue3React["reactive() / ref()"]
        ReactState["setState callbacks"]
        SvelteStores["writable() stores"]
    end
    
    SetVue2 --> Vue2Prov
    SetVue3 --> Vue3Prov
    SetReact --> ReactProv
    SetSvelte --> SvelteProv
    
    Vue2Prov --> Vue2React
    Vue3Prov --> Vue3React
    ReactProv --> ReactState
    SvelteProv --> SvelteStores

Sources: packages/relation-graph-models/models/RelationGraphWith2Data.ts:17-119

RGDataProvider Interface

All data providers implement the RGDataProvider abstract class, which defines:

Method Description
updateOptions(options) Update graph configuration
addNodes(nodes) Add nodes to the graph
removeNodeById(nodeIds) Remove nodes by ID
updateNode(nodeId, updates) Update node properties
addLines(lines) Add lines to the graph
removeLine(lineId) Remove a line
dataUpdated() Trigger view update (framework-specific)

The dataUpdated() method is where each provider integrates with its framework’s reactivity system, calling the appropriate update mechanism.

Sources: packages/relation-graph-models/data/RGDataProvider.ts:34-170

Platform-Specific Integration

Each platform provides a tailored integration that leverages framework-specific patterns and idioms. Below is a summary of each platform; see the linked sections for detailed information.

Platform Comparison

Platform Package Name Reactivity System Context/Provider Pattern Primary API
Vue 2 @relation-graph/vue2 Vue.set() / Vue.delete() provide() / inject() Options API, Slots
Vue 3 @relation-graph/vue reactive() / ref() provide() / inject() Composition API, useRelationGraph()
React @relation-graph/react setState callbacks Context API useRelationGraph() hook, RGProvider
Svelte @relation-graph/svelte writable() stores setContext() / getContext() RGHooks collection
Web Components @relation-graph/web-components Event-based updates N/A (Web Standards) Custom element attributes

Sources: packages/platforms/vue2/src/index.ts:1-142, packages/platforms/vue3/src/index.ts:1-139, packages/platforms/react/src/index.ts:1-153, platforms/vue2/package.json:1-65, platforms/vue3/package.json:1-65, platforms/react/package.json:1-65, platforms/svelte/package.json:1-65, platforms/web-components/package.json:1-65

Vue Integration (Vue 2 & Vue 3)

Vue integration provides RelationGraph.vue component with full support for slots, v-model, and Vue’s reactivity system:

  • Vue 2: Uses RGDataProvider4Vue2 with Vue.set() for reactivity, provide/inject for instance access, and graphStoreMixin for state management
  • Vue 3: Uses RGDataProvider4Vue3 with reactive() stores, Composition API with useRelationGraph() hook, and RGProvider wrapper component

Both versions export the same component hierarchy and utilities. See Vue 2 & Vue 3 Integration for details.

Sources: packages/platforms/vue2/src/index.ts:8-141, packages/platforms/vue3/src/index.ts:9-138

React Integration

React integration provides hooks-based API with useRelationGraph() hook for graph instance access:

  • Uses RGDataProvider4React with setState callback for triggering re-renders
  • Context-based architecture with RelationGraphStoreContext and RGProvider
  • Components use useImperativeHandle to expose imperative API
  • Full TypeScript support with RelationGraphComponent type

See React Integration for detailed hook usage and context setup.

Sources: packages/platforms/react/src/index.ts:1-153

Svelte Integration

Svelte integration uses stores and context for reactive data management:

  • Uses RGDataProvider4Svelte with writable() stores
  • RGHooks collection provides helper functions for common operations
  • Components use getContext() to access graph instance
  • Stores automatically trigger reactive updates in Svelte components

See Svelte Integration for store structure and usage patterns.

Sources: platforms/svelte/package.json:1-65

Web Components

Web Components build is generated from the Svelte implementation, providing framework-agnostic custom elements:

  • Built using Svelte’s customElement: true compiler option
  • Registered as <relation-graph> custom element
  • Accessible from any JavaScript environment
  • Uses standard DOM events and attributes for API

See Web Components for build process and usage.

Sources: platforms/web-components/package.json:1-65, build-all.sh:23-26

Shared Component Structure

All platforms export a consistent set of components adapted to each framework’s conventions. The core component hierarchy remains the same across platforms.

Exported Components

Component Export Structure

graph TB
    subgraph MainComponents["Main Components"]
        RG["RelationGraph
Primary graph component"]
        RL["RelationLinker
Lines-only display"]
    end
    
    subgraph Primitives["Primitive Components"]
        FakeNode["RGFakeNode
Temporary node preview"]
        LinePath["RGLinePath
SVG path rendering"]
        LineText["RGLineText
Line label text"]
        NodeExpandHolder["RGNodeExpandHolder
Expand/collapse handle"]
    end
    
    subgraph UIWidgets["UI Widgets"]
        ToolBar["RGToolBar
Zoom/layout controls"]
        MiniToolBar["RGMiniToolBar
Compact toolbar"]
        MiniView["RGMiniView
Mini-map navigator"]
        Background["RGBackground
Grid/pattern background"]
        Watermark["RGWatermark
Copyright/watermark"]
        DebugView["RGDebugView
Debug information"]
    end
    
    subgraph EditingComponents["Editing Components"]
        EditNode["RGEditingNodeController
Node selection/resize"]
        EditLine["RGEditingLineController
Line vertex editing"]
        EditConnect["RGEditingConnectController
Connection targeting"]
        EditResize["RGEditingResize
Resize handles"]
        NearNodeWidget["RGEditingNearNodeWidget
Nearby node hints"]
        ConnectPoints["RGEditingConnectPoints
Connection points"]
        ReferenceLine["RGEditingReferenceLine
Alignment guides"]
        ConnectSource["RGConnectSource
Connection source"]
        ConnectTarget["RGConnectTarget
Connection target"]
    end
    
    subgraph ProviderContext["Provider/Context"]
        Provider["RGProvider
Context provider wrapper"]
    end
    
    RG --> Primitives
    RG --> UIWidgets
    RG --> EditingComponents
    RL --> LinePath
    RL --> LineText

Sources: packages/platforms/vue2/src/index.ts:106-141, packages/platforms/vue3/src/index.ts:106-138, packages/platforms/react/src/index.ts:113-153

Utility Exports

All platforms also export shared utility modules and layout classes:

Export Contents
RGLayouts BaseLayout, BidirectionalTreeLayout, CenterLayout, CircleLayout, FixedLayout, ForceLayout, RGFolderLayout
RGUtils RGOptionsDataUtils, RGLineDataUtils, RGNodeDataUtils, RGGraphMath, RGNodesAnalyticUtils, RGEffectUtils
RelationGraphCore Core graph instance class (for advanced usage)
Type definitions Full TypeScript types exported from relation-graph-models

Sources: packages/platforms/vue2/src/index.ts:60-77, packages/platforms/vue3/src/index.ts:55-72, packages/platforms/react/src/index.ts:66-83

Framework Adaptation Patterns

Aspect Vue 2/3 React Svelte
Instance Access inject('graphInstance') useContext(GraphContext) getContext('graph')
Event Handling @event="handler" onEvent={handler} on:event={handler}
Slots/Children <slot name="x"> props.children / render props <slot name="x">
Conditional Rendering v-if, v-show {condition && <C/>} {#if condition}
List Rendering v-for .map() {#each items}
Two-way Binding v-model Controlled components bind:value

Sources: Diagram 1 from high-level architecture

Build and Distribution

The library provides multiple distribution strategies to support different consumption patterns.

Package Structure

graph LR
    subgraph "Source Code"
        Models["relation-graph-models
TypeScript core"]
        Vue2Src["platforms/vue2"]
        Vue3Src["platforms/vue3"]
        ReactSrc["platforms/react"]
        SvelteSrc["platforms/svelte"]
    end
    
    subgraph "Build Output"
        LibVue2["lib/vue2/
UMD + ESM"]
        LibVue3["lib/vue3/
UMD + ESM"]
        LibReact["lib/react/
UMD + ESM"]
        LibSvelte["lib/svelte/
UMD + ESM"]
    end
    
    subgraph "NPM Packages"
        MainPkg["relation-graph@3.0.0
All frameworks"]
        Vue2Pkg["relation-graph-vue2@2.2.11"]
        Vue3Pkg["relation-graph-vue3@2.2.11"]
        ReactPkg["relation-graph-react@2.2.11"]
    end
    
    Models --> LibVue2
    Vue2Src --> LibVue2
    Vue3Src --> LibVue3
    ReactSrc --> LibReact
    SvelteSrc --> LibSvelte
    
    LibVue2 --> MainPkg
    LibVue3 --> MainPkg
    LibReact --> MainPkg
    LibSvelte --> MainPkg
    
    LibVue2 --> Vue2Pkg
    LibVue3 --> Vue3Pkg
    LibReact --> ReactPkg
    
    style MainPkg fill:#f9f9f9

NPM Package Exports

The main package (relation-graph@3.0.0) uses subpath exports for framework selection:

{
  "exports": {
    ".": { /* Vue 2 by default */ },
    "./react": { "import": "./lib/react/relation-graph.mjs" },
    "./vue2": { "import": "./lib/vue2/relation-graph.mjs" },
    "./vue3": { "import": "./lib/vue3/relation-graph.mjs" },
    "./svelte": { "import": "./lib/svelte/relation-graph.mjs" }
  }
}

Framework-specific packages provide direct imports:

  • relation-graph-vue2@2.2.11 - Vue 2 only
  • relation-graph-vue3@2.2.11 - Vue 3 only
  • relation-graph-react@2.2.11 - React only

Consumption Patterns

Monolithic Package:

// Vue 3
import { RelationGraph } from 'relation-graph/vue3'

// React
import { RelationGraph } from 'relation-graph/react'

Framework-Specific Package:

// Vue 2
import { RelationGraph } from 'relation-graph-vue2'

// React
import { RelationGraph } from 'relation-graph-react'

CDN (UMD):

<script src="https://unpkg.com/relation-graph@3.0.0/lib/vue2/relation-graph.umd.js"></script>

Sources: package.json:1-101, platforms/react/package.json:1-67, platforms/vue2/package.json:1-67, platforms/vue3/package.json:1-67

Performance Mode Integration

All platform integrations support performance mode, which switches to Canvas/WebGL rendering for large graphs.

Performance Mode Detection

The data provider checks options.performanceMode and options.showEasyView:

if (performanceMode && !showEasyView) {
  // Skip reactive updates for nodes/lines
  // Canvas rendering handles visualization
}

When performance mode is active:

  • Reactive stores are not updated for nodes/lines (to avoid overhead)
  • Canvas-based rendering in RGEasyView is used
  • Only options updates trigger reactive changes

This ensures smooth interaction even with thousands of nodes, as the reactive system only tracks configuration, not individual graph elements.

Sources: packages/relation-graph-models/data/RGDataProvider.ts:123-142, packages/relation-graph-models/models/RelationGraphWith9EasyView.ts:1-189