ngDiagram skill

---
name: ng-diagram-fundamentals
description: Use when starting any ng-diagram task or unsure how the library works - data flow, golden rules, system-owned node/edge fields, where NgDiagram services can be injected, and which ng-diagram skill to load next.
license: Apache-2.0
---

# ng-diagram fundamentals

How ng-diagram works, the rules that prevent most bugs, and where to look next. The skill map at the end names the skill that owns each topic.

## Rules

- **Import the styles globally.** `@import 'ng-diagram/styles.css';` goes in the global stylesheet (`src/styles.css` or `.scss`), never in a component's `styles`. The library is styled through CSS variables on `:root`, and component styles are scoped. See `ng-diagram-setup`.
- **One `provideNgDiagram()` per diagram.** Put it in `providers` of the component that renders `<ng-diagram>`, or of an ancestor that also renders your toolbar or sidebar. Services resolve to the nearest registration, so two diagrams under one registration fight over one engine.
- **Change the model only through the services** (`NgDiagramModelService`, `NgDiagramSelectionService`, `NgDiagramNodeService`, ...). Do not mutate node or edge objects or write to the adapter from `getModel()`: only the services run middlewares, routing, z-index and events.
- **`await` when the next line depends on the change**, otherwise `void` the promise. Never `await` a service call inside a middleware: the update pipeline is not re-entrant and the await deadlocks (see `ng-diagram-middleware`).
- **Never write system-owned fields:** `measuredPorts`, `measuredBounds`, `measuredLabels`, `computedZIndex`, `computedHidden`, `sourcePosition`/`targetPosition` of connected edge ends, `points` of auto-routed edges, `size` of auto-sized nodes. The library recomputes them and your value is lost. Read `references/model-reference.md` when you need to know who owns a property.
- **Wait for initialization** before working with a new model: use `(diagramInit)` or `isInitialized()`. Calls made right after you assign a new model still reach the old model and are lost.
- **Hide elements with the `hidden` flag (since 1.4.0), not CSS `display: none`.** CSS-hidden elements cannot be measured, so loading waits for the measurement timeout and logs warnings. See `ng-diagram-visibility`.
- **Create every model with `initializeModel()`** (pass a custom adapter through `initializeModelAdapter()`), and give each diagram instance its own model. The adapter is destroyed together with its diagram.

## How it works

```
your code ──► NgDiagram*Service method ──┐
user gesture (drag, draw, keys) ─────────┤
                                         ▼
            command (one operation: addNodes, moveNodesBy, paste, ...)
                                         ▼
   middleware chain: your middlewares + built-ins (internal ids, z-index, edge routing)
                                         ▼
   model (the ModelAdapter from initializeModel) ──► events: (selectionChanged), addEventListener, ...
                                         ▼
               Angular renders nodes, edges, ports and labels
                                         ▼
   ResizeObserver measures nodes, ports and edge labels; the results go back through
   the same pipeline as size / measuredPorts / measuredLabels, and edges re-route
```

- Each `<ng-diagram>` has one engine. It is created when `<ng-diagram>` first renders and created again when you bind a new model. Before that, service methods throw `[ngDiagram] Library engine not initialized yet.`