xyflow — React Flow & Svelte Flow モノレポ解説

モノレポ構成

パッケージ構成

@xyflow/react

React Flow v12

React 向けのノードベース UI コンポーネント。TypeScript ジェネリクスで Node・Edge の型安全な拡張が可能。

packages/react/

@xyflow/svelte

Svelte Flow

Svelte 向けフロー UI。writable store で nodes / edges / viewport を管理する Svelte 流儀の API。

packages/svelte/

@xyflow/system

共有ヘルパーライブラリ

React / Svelte 双方が共有する純粋ロジック。型定義・パスユーティリティ・パンズーム・ドラッグ・ハンドルの実装を担う。

packages/system/

reactflow (v11)

React Flow v11

旧安定版。v11 ブランチで別途メンテナンス中。既存プロジェクトの継続利用に対応。

branch: v11

アーキテクチャ図

flowchart TD subgraph mono["xyflow monorepo"] direction TB react["@xyflow/react\n(packages/react)"] svelte["@xyflow/svelte\n(packages/svelte)"] system["@xyflow/system\n(packages/system)"] end subgraph react_internals["React Flow internals"] direction LR container["container/\nReactFlow"] components["components/\nHandle · EdgeLabel · Panel"] hooks["hooks/\nuseReactFlow · useNodes..."] store["store/\nZustand state"] end subgraph system_internals["system internals"] direction LR xypanzoom["xypanzoom\npan · zoom · wheel"] xyhandle["xyhandle\nconnect logic"] xydrag["xydrag\nnodeDrag"] utils["utils/\ngraph · edges · nodes"] end react --> system svelte --> system container --> hooks container --> components hooks --> store system --> xypanzoom system --> xyhandle system --> xydrag system --> utils classDef pkg fill:#e0f2fe,stroke:#0891b2,color:#0c4a6e classDef internal fill:#f0fdf4,stroke:#16a34a,color:#14532d classDef sys fill:#fef9c3,stroke:#ca8a04,color:#713f12 class react,svelte,system pkg class container,components,hooks,store internal class xypanzoom,xyhandle,xydrag,utils sys

@xyflow/system の役割 — React でも Svelte でも動く純粋 TypeScript で実装されており、フレームワーク非依存のコア機能（パンズーム・ドラッグ・ハンドル接続・エッジパス計算）を集約。両フレームワーク向けパッケージはこの共有レイヤーに依存して薄いアダプター層を持つ。

React Flow

ReactFlow コンポーネント — 主要 Props

Prop	型	説明
`nodes`	NodeType[]	表示するノードの配列（controlled モード）
`edges`	EdgeType[]	表示するエッジの配列（controlled モード）
`defaultNodes`	NodeType[]	初期ノード（uncontrolled モード）
`nodeTypes`	Record<string, ComponentType>	カスタムノードコンポーネントのマップ
`edgeTypes`	Record<string, ComponentType>	カスタムエッジコンポーネントのマップ
`onNodesChange`	(changes: NodeChange[]) => void	ノード位置・選択・削除変更ハンドラ
`onEdgesChange`	(changes: EdgeChange[]) => void	エッジ選択・削除変更ハンドラ
`onConnect`	(connection: Connection) => void	ハンドルからのエッジ接続時ハンドラ
`snapToGrid`	boolean	ドラッグ時にグリッドスナップを有効化
`fitView`	boolean	初期表示時に全ノードが収まるよう自動ズーム
`colorMode`	"light" \| "dark" \| "system"	テーマカラーモード（v12 新機能）
`connectionMode`	ConnectionMode	Strict（ソース→ターゲット）/ Loose（任意→任意）

プラグインコンポーネント

<MiniMap />

全体俯瞰ミニマップ。ノードカラーをカスタマイズ可能。

<Controls />

ズームイン・アウト・フィット・ロックボタン群。

<Background />

Dots / Lines / Cross の3種類の背景パターン。

<Panel />

フロー上に固定配置できる汎用コンテナ。位置指定可。

<Handle />

カスタムノード内の接続ポイント。type="source" / "target"。

<NodeToolbar />

ノード選択時に浮かぶツールバーコンテナ。

<NodeResizer />

ノードをドラッグでリサイズするハンドル。

<EdgeLabel />

エッジ中央に配置できるラベルコンポーネント。

React Flow Hooks

フック一覧

useReactFlow()

ノード・エッジ操作・ビューポート制御の全メソッドを返す主力フック。getNodes()・setNodes()・fitView()など。

useNodesState(init)

[nodes, setNodes, onNodesChange] を返すコンビニエンスフック。controlled モードのボイラープレートを削減。

useEdgesState(init)

[edges, setEdges, onEdgesChange] を返す。useNodesState のエッジ版。

useNodes()

現在のノード配列を購読するセレクタフック。変更がある時のみ再レンダリング。

