fsd-inspector

Visual inspector for Feature-Sliced Design projects: an interactive dependency graph of your layers and slices, powered by React Flow, with FSD rule violations highlighted right on the edges.

• 🔍 Zero-config analysis — auto-detects the FSD root (src/ with app, pages, widgets, features, entities, shared), attributes every file to a slice, traces import/export from/import()/require between them.
• 🧭 Alias-aware — reads paths/baseUrl from your tsconfig.json/jsconfig.json (with extends), plus the usual @/, ~/ conventions.
• 🚨 Violation detection — upward imports and same-layer cross-imports are errors; public API bypasses (deep imports past a slice's index) are warnings.
• 🗺 Interactive viewer — layers as rows, slices as nodes, violations as red/amber edges. Click a node to focus its links and violations.
• 🤖 CI-friendly — --json output and --fail-on-violations exit code.

Quick start

Run it in the root of any FSD project — no install needed:

npx fsd-inspector

This analyzes the project, starts a local server and opens the interactive graph in your browser.

CLI

fsd-inspector [dir] [options]

--json                 Print the dependency graph as JSON and exit
--out <file>           Write a standalone HTML report and exit
--port <n>             Port for the local viewer server (default 4573)
--no-open              Don't open the browser automatically
--fsd-root <dir>       Directory with the layer folders (default: auto-detect)
--fail-on-violations   Exit with code 1 when FSD errors are found (for CI)

Examples:

# self-contained HTML report you can attach to a PR
npx fsd-inspector --out fsd-report.html

# gate a pipeline on architecture violations
npx fsd-inspector --json --fail-on-violations > graph.json

Node API

import { analyze } from 'fsd-inspector';

const graph = analyze('./my-app');

graph.nodes; // slices: { id: 'features/auth', layer, slice, segments, files, path }
graph.edges; // aggregated deps: { source, target, imports[], violations[] }
graph.violations; // flat list: upward-import | cross-import | public-api-bypass

analyze(root, options) accepts:

| Option | Description | | ------------ | ----------------------------------------------------------------------------- | | fsdRoot | Directory with the layer folders, relative to root (auto-detected) | | extensions | File extensions to scan (default: ts/tsx/js/jsx/mjs/cjs/vue/svelte) | | ignore | Directory names to skip (default: node_modules, dist, tests, …) | | aliases | Extra alias → dir mappings on top of the tsconfig ones, e.g. { '@': 'src' } |

React component

Embed the graph in your own devtools or docs. react, react-dom and @xyflow/react are optional peer dependencies — install them alongside:

pnpm add fsd-inspector @xyflow/react

import { FsdInspector } from 'fsd-inspector/react';
import '@xyflow/react/dist/style.css';

// `graph` is the JSON produced by analyze() or `fsd-inspector --json`
export function ArchitecturePage({ graph }) {
  return (
    <div style={{ height: '100vh' }}>
      <FsdInspector graph={graph} onSelect={(node) => console.log(node?.id)} />
    </div>
  );
}

There is also a lower-level toFlow(graph) helper that converts an analyzer graph into React Flow nodes/edges with the layered layout, if you want to build a fully custom scene.

What counts as a violation

| Kind | Severity | Rule | | ------------------- | -------- | ------------------------------------------------------------------------ | | upward-import | error | A layer imports from a layer above it (e.g. entities → features) | | cross-import | error | Two slices of the same layer import each other | | public-api-bypass | warning | Deep import past a slice's index (segment indexes are OK for shared) |

License

MIT