cdk-dia turns a synthesized CDK stack into a Graphviz picture you can paste anywhere

cdk-dia reads a synthesized CDK app and emits dot source

The tool is described in one line in its own README: cdk-dia diagrams your CDK provisioned infrastructure using the Graphviz dot language. The subject is therefore the AWS CDK, and the output format is a picture rather than a description.

The mechanism has three stages. First you synthesize the CDK application, which writes the construct tree to the cloud assembly directory. Second, cdk-dia traverses that tree and decides what to show. Third, it writes a Graphviz model and renders it to a PNG. The package manifest makes the middle and last stages visible: ts-graphviz is a direct dependency, which is a Graphviz model builder for TypeScript, so the tool constructs a graph object in memory and serializes it rather than emitting raw dot text by hand.

The dependency list also explains some behaviour you would otherwise find puzzling. hasbin is present, which is the package used to test whether a binary exists on the system, matching the README instruction to make sure the Graphviz dot binary is available in your PATH. terminal-link is used to print a clickable path to the generated file, sanitize-filename to keep the output name safe, and yargs to parse the command line flags that the README documents for stack selection.

The published package exposes a bin entry named cdk-dia pointing at dist/bin/cli.js, and ships the dist folder plus an icons directory, so the icon set that appears in the diagram travels with the package.

The diagram comes from the cloud assembly, not from your source code

This is the part that surprises people who expect a static site generator for CDK. cdk-dia does not read your TypeScript and does not re-evaluate your constructs. It consumes the result of a synthesis, the same output the CDK CLI produces for deployment.

That has a direct consequence for how you use it. The diagram reflects what was synthesized, including the resolved configuration for the environment you synthesized, so a diagram generated from a synth run with different context can differ from one generated from another. It also means the tool cannot work on a stack you have not synthesized, and that a stale cloud assembly will produce a stale picture.

The dependency on aws-cdk-lib and constructs in the package manifest makes the coupling explicit. cdk-dia is bound to the AWS CDK construct model, with constructs at version 10.8.1 and aws-cdk-lib at 2.271.0 or newer, so it understands the tree shape that the CDK produces and can reason about construct scopes and identifiers.

A second consequence is that the tool is about the topology of the application rather than the state of a live account. Nothing in the README describes querying deployed resources, so a diagram is a picture of intent at synthesis time, not a drift report.

First diagram: install the package, install Graphviz, synthesize, render

The getting started section for TypeScript and JavaScript projects gives four steps. The package goes into the CDK project as a dependency:

npm install cdk-dia

Graphviz has to be installed separately, and the README suggests brew on macOS:

brew install graphviz

For other environments the README links to the Graphviz download documentation and repeats the same requirement, that the dot binary be available in your PATH. Then you synthesize the application:

cdk synth

And finally you render the picture:

npx cdk-dia

You should end up with a PNG of your stacks and their resources, generated from the synth output rather than typed by hand.

Projects written in another CDK language follow the same sequence with a global install instead, since the CLI is run outside the project:

npm install cdk-dia -g

followed by cdk synth and then the cdk-dia command. That global path is also where the first limitation of the customization features shows up, which the next sections come back to.

Level 2 constructs collapse by default so the picture stays readable

A raw CDK construct tree is verbose. Every L2 construct carries a number of L1 resources underneath it, and drawing all of them turns a diagram into a wall. cdk-dia handles this by collapsing any CDK Level 2 construct automatically, which the README describes as a way to create a diagram containing the most important details.

The tool's answer to that is the decorator pattern. You implement the CDK IInspectable interface on your construct and hand the inspector to cdk-dia's decorator, and the diagram then shows the construct in full instead of collapsed. The documented pattern looks like this:

import { CdkDia, CdkDiaDecorator } from "cdk-dia"
import * as cdk from "aws-cdk-lib"

export class InternalBucket extends s3.Bucket implements cdk.IInspectable {
    constructor(scope: Construct, id: string) {
        super(scope, id);
    }

    inspect(inspector: cdk.TreeInspector): void {
        const decorator = new CdkDiaDecorator().ignore()
        CdkDia.decorate(inspector, decorator)
    }
}

The repository carries two worked examples for this, examples/decoration-example and examples/experimental-decorator-example, and the README shows before and after images of the same three tier stack.

