agentleFS
noeltocknoeltock/react-flow/SKILL.md

react-flow

Skill0 starsChanged 3 months agoMITView on GitHub

Build and fix React Flow (@xyflow/react v12) node-based diagrams that look uniform, balanced, and aesthetically placed FROM THE START — auto-layout, clean connectors, consistent node sizing, and a reusable scaffolding baseline. Covers static/presentation diagrams (decks, docs, PDF export), interactive editors, headless/SSR capture, custom nodes/edges, and the keep-vs-switch decision. Freshness-aware: verifies current official docs, npm metadata, and load-bearing known issues when the task depends on current behavior. Triggers on: "react flow", "reactflow", "@xyflow/react", "xyflow", "node-based diagram", "flow diagram", "flowchart in react", "graph editor", "diagram connectors look messy", "auto layout diagram", "dagre"/"elkjs" + react, "export flow to image/PDF", "FlowDiagram", node/edge layout problems.

6 other projects use a version of this.

Adopted by

Most recently taken up by

  • Other versions6 projects use a version of this.

    Word for word · 0

    None found.

    Edited · 0

    None found.

    Wrote their own version · 6

    1. shep-ai/shep★ 277same name
    2. framara/react-flow-skill★ 55same name
    3. fatih-developer/fth-skills★ 7same name
    4. SnowBeatRain/skills★ 3same name
    5. udaykumar-dhokia/mcp-flow★ 2same name
    6. ryonakae/sheltie★ 1same name

    How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.

The file

We split this skill into the rules it gives an agent

5 rules. 0 are common, 3 are distinctive, and 2 are very specific to this project.

  • 0

    Common

    Most of the 5 edited versions we read keep these.

  • 3

    Distinctive

    This author's own choices. Worth a look.

  • 2

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    If you keep React Flow, follow the aesthetic baseline — it removes most of the pain.

    line 76
  2. Very specific:

    Control zoom deliberately: Use one fitView padding value.

    line 97
  3. Distinctive:

    Run the relevant freshness checks when the task depends on current versions, current APIs, or a fast-moving caveat.

    line 113
  4. Very specific:

    If you hit a symptom, check references/known-issues.md before debugging from scratch.

    line 117
  5. Distinctive:

    Verify visually (render/screenshot at target size).

    line 118

“Common” is measured: kept by at least 6 in 10 of the 5 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

react-flow — aesthetic, balanced node diagrams that work the first time

The north star: a React Flow diagram, in any context, should land aesthetically placed with clean connectors and uniform scaffolding as early as possible — no "messy connectors / total chaos / retune the spacing by hand" loop. Everything below serves that. The fastest path to balance is let an algorithm place the nodes, fix the sizes, match the handles to the flow direction, and cap the zoom — not hand-tuned x/y constants.

Freshness protocol — use when currentness is load-bearing

This skill is a dated snapshot, not gospel. React Flow ships often; treat the baked guidance as "last known good." Apply the cheap checks needed for the current task; do not turn an ordinary diagram request into an unrelated research project.

  1. Resolve the relevant official docs via Context7 (/websites/reactflow_dev) when available, or use reactflow.dev directly. Context7 version metadata can lag npm, so never use it as the package-version check.
  2. Check registry versions when selecting or changing dependencies: npm view @xyflow/react version peerDependencies dependencies --json, plus npm view @dagrejs/dagre version --json or npm view elkjs version --json when layout is in scope. Compare with the Last verified stamp below. A major/minor jump means re-read before trusting.
  3. Query only the task's topic with Context7's query-docs tool against /websites/reactflow_dev (e.g. "fitView options", "layouting dagre elk", "migrate to v12", "server side rendering image"). Prefer what it returns over this file.
  4. For third-party / fast-moving caveats (open GitHub issues, html-to-image working version, dagre/elk maintenance), re-check live — spawn web-runner or run /research for anything load-bearing. references/known-issues.md lists what to re-confirm and the issue URLs.
  5. If you find material drift, prefer the live source and tell the user it superseded this snapshot. Update this installed skill only when skill maintenance is explicitly part of the task; ordinary React Flow work does not authorize it.

For version claims or load-bearing fast-moving caveats, state what was verified. "The docs changed" is a first-class outcome.

When to use

  • Creating or restyling any React Flow diagram (especially "make it look balanced").
  • Connectors look messy / nodes overlap / layout feels hand-tuned and fragile.
  • Exporting a diagram to image/PDF (deck slides, docs, OG images, headless render).
  • Debugging a known React Flow footgun (fitView no-op, edges not rendering, re-render warnings).
  • Deciding whether React Flow is even the right tool (see references/decision.md).

Verified dependency baseline (not a lockfile)

