GitHub - Fcmam5/nx-mermaid-grapher: Create Mermaid graphs for NX dependencies

Tip

Using this from an AI coding agent? nx-mermaid-grapher is designed to be a token-cheap window into an Nx workspace. Instead of feeding the model the full nx graph JSON (often tens to hundreds of kB), have the agent shell out to this CLI with --format edges or --format json to get a compact view of the dependency topology. The default mermaid output is great for showing the result back to the user — it renders natively in GitHub/GitLab markdown and in VS Code-based editors (Cursor, Windsurf, VSCodium, ...) with a Mermaid preview extension. See Output formats below for the short version, or the Usage guide for a full walkthrough of every format with realistic examples.

npm i -g nx-mermaid-grapher


# or using npx
npx nx-mermaid-grapher -f file.json

Usage: nx-mermaid-grapher (-f <path> | --stdin) [-o <format>] [-e <lib>]... [-p <lib>]... [-t] [--raw]

Options:
  -f, --file <path>      NX graph output file. Pass `-` to read from stdin
                         (see: https://nx.dev/packages/nx/documents/dep-graph#file)
      --stdin            Read the graph JSON from stdin (alias for `-f -`)
  -o, --format <format>  Output format (default: mermaid).
                         One of: mermaid, edges, json, dot, stats
  -e, --exclude <lib>    Exclude a library (repeatable)
  -p, --projects <lib>   Include only these libraries (repeatable).
                         Useful for rendering affected-project subgraphs.
  -t, --transitive       When used with --projects, include the full transitive
                         closure in both directions. Forward traversal starts
                         from root seeds only to avoid unrelated siblings.
      --raw              Emit raw Mermaid (no ```mermaid markdown fence)
  -h, --help             Show help
  -V, --version          Show version

npx nx-mermaid-grapher -f tests/mocks/ddd-example.graph.json

npx nx-mermaid-grapher -f tests/mocks/ddd-example.graph.json -e lending-infrastructure -e lending-ui-rest

nx graph --file=/dev/stdout | npx nx-mermaid-grapher --stdin -o stats
# (or the idiomatic form: `... | npx nx-mermaid-grapher -f -`)

# Raw Mermaid body (no markdown fence) — handy when piping into a templater.
npx nx-mermaid-grapher -f graph.json --raw

# Plain edge list — the cheapest format for an AI agent to reason about.
npx nx-mermaid-grapher -f graph.json -o edges

# Compact JSON.
npx nx-mermaid-grapher -f graph.json -o json

# Graphviz, rendered to SVG.
npx nx-mermaid-grapher -f graph.json -o dot | dot -Tsvg > graph.svg

# One-shot summary (counts, roots/leaves, cycle check, hottest projects).
npx nx-mermaid-grapher -f graph.json -o stats

Tip

For AI agents and tool authors. Pick the format that matches what the model actually needs:

• One-shot orientation ("how big is this workspace?", "any cycles?", "what are the load-bearing libs?") → use --format stats. A single block of text covers counts, roots/leaves, cycle detection, max depth, and per-project fan-in/fan-out.
• Reasoning about structure ("which libs depend on auth?", "show me the path from library to shared-domain") → use --format edges or --format json. Both are much smaller than the raw Nx graph and have predictable shapes the model can parse without hallucinating fields.
• Showing the user the topology in a chat reply, a PR comment, or a markdown report → use the default mermaid output. It renders natively on GitHub/GitLab and in VS Code-based editors (Cursor, Windsurf, VSCodium, …) with a Mermaid preview extension.
• Producing an image for a doc site or a Slack message → use --format dot | dot -Tsvg (or -Tpng).

Combine with -e <lib> to drop noisy projects from the rendered subset before passing it to the model — fewer tokens, less distraction.

import { DiGraph, NXGraphFileLoader, NxMermaidGrapher } from 'nx-mermaid-grapher';

const loader = new NXGraphFileLoader();
const diGraph = new DiGraph();
const core = new NxMermaidGrapher(loader, diGraph);

core.init('path/to/file');

const logMerMaidInMd = (str: string) => `\`\`\`mermaid\n${str}\`\`\``;

console.log(logMerMaidInMd(core.getGraphSnippet()));

import { IGraph } from "nx-mermaid-grapher/dist/data-structures/graph.ds.interface";

class SomeGraph implements IGraph<MyType> {
    addNode(nodeVal: MyType): void {
        throw new Error("Method not implemented.");
    }
    addEdge(source: MyType, destination: MyType): void {
        throw new Error("Method not implemented.");
    }
    getGraph(): { [key: string]: MyType[]; } {
        throw new Error("Method not implemented.");
    }
}

import {  NXGraphFileLoader, NxMermaidGrapher } from 'nx-mermaid-grapher';

const loader = new NXGraphFileLoader();
const myGraph = new SomeGraph();
const core = new NxMermaidGrapher(loader, myGraph);

# 1. Dump the *full* workspace graph (once).
npx nx graph --file=graph.json

# 2. Get the names of affected projects and render with impact context.
#    -t includes the full transitive closure around the affected set.
#    Requires `jq`; adjust --base to your target branch.
npx nx-mermaid-grapher -f graph.json -t \
  $(npx nx show projects --affected --json --base=origin/develop \
    | jq -r '.[] | "-p " + .')

name: Affected dep graph

on:
  pull_request:
    branches: [develop, main]

permissions:
  contents: read
  pull-requests: write

jobs:
  graph:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          # Required so `--base=origin/${{ github.base_ref }}` has history.
          fetch-depth: 0

      - uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: npm

      - run: npm ci

      - name: Generate affected Mermaid graph
        run: |
          # 1. Dump the full workspace graph.
          npx nx graph --file=graph.json

          # 2. Get affected project names and build -p flags.
          PROJECTS=$(npx nx show projects --affected --json --base=origin/${{ github.base_ref }} | jq -r '.[] | "-p " + .' | xargs)

          # 3. Render the subgraph with impact context.
          {
            echo '## Affected dependency graph'
            echo
            npx nx-mermaid-grapher -f graph.json -t $PROJECTS
          } > graph.md

      - name: Comment on the PR
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: gh pr comment "${{ github.event.pull_request.number }}" --body-file graph.md