Two constraints are stated. Customization and decorators are only supported in TypeScript and JavaScript CDK projects. And because the decorator class has to come from your own dependency tree, a global install with npm i -g will not let you use CdkDiaDecorator, which means if you want to customise a diagram you have to add cdk-dia as a project dependency.

Ignoring a resource removes it and everything under it

The inverse of collapsing is removing. The ignore option excludes specific resources from the diagram, and the README describes the purpose as getting rid of constructs that add noise without giving architectural insight.

There is an experimental class decorator for it, applied to a construct class:

import { DiagramOptions } from "cdk-dia"

@DiagramOptions({ ignore: true })
export class InternalBucket extends s3.Bucket {
    constructor(scope: Construct, id: string) {
        super(scope, id);
    }
}

The other route is the CdkDiaDecorator with the ignore() call shown in the previous section, used inside an inspect method.

The behaviour that matters for planning is documented in one sentence: when a resource is ignored, it and all its children are removed from the diagram entirely. That is a subtree deletion rather than a visual dimming, so ignoring a parent construct does not merely hide the parent node, it removes the entire branch beneath it.

The decorator form is marked experimental, which is worth noting since it is the mechanism that lets you keep an internal bucket out of a diagram that is meant to describe the architecture to an outside reader.

Stack selection with --include and --exclude, by name or by path

Real CDK applications have many stacks, and a diagram of all of them at once is often unreadable. The CLI arguments section covers the selection.

npx cdk-dia --include stackOne stackFour

That restricts the output to the named stacks. The README also shows selection by path, which is how you reach a stack nested inside a pipeline structure:

npx cdk-dia --include pipelinestack/prod/database

The inverse excludes a stack instead:

npx cdk-dia --exclude stackOne

And the help flag lists everything else:

npx cdk-dia --help

The path form is the one to internalise. CDK applications built with pipelines have stacks inside stacks, and a name that looks unique in your codebase can exist under several parents, so selecting by path is the reliable way to say which copy you mean.

There is also an experimental interactive output, generated with the cytoscape-html rendering mode:

npx cdk-dia --rendering cytoscape-html

The repository has a cytoscape-rendering directory for it. The README labels that mode experimental, so treat it as a preview rather than something to publish to stakeholders without checking the output yourself.

Version 0.12.4, MIT licence, and a dependency tree that carries aws-cdk-lib

The published version is 0.12.4, and the licence is MIT, with the text in the LICENSE file at the repository root. MIT is permissive and asks no reciprocal obligations if you embed the tool in your own build pipeline.

On activity, the last push was on 2026-09-27. The release notes for that version describe dependency bumps and strict TS mode, and the two earlier releases, 0.12.3 and 0.12.2 from January 2026, were both framed as patches for vulnerable dependencies. That pattern tells you what the recent work has been: keeping the dependency tree current and the TypeScript compilation strict, rather than adding diagram features.

The dependency tree is heavy for a small tool, and that is the real upgrade cost. aws-cdk-lib alone is a large package, and it arrives in your project alongside the CDK application you already depend on. The rest of the runtime list is small and conventional, chalk for terminal output, fs-extra, lodash, word-wrap, values.js, and the Graphviz model builder ts-graphviz.

For the project itself, the repository layout shows how it verifies itself. The test script runs tsc and then jest, with jest-file-snapshot and jest-specific-snapshot among the dev dependencies and a snapshots/ directory in the tree, so diagram output is checked as a snapshot. There is a smoke-test/ directory, an examples/ directory with two decorator examples, and a prepublishOnly script that runs ./scripts/npm-prepare.sh before publishing, which is where the dist folder and icons are assembled.

Editorial conclusion

Adopt cdk-dia if your AWS CDK application is large enough that reading the construct tree in a terminal is no longer practical, and if you can accept that its own diagram output is the deliverable rather than a live view of a deployed stack. Do not adopt it for other CDK languages if you need decorators, since customization is only supported in TypeScript and JavaScript projects, and do not rely on the HTML output for anything critical because the README labels the cytoscape-html rendering experimental. Verify three things on your first run: that the dot binary is on your PATH, that the cdk synth output directory the CLI reads matches the stacks you expect, and that the L2 collapsing behaviour is acceptable for the diagram your reviewers will read.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. pistazie/cdk-dia on GitHub
4. README
5. Releases