@yworks/yfiles-graphbuilder

---
name: yfiles-graphbuilder
description: This skill should be used when the user asks to "build a graph from data", "load data into a graph", "import JSON into yFiles", "create nodes from an array", "use GraphBuilder", or mentions "data to graph", "import data", "business data", "GraphBuilder", "TreeBuilder", or "AdjacencyGraphBuilder".
---

# Build Graphs from Data

Convert business data into graph visualizations using the `GraphBuilder` API.

## Before Building

Always query the yFiles MCP for current API:

```
yfiles:yfiles_get_symbol_details(name="GraphBuilder")
yfiles:yfiles_search_documentation(query="GraphBuilder tutorial")
```

## Quick Start

```typescript
import { GraphBuilder } from '@yfiles/yfiles'

const builder = new GraphBuilder(graph)
builder.createNodesSource({ data: nodesData, id: 'id' })
builder.createEdgesSource({
  data: edgesData,
  id: 'id',
  sourceId: 'source',
  targetId: 'target'
})
builder.buildGraph()
```

## Key Concepts

- **Data stays in tags**: Original data objects are stored in `element.tag` after build
- **ID mapping**: Use field name strings or accessor functions for `id`, `sourceId`, `targetId`
- **Build order**: Groups → nodes → edges (groups must exist before their children)
- **Provider functions**: Compute styles, labels, and layouts from data at build time
- **updateGraph()**: Incrementally updates an existing graph instead of rebuilding from scratch

**Important**: Never directly assign to readonly properties like `node.layout`, `edge.sourceNode`, or `edge.targetNode`. Use IGraph methods instead (e.g., `graph.setNodeLayout()`, `graph.setEdgePorts()`). The `@yfiles/eslint-plugin` rule `@yfiles/suggest-setter-methods` warns about these mistakes.

## After Building

Apply a layout to position the nodes:

```
/yfiles-layout
```

## Additional Resources

- **`references/patterns.md`** — Node/edge creation, custom styles from data, labels, node positioning, updating graphs
- **`references/advanced.md`** — Group nodes, ports and bends, `TreeBuilder`, `AdjacencyGraphBuilder`
- **`references/examples.md`** — Complete working code examples