useEdges()

現在のエッジ配列を購読。useNodes の edges 版。

useViewport()

{ x, y, zoom } を返す。スクロール・ズーム状態の読み取り専用サブスクリプション。

useKeyPress(keyCode)

指定キーの押下状態を boolean で返す。ショートカット実装に。

useOnViewportChange(opts)

ビューポート変更の onStart / onChange / onEnd コールバックを登録。

useHandleConnections(opts)

特定ハンドルへの接続一覧を返す。ハンドルの接続状態に応じたスタイリングに。

useNodeConnections(opts)

ノード全体への接続一覧を取得。source / target でフィルタ可能。

useNodesData(ids)

指定ノード ID の data フィールドを型安全に取得する。

useInternalNode(id)

内部 Node オブジェクト（measured・positionAbsolute 含む）にアクセス。

実験的 API

experimental_useOnNodesChangeMiddleware / experimental_useOnEdgesChangeMiddleware — ノード・エッジ変更をインターセプトして変形・キャンセルするミドルウェアパターン。将来の安定化を見据えた試験的実装。

Svelte Flow

Svelte Flow — API 対比

React Flow と同じ機能を持ちながら、Svelte の reactive store パラダイムに沿った API を提供。nodes / edges を writable() で持ち、リアクティビティは Svelte の仕組みに委ねる。

React Flow

const [nodes, setNodes, onNodesChange]
  = useNodesState(initialNodes);

<ReactFlow
  nodes={nodes}
  edges={edges}
  onNodesChange={onNodesChange}
  onEdgesChange={onEdgesChange}
  onConnect={onConnect}
>
  <MiniMap />
  <Controls />
  <Background />
</ReactFlow>

Svelte Flow

const nodes = writable(initialNodes);
const edges = writable(initialEdges);

<SvelteFlow
  {nodes}
  {edges}
  fitView
  on:nodeclick={handleClick}
>
  <Controls />
  <Background variant={Dots} />
  <MiniMap />
</SvelteFlow>

Svelte Flow エクスポート一覧

カテゴリ	エクスポート
メインコンポーネント	`SvelteFlow`
エッジ	`BezierEdge` · `StepEdge` · `SmoothStepEdge` · `StraightEdge` · `BaseEdge`
プラグイン	`Controls` · `Background` · `Minimap` · `NodeToolbar` · `EdgeToolbar` · `NodeResizer`
コンポーネント	`Handle` · `EdgeLabel` · `EdgeReconnectAnchor` · `SvelteFlowProvider` · `ViewportPortal` · `Panel`
フック (Svelte 5 rune)	`useSvelteFlow()` · `useUpdateNodeInternals()` · `useConnection()` · `useNodesData()` · `useNodeConnections()`
ストア	`useStore()`

セットアップ

はじめ方

1

インストール

# React Flow v12
npm install @xyflow/react

# Svelte Flow
npm install @xyflow/svelte

2

スタイルシートをインポート

// React
import '@xyflow/react/dist/style.css';

// Svelte
import '@xyflow/svelte/dist/style.css';

3

最小構成コード（React）

import { useCallback } from 'react';
import {
  ReactFlow, MiniMap, Controls, Background,
  useNodesState, useEdgesState, addEdge,
} from '@xyflow/react';

import '@xyflow/react/dist/style.css';

const initialNodes = [
  { id: '1', position: { x: 0,   y: 0   }, data: { label: 'Node 1' } },
  { id: '2', position: { x: 0,   y: 100 }, data: { label: 'Node 2' } },
];
const initialEdges = [{ id: 'e1-2', source: '1', target: '2' }];

export default function Flow() {
  const [nodes, setNodes, onNodesChange] = useNodesState(initialNodes);
  const [edges, setEdges, onEdgesChange] = useEdgesState(initialEdges);

  const onConnect = useCallback(
    (params) => setEdges((eds) => addEdge(params, eds)),
    [setEdges],
  );

  return (
    <ReactFlow
      nodes={nodes}
      edges={edges}
      onNodesChange={onNodesChange}
      onEdgesChange={onEdgesChange}
      onConnect={onConnect}
    >
      <MiniMap />
      <Controls />
      <Background />
    </ReactFlow>
  );
}

4

カスタムノード

import { Handle, Position } from '@xyflow/react';

// 1. カスタムノードコンポーネント定義
function TextNode({ data }) {
  return (
    <div className="text-node">
      <Handle type="target" position={Position.Top} />
      <p>{data.label}</p>
      <Handle type="source" position={Position.Bottom} />
    </div>
  );
}

// 2. nodeTypes に渡す
const nodeTypes = { text: TextNode };

// 3. ReactFlow に nodeTypes prop として渡す
<ReactFlow nodeTypes={nodeTypes} ... />