NestLens

Explore the architecture of your NestJS applications visually

NestLens is an offline-first developer tool that analyzes NestJS projects and creates an interactive architecture map.

Understand modules, controllers, providers, and dependencies without reading thousands of lines of code.

No cloud. No AI. No source code upload. Everything runs locally.

Features

Architecture Graph

Visualize your NestJS application structure as an interactive SVG graph.

• Modules, controllers, and providers as color-coded nodes with Lucide icons
• Module imports, ownership, middleware, and dependency injection as edges
• Hybrid hierarchical layout with compact route tags attached to controllers
• Pan, zoom, auto-fit, and draggable nodes
• Mini map with viewport indicator for navigation
• Click any node to highlight its connections

Inspector Panel

Select any node to see:

• Node type and name
• Source file path
• Outgoing and incoming relationships
• Click any relationship to navigate

Status Bar

Always-visible project summary:

• Project name
• Node and edge counts
• Module, controller, and provider counts

Global Search

Press Cmd+K (macOS) or Ctrl+K (Windows) to search across all nodes.

• Fuzzy matching on node names
• Keyboard navigation (arrow keys + Enter)
• Click a result to select it in the graph

Architecture Insights

After analysis, NestLens automatically runs architectural insight rules:

• 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.

Documentation

All documentation lives in docs/:

• 01_PRODUCT_VISION.md — Vision and mission
• 02_MVP_SCOPE.md — Current MVP scope and implemented features
• 03_ARCHITECTURE.md — System architecture and package boundaries
• 04_IMPLEMENTATION_PLAN.md — Phase-by-phase implementation plan
• 05_AGENT_RULES.md — Engineering rules for AI agents
• 06_ANALYZER_SPECIFICATION.md — Detector specifications
• 07_UI_GUIDELINES.md — UI design guidelines
• 08_GRAPH_MODEL.md — Graph data model specification
• 09_TASK_BREAKDOWN.md — Task-level breakdown
• 10_DEV_GUIDE.md — Development guide
• 11_PLUGIN_SYSTEM.md — Future plugin system design
• 12_RELEASE_PROCESS.md — Release process
• 13_README.md — Extended README
• 14_CONTRIBUTING.md — Contributing guide
• 15_CI_CD.md — CI/CD pipeline
• 16_ROADMAP.md — Product roadmap
• 17_SECURITY.md — Security policy
• 18_CHANGELOG.md — Changelog

License

MIT