dependency-cruiser-json-viewer

Interactive browser viewer for dependency-cruiser JSON cruise results — explore file trees, dependency graphs, circular dependencies, and module relations.

Built with React, MUI, @xyflow/react, elkjs, @mr_mint/elkjs-libavoid, and zustand.

Demo

Try it live: https://narapov.github.io/dependency-cruiser-json-viewer/

The demo loads the dependency-cruiser cruise result of this project by default. To explore your own codebase, press F1 to open the command palette and choose Cruise Result: Load JSON, or drag and drop a local .json file onto the window.

Motivation

dependency-cruiser is an excellent tool for understanding how a codebase is wired together. Its built-in output formatters, however, fall short when you need to explore architecture interactively — zooming in and out across hierarchy levels, following imports folder by folder, and comparing different views of the same graph.

This is particularly relevant after AI-assisted refactoring, when you need to verify imports and the layered structure on the fly, rather than interrupting your workflow to tweak the configuration and regenerate svg for every session.

The usual workflow meant constantly tweaking filters, collapsePattern, and exclude rules in .dependency-cruiser.js, then waiting for huge SVG files to regenerate. This viewer was born from that pain: load the JSON cruise result once, then navigate the dependency graph in the browser — expand folders, highlight edges, filter modules, and inspect relations without leaving the interactive UI.

Features

• File tree — browse modules and folders; checkbox selection to dynamically show or hide parts of the codebase in the graph; expand/collapse, context menu.
• Dependency graph — interactive graph with folder/file nodes and colored edges (incoming/outgoing/circular).
• Drag-and-drop layout — rearrange graph nodes by dragging; custom positions persist when you expand or collapse folders. Turn off Auto layout only in the graph legend to enable dragging; use Auto layout in a folder's context menu to reset layout.
• Edges type — choose how dependency edges are drawn (Bezier, Straight, Simple orthogonal, or Libavoid orthogonal — higher-quality routes that avoid nodes and reduce overlaps, at the cost of slower routing) via the control next to Auto layout only, or the command palette (Graph: Select Edges Type). The choice is saved with the workspace.
• Edge highlighting — highlight dependencies via the edge context menu, the dependencies panel, or the command palette (Highlights: Highlight Edge…: pick source → target → color, including folder targets that cover all deps under that path); highlights are tied to the underlying import relation and persist when you expand or collapse nodes. Open the Highlights sidebar to browse connections by color, jump to one in the graph, or remove a single highlight, a whole color group, or all highlights.
• Hide others — from a graph node context menu, keep only that file (or already-selected modules under a folder) in the selection so the rest of the graph is hidden.
• Dependencies panel — inspect dependencies and dependents for a path in the right panel.
• Rules panel — browse the cruise ruleSetUsed with violation counts; fuzzy-filter by rule name; expand a rule to see violations and click one to select/navigate to the offending modules in the tree and graph; use Show violations only on a rule to keep only its violation modules in the graph.
• Applicable rules panel — see which cruise rules apply to a path and jump to their violations.
• Rule violations filter — command palette Selection: Show Rule Violations… opens a picker of rules that have violations; confirm to keep only modules involved in the selected rules.
• Circular dependencies — open the Circular panel to browse distinct cycles; expand a cycle for member paths, or show the cycle in the graph without unrelated modules.
• Drill-down navigation — expanding a folder in the tree rebuilds the graph for that scope, so you can walk from high-level architecture down to individual files.
• Load cruise JSON — load a cruise result via the command palette (Cruise Result: Load JSON) or by dragging a .json file onto the window (disabled while watch mode is active).
• JSON preview — interactive raw JSON (expand/collapse) for the full cruise result via the command palette (Cruise Result: View JSON); for a module or folder from the file tree / graph node context menu, dependencies panel, status bar, or command palette (Active Item: View Module JSON); and for a rule from the Rules or Applicable rules panels.
• Quick search & commands — fuzzy file search (Cmd/Ctrl+P) and command palette (F1); see Keyboard shortcuts below.
• DOT export — export the current graph layout as a Graphviz .dot file via the command palette (Graph: Export DOT), or open it in Graphviz Online (Graph: View DOT Online); render locally with neato -n2 -Tsvg graph.dot or dot -Knop2 -Tsvg graph.dot.
• Workspace save/load — save selection, expansion, ignore patterns, edge highlights, folder colors, edges type, and layout into the cruise JSON under dependency-cruiser-json-viewer (Workspace: Save). Both Cruise Result: Load JSON (when the file has workspace settings) and Workspace: Load Settings always clear the current view and replace selection, expansion, the dependencies panel path, ignore patterns, edge highlights, folder colors, edges type, and layout from the file, dropping entries that no longer match the relevant cruise data (e.g. references to files or dependencies that no longer exist). With the CLI, pass --workspace-settings <path> to apply a saved workspace once on startup (same as Workspace: Load Settings) so you do not have to load it manually every time.
• Ignore patterns — glob patterns to exclude modules from tree and graph.
• Watch mode — reload the cruise JSON when the file changes on disk and keep the current workspace (see Watch mode). A --workspace-settings file is applied only on startup and is not watched.

