TopoViewer
TopoViewer turns topology.yaml + stylesheet.yaml into interactive,
embeddable, schema-validated topology diagrams for infrastructure docs,
internal portals, and ops dashboards.
It is a Topology as Code toolkit for teams that want network, infrastructure, service, and other connected-system diagrams to stay close to source data.
Topology here means a diagram or graph made of meaningful objects and relationships: nodes, links, paths, regions, layers, labels, data, and attention rules. TopoViewer keeps those facts in declarative YAML and keeps presentation policy in selector-based stylesheets, then renders both through an embeddable TypeScript/React runtime.
TopoViewer is not a generic Mermaid.js replacement. Mermaid is broad text-to-diagram syntax for many diagram families. TopoViewer is narrower and more semantic: it is built for inspectable, data-driven topology views where layers, regions, paths, operational metadata, focus behavior, and reusable runtime APIs matter.
Start In 60 Seconds
npm install topoviewer @xyflow/react react react-dom
- Render the copyable YAML pair in First Topology.
- Style it with Style Your First Topology.
- Embed it in React or MkDocs.
Choose A Path
| Need | Start here |
|---|---|
| Understand the product | Why TopoViewer |
| Author a topology | First Topology |
| Style a topology | Style Your First Topology |
| Explore examples | Examples |
| Embed in a React product | React and TypeScript API |
| Embed in documentation | MkDocs or Static HTML / Zensical Adapter |
| Operate from telemetry | Grafana TopoViewer Panel |
| Reference accepted contracts | Object attributes, YAML schemas, compatibility, and stylesheet reference |
| Evaluate architecture and risk | Architecture, threat model, performance and accessibility, and Adopt TopoViewer Or Keep Topology Locked To A Surface |
| Maintain or release the repo | Production Hardening, Design Review Checklist, Release, and Documentation Standard |
| Debug a broken render | Debug Rendering |
Integration Surfaces
TopoViewer's first public adoption path is the React package plus documentation embeds. Authoring tools and operational dashboards exist to prove the model, but they are not all part of the same stability promise.
| Surface | Status | Use today |
|---|---|---|
| TypeScript/React package | Supported | Install topoviewer from npm and embed schema-validated topology diagrams in React applications. |
| MkDocs | Supported | Publish live YAML examples through mkdocs-topoviewer. |
| Browser harness | Experimental | Author, validate, preview, and export TopoViewer YAML while the authoring UX matures. |
| Grafana panel | Experimental | Mount topology/style/mapper bundles and render Prometheus-driven overlays. |
| Zensical | Supported Adapter | Preview the same docs content through the generated Zensical site. |
| VS Code extension | Experimental | Preview TopoViewer YAML locally; automatic full-project authoring is still evolving. |
| Grafana Containerlab mode | Lab | Validate realistic telemetry under the Grafana lab; not a separate production surface. |
| NetBox | Roadmap | Future in-product topology visualization from NetBox inventory and platform data. |
| OpsMill/Infrahub | Roadmap | Future in-product topology visualization from Infrahub network topology and inventory data. |
Support Status Labels
| Status | Meaning |
|---|---|
| Supported | Implemented, documented, CI-gated, and intended for normal use. Compatibility expectations apply. |
| Supported Adapter | Implemented, documented, and CI-gated as an adapter path, not as a native upstream plugin package. |
| Experimental | Implemented enough to try, but API, UX, packaging, or operational behavior may still change. |
| Lab | Disposable local validation environment. Do not treat it as production deployment guidance. |
| Roadmap | Planned or under study. Do not depend on it as shipped behavior. |
| Maintainer | Repository maintenance workflow, not an end-user product surface. |
Examples
The feature examples are generated from
packages/topoviewer/content/examples. Each example is both documentation
and a Playwright-backed test fixture.