structurizr-renderer

The structurizr-renderer is a Java library and CLI tool to render Structurizr workspaces providing different rendering algorithms.

Usage

Usage from the command line

You can download the latest release from GitHub. Once downloaded, run it using java -jar. This requires at least JDK 17.

Following is the configuration as requested. This output is provided by PicoCLI and also shown when running the CLI without the expected arguments.

Missing required options: '--workspace=<workspaceDslPath>', '--outputDir=<outputDir>', '--viewKey=<viewKey>'
Usage: render [-e=<plantumlLayoutEngine>] [-j=<workspaceJsonPath>]
              -o=<outputDir> [-p=<playwrightWsEndpoint>] [-r=<renderer>] -v=<viewKey> -w=<workspaceDslPath>
Renders the views of a given workspace to SVG files
  -e, --plantumlLayoutEngine=<plantumlLayoutEngine>
                            The layout engine to use for the PLANTUML-C4
                              renderer. Defaults to GraphViz.
  -j, --workspaceJson=<workspaceJsonPath>
                            Path to the manual layout JSON file.
  -o, --outputDir=<outputDir>
                            Path to write the output to.
  -p, --playwrightWsEndpoint
                            The Playwright URI to connect to if a running
                              installation should be used.
  -r, --renderer=<renderer> The renderer to use. Defaults to STRUCTURIZR.
  -v, --viewKey=<viewKey>   The key of the view to render.
  -w, --workspace=<workspaceDslPath>
                            Path to the workspace DSL file.

Usage as a Java library

To run the renderer from Java, you can use the WorkspaceRenderer#render convenience method which will set up everything as required based on the provided configuration.

Rendering Algorithms

Following are the supported values for the --renderer parameter:

• MERMAID

• PLANTUML-C4

• STRUCTURIZR (Default)

Mermaid

Structurizr workspaces can be rendered using Mermaid. For that, the workspace is converted to `.mmd`files and then rendered by mermaid-js. Please refer to the Structurizr Documentation to learn what parts of a workspace are supported. Per defined view in the DSL, a diagram will be generated.

NOTE

Additionally to the rendered SVG, the .mmd file is exported to the same path for further processing.

NOTE

If Mermaid is used, a Mermaid installation is required and mmdc needs to be on the path.

PlantUML-C4

Structurizr workspaces can be rendered using C4-PlantUML. For that, the workspace is converted to C4-PlantUML and afterwards rendered using the PlantUML library. Please refer to the Structurizr Documentation to learn what parts of a workspace are supported. Per defined view in the DSL file, a diagram will be generated.

NOTE

Additionally to the rendered SVG, the .puml file is exported to the same path for further processing.

Additionally, there is support to configure which layout engine should be used. This can be chosen by specifying plantumlLayoutEngine to one of the following values:

• ELK

• GRAPHVIZ (Default)

• SMETANA

  NOTE

  If GraphViz is used, a GraphViz installation is required and dot needs to be on the path.

Structurizr

This renderer refers to the rendering that is used natively inside the UI application Structurizr Lite und Structurizr Playground. To make this work, Playwright is used under the hood with a minimal JavaScript setup of the browser-based rendering. With that, the diagrams will look like designed including support for manual layout.

By default, Playwright will look for an existing Chromium installation in the documented locations. If none is found, Chromium will be downloaded.

NOTE

If this is run behind a proxy, the HTTPS_PROXY env variable needs to be configured.

By specifying the --playwrightWsEndpoint parameter, the default behavior can be omitted and a connection is created to a running Chromium instance. For example, if Chromium was started using docker run -p 3000:3000 ghcr.io/browserless/chromium, the value would be `ws://localhost:3000/playwright/chromium