Keyboard shortcuts

| Shortcut | Action | | ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | | F1 | Open the command palette (expand/collapse, theme, language, ignore patterns, load JSON, etc.). | | Cmd+P / Ctrl+P | Open quick file search; type to fuzzy-find files/folders, Enter to navigate (expands ancestors, focuses node in tree and graph). | | Cmd+B / Ctrl+B | Toggle sidebar. | | Cmd+Shift+E / Ctrl+Shift+E | Show File Tree. | | Cmd+Shift+M / Ctrl+Shift+M | Show Rules. | | Cmd+Shift+C / Ctrl+Shift+C | Show Circular. | | Cmd+Shift+H / Ctrl+Shift+H | Show Highlights. |

Typing > at the start of the quick-search query switches to command mode (same as F1).

Usage

Install as a dev dependency and serve your dependency-cruiser JSON output in the browser:

npm install -D dependency-cruiser-json-viewer
npx depcruise src -T json -f cruise-result.json
npx dependency-cruiser-json-viewer cruise-result.json
# dependency-cruiser-json-viewer is running at http://localhost:7347

Optional flags:

npx dependency-cruiser-json-viewer cruise-result.json --port 9000
# dependency-cruiser-json-viewer is running at http://localhost:9000

npx dependency-cruiser-json-viewer cruise-result.json --watch
# or -w — reload the UI when the cruise JSON file changes

npx dependency-cruiser-json-viewer cruise-result.json --workspace-settings workspace.json
# apply a previously saved workspace once on startup (same as Workspace: Load Settings)

The CLI serves the built viewer from dist and streams your JSON file at /cruise-result.json without copying it.

Use --workspace-settings when you already have a saved workspace and do not want to load it manually every time. The file is applied once at startup using the same replace semantics as Workspace: Load Settings; it is not watched even with --watch. Manual Workspace: Load Settings remains available afterward.

Watch mode

When watch mode is on, the viewer reloads /cruise-result.json whenever that file changes on disk and re-applies the current workspace (selection, ignore patterns, edge highlights, folder colors, and layout). Manual Cruise Result: Load JSON and drag-and-drop load are disabled while watch is active. If you started with --workspace-settings, that file is still not watched — only the cruise JSON is.

CLI

npx dependency-cruiser-json-viewer cruise-result.json --watch
# or
npx dependency-cruiser-json-viewer cruise-result.json -w

Local development (this repository)

1. Set CRUISE_WATCH=true in .env.development (only the literal value true enables watch).
2. Refresh the sample cruise JSON if needed: npm run depcruise:json-for-cli (or npm run watch-src-and-regenerate-cruise-result-for-cli to regenerate it when src/ changes).
3. Start the Vite dev server: npm run dev.

With CRUISE_WATCH=false (the default in .env.development) or any value other than true, npm run dev runs without cruise watch — you can load a JSON file from the command palette as usual.

Architecture

See docs/architecture.md for layers, import rules, and project conventions. Graph algorithms: docs/algorithms/ (buildGraph, libavoid).

Scripts

| Command | Description | | ------------------------------------- | -------------------------------------------------------------------------------------------------------------------- | | npm run dev | Start Vite dev server (serves test-data/cruise-result.json; cruise watch via CRUISE_WATCH in .env.development) | | npm run build | Type-check (tsc) and build for production | | npm run build:gh-pages | Production build with GitHub Pages base path + embed cruise result in dist/ | | npm run preview | Preview production build | | npm run test | Run Vitest suite | | npm run lint | Run ESLint | | npm run lint:fix | Run ESLint with autofix | | npm run format | Format all files with Prettier | | npm run format:check | Check formatting (CI-friendly) | | npm run depcruise | Run dependency-cruiser on src (validate layer rules) | | npm run depcruise:json | Export cruise result to ./cruise-result.json | | npm run depcruise:json-for-cli | Export cruise result (src + invalid_samples, sample config) to test-data/cruise-result.json | | npm run depcruise:json-for-gh-pages | Export cruise result (src + invalid_samples, sample config) to dist/cruise-result.json | | npm run cli:verify | Build, refresh test-data/cruise-result.json, start CLI server |

License

MIT