TSDiagram: turning TypeScript declarations into interactive diagrams

Diagrams generated from the type declarations themselves

TSDiagram is described as turning TypeScript into interactive diagrams, by defining interfaces, type aliases, classes, enums and function signatures to see their relationships. The home page is tsdiagram.com, and the app is a single web page you open in a browser.

The interesting decision is the input. A diagram tool usually asks you to draw boxes and arrows, or to describe a model in a modelling language. This one takes the type declarations you were going to write anyway and derives the picture from them, which means the diagram is a by-product of the code rather than a second artefact to keep in sync. The example links in the README cover the default case, interfaces, type aliases, and inheritance and implementation, which is a reasonable survey of what the parser recognises.

The audience splits in two. A developer sketching a module boundary can open the app, type the types, and see the graph before writing any implementation. A team with an existing codebase can generate the same picture from real files and keep it next to the code.

The features list is short and specific. Automatic layout that preserves manually positioned nodes, so you can fix the arrangement once and the tool will not undo it on the next render. Documents saved in the browser and shareable by URL, which means a diagram is a link rather than a file you attach. And SVG export from the web app, plus SVG and PNG export from the command line.

The project is TypeScript, licensed GPL-3.0, and the last push was on 2026-10-14. There are no GitHub releases, so npm is where the versions live.

The CLI renders SVG and PNG without a browser

The command line interface reads TypeScript from files, from stdin, or from inline code, and renders SVG and PNG with Takumi, sharing the web app's card presentation, fonts, themes, layout and edge routing.

tsdiagram render domain.ts -o diagram.svg --png
cat domain.ts | tsdiagram render
tsdiagram render --code 'interface User { id: string }' -o user.svg

The first command writes both `diagram.svg` and `diagram.png`. The second pipes a file in on standard input, and the third passes the source inline as a string.

The output defaults are spelled out in the README. Piped standard input and inline code default to `diagram.svg` in the current directory, and the `-o` or `--output` flag chooses another path for any of the input modes. There is a compatibility wrinkle worth knowing: positional output paths remain supported, but they cannot be combined with `-o` or `--output`.

Two operational details matter more than the flags. Rendering runs locally without a browser or a web server, so the CLI does not need a headless Chrome, which is what makes it usable in CI. And it requires Node.js 22.12 or later.

The text handling differs between the two paths, and the README is explicit about it. CLI SVG text is stored as vector outlines, while the web app's SVG export retains selectable text. That is a real trade-off rather than an inconsistency: the CLI output cannot be edited as text in a vector editor, but it also cannot be broken by a missing font, which matters when the file is generated in one environment and rendered in another.

For installation and options the README points at the CLI guide in the package directory, or `tsdiagram render --help`.

Four packages that separate analysis, presentation, editing and rendering

The repository is a pnpm workspace with four packages, and the split is the clearest description of the architecture available.

`core` holds the TypeScript analysis and the diagram models. It is the part that reads declarations and turns them into nodes and edges, and it carries no rendering concern.

`renderer` holds the shared diagram presentation, the browser rendering, and the browser-free Takumi export. Sharing the presentation layer between the web app and the CLI is what makes the README's claim coherent, that the CLI shares the web app's card presentation, fonts, themes, layout and edge routing. If the two drew the same graph differently, that claim would be false, and the tests living beside the code they cover are how the project keeps them honest.

`web` is the editor, the documents, the preferences and the sharing. This is where the browser-stored documents and the shareable by URL behaviour live, and where React Flow and the Monaco editor do their work.

`cli` is the Gunsmith commands, the render-process lifecycle and the file export. The mention of a render-process lifecycle is a hint about the implementation, since rendering happens out of process, which is how a CLI can render without a browser while reusing browser-targeted code.

The README also notes that the CLI is packaged for npm as `tsdiagram`, while core and renderer are internal packages. That is a sensible boundary. A user installs one package, and the others are implementation details that can change without a breaking release.

The wider technical dependencies are credited in the README, and they explain the design: React Flow for the interactive graph, Monaco for the code editing, elkjs for the automatic layout, dom-to-svg for turning the DOM into SVG in the browser, and Takumi for the headless export path.

Documents live in the browser, and the web export keeps text selectable

The storage model is the most consequential choice in the web app, and it is short. Documents are saved in your browser and shareable by URL.

That has two clear consequences. A diagram is not a file in a repository, it is a piece of browser state with a link, so a colleague can open the link and see the same diagram without an account, a server or a shared drive. And the content lives on one machine, which means the app has no backend to operate, host or pay for, and also that clearing browser data can lose work if the URL sharing path is not used.

