How bcakmakoglu/vue-flow works
1. What this repo is
- This is a pnpm monorepo for Vue Flow, a Vue 3 flowchart/graph library.
- The repo is split into a core rendering/runtime package, several optional UI add-on packages, a VitePress docs site, many example apps, and Cypress component tests.
2. Core runtime is the center of the architecture
- packages/core is the primary subsystem and contains the actual graph engine.
- It owns the flow store, render containers, composables, types, and utility logic for nodes, edges, handles, selection, zoom/pan, and viewport control.
- Most other packages are thin extensions that depend on core rather than duplicating graph state.
3. Main data model: nodes, edges, and flow state
- The core API revolves around nodes and edges as graph elements.
- Nodes carry position and node-specific metadata; edges connect source/target node ids and may also carry custom rendering data.
- The store layer in packages/core/src/store is the central mutable/reactive state boundary; actions, getters, and hooks provide controlled access to that state.
4. Rendering pipeline
- VueFlow is the top-level container in packages/core/src/container/VueFlow.
- Inside it, the graph is rendered through layered containers:
- Viewport: pan/zoom transform handling
- Pane: interaction surface and pointer handling
- NodeRenderer: node instances
- EdgeRenderer: edge instances and marker definitions
- This makes the render path mostly: props/store → derived state → node/edge renderers → DOM/SVG output.
5. Interaction and editing flow
- User interactions such as dragging, connecting, selecting, resizing, and keyboard actions are handled through core composables like useDrag, useConnection, useNode, useEdge, useResizeHandler, and useKeyPress.
- These composables translate pointer/keyboard events into store updates and graph changes.
- Selection, connection, and viewport behavior are therefore managed as interaction helpers around the central store, not as isolated UI logic.
6. Component boundaries inside core
- packages/core/src/components contains reusable graph primitives such as:
- node wrappers and default/input/output node types
- edge variants and base edge geometry/rendering
- handle and selection helpers
- accessibility descriptions and user-selection overlays
- packages/core/src/utils contains graph math and behavioral helpers, including edge path generation, node/handle utilities, storage, logging, and auto-pan logic.
7. Public API boundary
- packages/core/src/index.ts and the package entrypoints expose the library surface used by apps and extensions.
- The repo also includes many composables exported for advanced use, so consumers can either use the high-level <VueFlow /> component or compose lower-level hooks for custom graph behaviors.
- The architecture is intentionally split between simple declarative usage and advanced composable-driven control.
8. Optional add-on packages
- Several sibling packages extend the core without changing it:
- packages/background: background grid/pattern rendering
- packages/controls: zoom/pan control buttons
- packages/minimap: compact overview of the graph
- packages/node-resizer: resize handles and resize controls
- packages/node-toolbar: floating toolbar anchored to nodes
- These packages typically consume Vue Flow context/state and render in the same flow surface, but remain separate installable artifacts.
9. Specialized edge package
- packages/pathfinding-edge is a distinct extension focused on obstacle-aware edge routing.
- It includes grid creation, bounding-box analysis, path generation, SVG path drawing, and arrow rendering.
- Architecturally, it sits beside the core as a custom edge implementation package rather than part of the generic edge renderer.
10. Documentation site
- docs is a standalone VitePress application that documents the library and showcases behavior.
- It contains guide pages, API docs, and rich interactive examples implemented in Vue components.
- The docs site is both a documentation layer and a live integration showcase for the library packages.
11. Example applications
- examples/ contains full apps for different host frameworks/runtimes: Vite, Nuxt 3, and Quasar.
- These examples demonstrate how the library integrates into real applications and how custom nodes, edges, layouts, DnD, teleportation, validation, and state persistence are built on top of the core.
- They are not part of the runtime library itself, but they are important for understanding intended usage boundaries.
12. Testing and verification
- tests/ uses Cypress component testing to validate store behavior, Vue Flow interactions, and optional components.
- There are explicit test groups for store operations, node/edge updates, viewport behavior, and add-on packages like background, controls, and minimap.
- This suggests the repo treats graph behavior as a UI/runtime contract that must be tested at the component level.
13. Build, release, and repo tooling
- The repo uses pnpm workspaces, Turbo, TypeScript project configs, and per-package Vite builds.
- Release management is changeset-based (.changeset, CHANGELOG.md, GitHub publish workflow), which is important for diagramming package lifecycle.
- GitHub Actions handles build/test/publish automation, while the devcontainer supports a reproducible development environment.
14. How to draw the architecture
- The central box should be packages/core, with arrows from apps/docs/examples/tests into it.
- Add-on packages should be shown as dependents of core that render into the same flow surface through shared context/store.
- Docs and examples should be shown as consumers of the library, not peers of runtime logic.
- The main internal flow is: input nodes/edges → reactive store → render containers/components → user interaction events → store updates → rerender.
Main entry points: store Store · VueFlow.vue Vue Flow · config.mts Docs site · component Cypress tests
Components 22
Core runtime
Primary graph engine, render pipeline, composables, store, and shared types.
- Vue Flow · Top-level component and render entry for the core library.
packages/core/src/container/VueFlow/VueFlow.vue - Store · Central mutable graph state boundary for nodes, edges, viewport, and selection.
packages/core/src/store - Node renderer · Renders node instances from store-derived state.
packages/core/src/container/NodeRenderer/NodeRenderer.vue - Edge renderer · Renders edges and marker definitions from store-derived state.
packages/core/src/container/EdgeRenderer/EdgeRenderer.vue - Viewport · Handles pan/zoom transforms and viewport framing.
packages/core/src/container/Viewport/Viewport.vue - Pane · Pointer and interaction surface for graph editing gestures.
packages/core/src/container/Pane/Pane.vue - Composables · Drag, connect, resize, keyboard, and viewport helpers that translate input into store updates.
packages/core/src/composables - Primitives · Core node, edge, handle, selection, and accessibility primitives.
packages/core/src/components - Graph utils · Path generation, graph math, node/edge utilities, storage, and autopan helpers.
packages/core/src/utils - Types · Shared node, edge, connection, flow, and store type definitions.
packages/core/src/types
Add-ons
Optional packages that extend the core flow surface.
- Background · Renders grid and pattern backgrounds in the flow surface.
packages/background/src/Background.vue - Controls · Zoom and pan control buttons for the flow surface.
packages/controls/src/Controls.vue - Minimap · Compact overview of the current graph and viewport.
packages/minimap/src/MiniMap.vue - Node resizer · Resize handles and resize controls anchored to nodes.
packages/node-resizer/src/NodeResizer.vue - Node toolbar · Floating toolbar anchored to selected nodes.
packages/node-toolbar/src/NodeToolbar.vue - Pathfinding edge · Obstacle-aware routed edge implementation with grid and SVG path generation.
packages/pathfinding-edge/src/edge/PathFindingEdge.vue
Consumers
Docs site and example applications built on top of the library.
- Docs site · Documentation and live examples for the library.
docs/src/.vitepress/config.mts - Vite examples · Primary Vue/Vite showcase app for custom nodes, edges, layouts, and interactions.
examples/vite/main.ts - Nuxt example · Nuxt 3 integration example for the library.
examples/nuxt3/app.vue - Quasar example · Quasar integration example for the library.
examples/quasar/src/App.vue
Quality
Component tests and repo tooling for build/release workflows.
- Cypress tests · Component-level verification for store behavior, Vue Flow interactions, and add-ons.
tests/cypress/component - Tooling · pnpm workspace, Turbo, TypeScript config, changesets, and CI/release automation.
turbo.json
Connections 37
- Vue Flow → Store: reads/writes · VueFlow is driven by reactive graph state.
- Vue Flow → Viewport: wraps · The top-level container embeds the viewport transform layer.
- Vue Flow → Pane: hosts · The interaction pane captures pointer events over the canvas.
- Viewport → Node renderer: contains · Viewport content includes node rendering.
- Viewport → Edge renderer: contains · Viewport content includes edge rendering.
- Pane → Composables: drives · User gestures are translated through composables.
- Composables → Store: updates · Interaction hooks mutate the central store.
- Store → Node renderer: derives state for · Node renderer consumes store-derived node state.
- Store → Edge renderer: derives state for · Edge renderer consumes store-derived edge state.
- Store → Primitives: feeds · Store state powers primitives like nodes, edges, handles, and selection overlays.
- Primitives → Graph utils: uses · Primitives rely on shared graph and path utilities.
- Graph utils → Types: shapes · Utility functions operate on core graph model types.
- Background → Store: consumes · Add-on reads shared flow state/context.
- Controls → Composables: uses · Controls invoke viewport helpers and state actions.
- Minimap → Store: consumes · Minimap reflects the current graph and viewport.
- Node resizer → Composables: uses · Resize interactions are implemented through core hooks.
- Node toolbar → Store: anchors to · Toolbar positions itself from node state and selection.
- Pathfinding edge → Primitives: extends · Provides a specialized edge implementation beside the generic edge renderer.
- Docs site → Vue Flow: documents · Docs demonstrate the primary runtime API.
- Docs site → Background: shows · Documentation covers add-on components.
- Docs site → Controls: shows · Documentation covers add-on components.
- Docs site → Minimap: shows · Documentation covers add-on components.
- Docs site → Node resizer: shows · Documentation covers add-on components.
- Docs site → Node toolbar: shows · Documentation covers add-on components.
- Vite examples → Vue Flow: integrates · Main example app exercises the core library.
- Vite examples → Node resizer: demonstrates · Examples show optional add-ons and custom behaviors.
- Vite examples → Pathfinding edge: demonstrates · Examples include specialized edge implementations.
- Nuxt example → Vue Flow: integrates · Nuxt example consumes the core library.
- Quasar example → Vue Flow: integrates · Quasar example consumes the core library.
- Cypress tests → Store: verifies · Component tests cover store operations and graph state behavior.
- Cypress tests → Vue Flow: verifies · Component tests cover render and interaction contracts.
- Cypress tests → Background: verifies · Tests cover add-on packages.
- Cypress tests → Controls: verifies · Tests cover add-on packages.
- Cypress tests → Minimap: verifies · Tests cover add-on packages.
- Tooling → Vue Flow: builds · Workspace tooling supports package builds and releases.
- Tooling → Docs site: builds · Workspace tooling supports docs builds.
- Tooling → Cypress tests: runs · Workspace tooling supports component test execution.