ngrx-graph

CLI to scan an Angular NgRx codebase and produce a structure JSON and DOT/SVG graphs.

Motivation:

Working with a very big NgRx store in an angular application will lead to having lots of actions/effects and lots of interactions between components/actions/reducers. It gets very tedious very quickly to follow an action from the start to the end, and it is very easy to miss an action dispatched in an effect somewhere along the chain of actions.

This package tries to collect all actions/components/reducers participating in a particular flow and generate dot files for that flow, with the idea that following a graph visually is easier than following effects and actions in code.

It is also possible to see the whole net with all actions/components/reducers, but that is more important is to follow a particular action from the start to the end (the optional argument)

Notes

• The CLI always writes the JSON payload to the file specified by --out (default: ngrx-graph.json).
• DOT and SVG files are written under the directory specified by --dir.
• DOT files are generated only when --dot or --svg is passed. Use --json to re-generate the JSON first; combine with --dot/--svg to continue generating DOT/SVG.
• Default concurrency: the CLI computes a sensible default of max(1, CPU_COUNT - 2) (number of CPUs minus two, minimum 1). This keeps CPU available for other tasks while enabling parallel parsing. Override with -c/--concurrency <n>.
• Prefer viz.js for SVG: pass --viz to prefer using viz.js (a WASM/JS renderer) for SVG generation. With --viz the CLI tries viz.js first and falls back to Graphviz dot if viz.js fails. Without --viz the CLI prefers the native dot executable and uses viz.js only as a fallback.

Install globally (optional):

npm install -g ngrx-graph
# or run with npx: npx ngrx-graph ...

Quick examples

• Generate the structure JSON (always written to --out, default ngrx-graph.json):

ngrx-graph -d ./src --out ./out
# writes: ./out/ngrx-graph.json

• Generate an action-focused DOT (and optional SVG):

ngrx-graph "MyAction" -d ./src --out ./out --dot --svg

• Generate a single aggregated DOT for the whole project (writes all.dot):

ngrx-graph -a -d ./src --out ./out --dot --svg

• Re-generate the JSON only (stop after JSON):

ngrx-graph -d ./src --out ./out --json

ngrx-graph -d ./src --out ./out

Note: caching is enabled by default. To force a re-scan and regenerate the JSON payload, pass -f or --force.

Common flags: -d/--dir, -o/--out, -a/--all, -s/--svg, -j/--json, -v/--verbose, -c/--concurrency, -f/--force

| | | | --------------- | -------------------------------------------- | | Component | | | Action | | | Action in focus | | | Nested Action | | | Reducer | |

Case 1:

Input:

Input files (see the canonical example sources under docs/examples/case1/src):

• Actions: docs/examples/case1/src/case1.actions.ts
• Component: docs/examples/case1/src/case1.component.ts
• Effects: docs/examples/case1/src/case1.effects.ts
• Reducer: docs/examples/case1/src/case1.reducer.ts

Output:

npx ngrx-graph -j

• ngrx-graph.json

npx ngrx-graph action1

• dotFile
• graph:
  

npx ngrx-graph action3

• dotFile
• graph:
  

Case 2 (nested actions):

Input:

Input files (see the canonical example sources under docs/examples/case2/src):

• Actions: docs/examples/case2/src/case2.actions.ts
• Component: docs/examples/case2/src/case2.component.ts
• Effects: docs/examples/case2/src/case2.effects.ts
• Reducer: docs/examples/case2/src/case2.reducer.ts

Output:

npx ngrx-graph -j

• ngrx-graph.json

npx ngrx-graph action1

• dotFile
• graph:
  

npx ngrx-graph action3

• dotFile
• graph:
  

Case 3 (reachability filtering):

Input:

Input files (see the canonical example sources under docs/examples/case3/src):

• Actions: docs/examples/case3/src/case3.actions.ts
• Component: docs/examples/case3/src/case3.component.ts
• Effects: docs/examples/case3/src/case3.effects.ts
• Reducer: docs/examples/case3/src/case3.reducer.ts

Output:

npx ngrx-graph -j

• ngrx-graph.json

npx ngrx-graph action1

• dotFile
• graph:
  

npx ngrx-graph action3

• dotFile
• graph:
  

npx ngrx-graph action2

• dotFile
• graph:
  

Case 4 (aliases and re-exports):

Input:

Input files (see the canonical example sources under docs/examples/case4/src):

• Actions: docs/examples/case4/src/case4.actions.ts
• Barrel / re-exports: docs/examples/case4/src/index.ts
• Component: docs/examples/case4/src/case4.component.ts
• Effects: docs/examples/case4/src/case4.effects.ts
• Reducer: docs/examples/case4/src/case4.reducer.ts

Output:

npx ngrx-graph -j

• ngrx-graph.json

Generate a combined graph for the whole example:

npx ngrx-graph -a -d docs/examples/case4/src -o docs/examples/case4/out

• combined DOT
• combined graph:
  

Generate a graph for a specific action (produces per-action DOT only when an action is supplied):

npx ngrx-graph actionA -d docs/examples/case4/src -o docs/examples/case4/out

• dotFile
• graph:
  

$ npm install -g ngrx-graph
$ ngrx-graph COMMAND
running command...
$ ngrx-graph (--version)
ngrx-graph/1.0.2 linux-x64 node-v16.20.2
$ ngrx-graph --help [COMMAND]
USAGE
  $ ngrx-graph COMMAND
...

• ngrx-graph help [COMMAND]

ngrx-graph help [COMMAND]

Display help for ngrx-graph.

USAGE
  $ ngrx-graph help [COMMAND...] [-n]

ARGUMENTS
  [COMMAND...]  Command to show help for.

FLAGS
  -n, --nested-commands  Include all nested commands in the output.

DESCRIPTION
  Display help for ngrx-graph.

See code: @oclif/plugin-help

• change version in package.json
• run npm run version
• run ./scripts/test-npm-pack.sh to check that package would work if published.
• commit and push/merge to main
• draft and release a release on github

Status:

This project is still young and it encourages collaborations. If you have an ideas/questions/fixes please do not hesitate to open an issue or provide a pull request.

I work on this on my own free time only.