The README's roadmap lists support for other document storage providers, which confirms that browser storage is a starting point rather than a fixed decision, and that the team sees the limitation.

The web export path is deliberately different from the CLI one. The web app's SVG export retains selectable text, so the result can be opened in a vector editor and edited like normal text, while the CLI stores text as vector outlines for rendering fidelity.

Everything the app does, the diagram, the editing, the preferences and the sharing, happens client side. The package manifest confirms the shape of the frontend, with React 19 types, Vite, Tailwind CSS 4 and PostCSS in the development dependencies, and the web build written to `packages/web/dist/`.

The `web` package is also where the automatic layout that preserves manually positioned nodes becomes visible, since moving a node and re-rendering is an editor behaviour, and the layout engine behind it, elkjs, has to be told which positions are fixed.

Working on the project: pnpm, vitest and a workspace-wide typecheck

The development instructions are concrete about versions. You need Node.js 22.12 or later and pnpm 10.14.0, and the package manifest pins the package manager with a `packageManager` field and declares the engine constraint.

From the repository root, installing dependencies and starting the web app is two commands.

pnpm install
pnpm dev

The rest of the scripts are listed in the README as a short catalogue. `pnpm test:run` runs the tests once and `pnpm test` runs them in watch mode. `pnpm typecheck` checks TypeScript across the workspace, and `pnpm build` checks types and then builds all packages, with the web build written to `packages/web/dist/`. `pnpm preview` previews the production web build.

The build script in the manifest is more revealing than the README summary. It runs the typecheck first, and then builds the packages with a filter that excludes the renderer and a workspace concurrency of one. In other words, the renderer is not built as part of the normal workspace build, because it is consumed as a library by the other packages rather than shipped on its own, and the build is serialised to keep the output deterministic.

The CLI is built separately, from its own package directory, and the README gives the sequence.

cd packages/cli
pnpm build
node dist/cli.js --help

The README notes that this also builds and bundles the renderer, which is the step that produces the standalone rendering path the CLI uses when it works without a browser.

Around the code there is the usual scaffolding: Vitest as the test runner with a coverage script, Prettier for formatting, husky and lint-staged for commit hooks, a `vitest.config.ts` at the root, shared browser build configuration in `build/browser-config.ts`, and a `.nvmrc`.

The roadmap, the licence, and where this is the wrong tool

The roadmap is short enough to quote in full, and it says as much about the present as the future. It lists function call visualisation, configurable TypeScript context including libraries, support for other document storage providers, and a move to Tree-sitter to support broader code and data-flow visualisation.

Read carefully, those four items describe the current limits. Function call visualisation is not there, so you get the type graph and not the control flow. The TypeScript context is not configurable, so the diagram reflects the code you give it and not the library types it pulls in. And the move to Tree-sitter implies the parsing today is TypeScript-specific, so other languages are out of scope.

The licence is GPL-3.0, which is copyleft. For a diagram generator used as a development tool that is usually not a problem, but it does matter if you want to embed the renderer in a commercial product, and it is worth reading before you build a pipeline on it. This is not legal advice, and the LICENSE file in the repository holds the terms.

With that in place, the cases where TSDiagram is the wrong tool are clear. It is not an architecture diagrammer, and it will not draw a deployment view or a sequence diagram. It is not a general modelling tool with a notation, since it derives its picture from declarations. And it is not a replacement for a maintained UML tool if your organisation already has a modelling standard that other artefacts follow.

The strongest case for it is the one the README leads with: the same source of truth, your type declarations, produces both the code and the diagram. If your diagrams currently live in a separate tool and drift from the code, that is the problem this solves, and the CLI output path, which can run in CI and write a committed SVG, is the feature that makes the diagram part of the repository rather than a picture in a slide.

Editorial conclusion

TSDiagram is a good fit for a TypeScript team that wants a fast picture of a type graph, either in a browser tab while designing a module or as a committed SVG produced by a script in CI. It is the wrong tool for a general purpose architecture diagram, for languages other than TypeScript, and for any project that needs a maintained UML tool rather than a diagram generated from declarations. Verify first that the version of the CLI you install matches your Node version, because the package requires Node.js 22.12 or later, and read the roadmap before you rely on it for call flows, since function call visualisation is listed there as future work rather than a shipped feature.

Frequently asked questions

Official sources

1. 3rd/tsdiagram on GitHub
2. Issues
3. License: GPL-3.0
4. Project website
5. README