Circular Dependency Detection — flags cycles in module imports and provider dependencies
Oversized Module Detection — flags modules owning more than 10 components
Unused Provider Detection — flags providers not injected or owned

Insights appear as a count in the status bar. Click to toggle the Insights panel, which shows severity-grouped cards with affected node links.

Quick Start

Prerequisites

Node.js 20+
pnpm

Installation

# Install globally
npm install -g nestlens-cli

# Or use npx (no install required)
npx nestlens-cli ./my-project

From source

git clone https://github.com/rostislaw9/nestlens.git
cd nestlens
pnpm install
pnpm build

Run

# If installed globally
nestlens-cli ./examples/basic-project

# If using npx
npx nestlens-cli ./examples/basic-project

# From source
pnpm nestlens ./examples/basic-project

The browser opens automatically with the architecture graph.

To skip browser auto-open:

nestlens-cli ./examples/basic-project --no-browser
# or
npx nestlens-cli ./examples/basic-project --no-browser

Run Against Your Own NestJS Project

npx nestlens-cli /path/to/your/nestjs-project

How It Works

NestJS Project
      ↓
Scanner (file discovery + tsconfig loading)
      ↓
Analyzer (module, controller, provider detectors)
      ↓
Graph Model (nodes, edges, metadata)
      ↓
GraphJSON Serialization
      ↓
Local HTTP Server (/api/graph + static assets)
      ↓
React Application (SVG graph + inspector)

NestLens uses the TypeScript Compiler API for static analysis. No regex parsing. No runtime execution. Your code stays on your machine.

Project Structure

nestlens/
├── apps/
│   └── web/              # React + SVG visualization
├── packages/
│   ├── cli/              # CLI entry point
│   ├── scanner/          # Project file discovery
│   ├── graph/            # Graph model + serialization
│   ├── analyzer/         # NestJS detectors
│   └── server/           # Local HTTP server
├── examples/
│   └── basic-project/    # Example NestJS project
├── docs/                 # 18 documentation files
└── package.json

Supported NestJS Features

Current

Modules (@Module())
Controllers (@Controller())
Providers (@Injectable() or NestJS interface implementation)
Routes (HTTP endpoints as graph nodes)
Module imports
Module ownership (controllers, providers, middleware)
Module exports (exported providers)
Constructor dependency injection
Controller-to-route handles edges
HTTP route detection
Object literal providers (useClass, useFactory, useExisting)
Middleware detection from configure() method
APP_* token providers (global interceptors, pipes, guards)
Global search (Cmd+K) with fuzzy matching
Architecture insights (circular deps, oversized modules, unused providers)
Graph legend with node types and edge types
Mini map with viewport indicator
Draggable nodes
Lucide React icons

Planned

Route explorer table
Prisma / TypeORM / GraphQL / BullMQ / CQRS support

Development

pnpm install
pnpm lint
pnpm test
pnpm build

Run CLI during development:

npx tsx packages/cli/src/index.ts ./examples/basic-project

Develop web UI independently with hot reload:

# Terminal 1: start CLI server with graph data
pnpm nestlens ./examples/basic-project --no-browser

# Terminal 2: start Vite dev server with HMR
pnpm --filter web dev

Open http://localhost:5173. Vite proxies /api/graph to the CLI server on port 3000. Changes to apps/web/src/ are reflected instantly.