As of 2026-08-31: @xyflow/react 12.11.5 (pulling @xyflow/system 0.0.81), with React/ReactDOM peers >=17; @dagrejs/dagre 3.1.1; elkjs 0.12.0. Dagre v3 ships native TypeScript types, so do not add legacy @types/dagre. Choose dagre or ELK for the actual layout need rather than installing both. For client-side export, the exception is deliberate: keep html-to-image pinned to exactly 1.11.11 until the current official example and open issue say otherwise. Re-run the freshness protocol before changing any of these.

The decision gate (read before building)

React Flow earns its weight for interactive node UIs (editors, pipelines, builders). For purely static diagrams you already know the shape of, plain authored SVG or dagre/elk → your own SVG is often simpler and gives total control. Its interaction/runtime dependencies are irrelevant for a local deck/PDF, but the complexity tax is real. Full tradeoff: references/decision.md. If you keep React Flow, follow the aesthetic baseline — it removes most of the pain.

The aesthetic baseline (the whole point)

Get all five right and diagrams look balanced immediately. Detail + code: references/aesthetics.md.

  1. Place with a layout engine, not by hand. ELK (elk.algorithm: layered) for flows; dagre for trees. Hand x/y is the #1 cause of the "chaos / retune forever" loop. Feed it node.measured dimensions. ELK can also compute orthogonal edge sections, but built-in React Flow edges use them only if you map them into a custom edge.
  2. Fix node sizes deliberately. One (or few) canonical widths so layers align. For ordinary client rendering, size with style/className and lay out from node.measured; use top-level width/height only for intentionally fixed or server-rendered nodes, and initialWidth/initialHeight when the client may remeasure.
  3. Match handles to flow direction. L→R ⇒ sourcePosition: Right, targetPosition: Left (T→B ⇒ Bottom/Top). Mismatched handles are why connectors elbow and cross. Set them from the layout direction.
  4. One connector style, one accent. Uniform smoothstep, thin neutral stroke (~1.5px), consistent ArrowClosed marker. For rounded corners, put pathOptions.borderRadius on edges typed as BuiltInEdge; it does not type-check in DefaultEdgeOptions in 12.11.5. Reserve a single brand/accent colour for at most one highlighted path. No label clutter.
  5. Control zoom deliberately. Use one fitView padding value; add maxZoom: 1 when a sparse graph must not blow up past 1:1, but omit the cap when a compact graph should fill a larger canvas.

Quick cheat sheet (verify via freshness protocol)

  • Static/read-only recipe + over-zoom fix → references/static-config.md
  • Auto-layout (dagre/elk) integration, node.measured → references/layout.md
  • Custom nodes, v12 sizing, handles, edge types/routing, nodeTypes identity → references/nodes-edges.md
  • Performance (memoization, selectors, culling, CSS/compositing, benchmarks) → references/performance.md
  • Testing (jsdom contract vs browser-fidelity acceptance) → references/testing.md
  • Headless / PDF / image capture (the useNodesInitialized gate, html-to-image pin) → references/headless-pdf.md
  • v11 → v12 breaking changes → references/migration-v12.md
  • Known issues & workarounds (from the GitHub tracker) → references/known-issues.md
  • Keep React Flow vs plain SVG / dagre+SVG / Mermaid → references/decision.md

Working mode

  1. Run the relevant freshness checks when the task depends on current versions, current APIs, or a fast-moving caveat.
  2. State the context (static deck / interactive / headless export) — it changes the recipe.
  3. Apply the aesthetic baseline; pull the relevant reference for specifics.
  4. If you hit a symptom, check references/known-issues.md before debugging from scratch.
  5. Verify visually (render/screenshot at target size). For PDF/deck work, gate capture on readiness, don't guess a timeout.

Last verified: 2026-08-31 · Target: @xyflow/react v12 (latest verified 12.11.5; @xyflow/system 0.0.81) · React ≥ 17 (17/18/19).

Changelog

  • 2026-06-16 — Initial skill. Built from context7 official docs + multi-angle research (layout, static config, headless/PDF, v11→v12 migration, keep-vs-switch) + a sweep of the xyflow/xyflow GitHub issue tracker for recurring problems/workarounds.
  • 2026-06-16 — Dogfooded on a real deck diagram (dagre auto-layout duplicate vs hand-tuned original). Auto-layout confirmed: balanced, clean connectors, zero coordinate constants. Corrected the maxZoom:1 guidance from "always" to situational — it under-fills a compact graph on a large canvas; omit it for fill-the-canvas diagrams.
  • 2026-08-31 — Refreshed against Context7, current React Flow docs/releases, npm, and issue state. Updated React Flow/Dagre/ELK versions; retained the deliberate html-to-image@1.11.11 pin; corrected Tailwind layering, node sizing, attribution, SSR, ELK edge typing/routing ownership, and pathOptions TypeScript guidance.
  • 2026-08-31 — Added performance and testing playbooks, dynamic-handle and custom-edge invariants, and the graph-editor versus workflow-runtime boundary. Scoped freshness checks to load-bearing claims and removed implicit authorization for self-editing.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.