nestlens-viewer

Nest Lens

See your NestJS architecture, clearly.

What is NestLens?

NestJS projects grow complex fast. Modules import other modules, controllers define dozens of routes, providers depend on each other — and suddenly you're lost in the code. NestLens solves this by automatically scanning your source code and showing you the full architecture as an interactive visual map. No manual documentation, no guesswork — just run it and see how everything connects.

What You Get

Without NestLens	With NestLens
Manually trace @Module decorators to understand relationships	See modules, imports, controllers, and providers at a glance
Search files to find all routes and their HTTP methods	View all routes with color-coded method badges instantly
Guess which services a controller depends on	Inspect constructor-injected dependencies from the UI
Lose track of the big picture in large codebases	Get live summary statistics across the entire project

How It Works

NestLens reads your code without running it. The analysis engine uses the TypeScript Compiler API to build an in-memory version of your project, walks through the code structure, and finds every @Module, @Controller, and @Injectable decorator. From each one, it pulls out routes, dependencies, and relationships — then builds a clean JSON structure from it.

A lightweight Express server serves this data to a browser-based dashboard, where everything is rendered as an interactive visualization — no build tools, no bundler, no complexity.

Core Concepts

Concept	What It Does in NestLens
Abstract Syntax Tree (AST)	Represents source code as a tree structure — NestLens walks it to find decorated classes
TypeScript Compiler API	Compiles your project in memory, giving access to all files and type information
Decorator Pattern	NestJS decorators carry metadata — NestLens reads them to extract architecture
Static Analysis	Everything happens at compile time — your project never needs to run
Dependency Injection	Constructor parameters are inspected to map which services each class depends on
Express Server	A minimal HTTP server serves the API and the dashboard
Vanilla JavaScript	The entire UI is built from JSON data — no frameworks, no build step

Project Structure

nestlens/
├── package.json
├── tsconfig.json
├── .gitignore
│
├── package/
│   ├── server.ts        — Express server, runs analysis, serves dashboard on port 4000
│   ├── parser.ts        — Core analysis engine using the TypeScript Compiler API
│   └── types.ts         — TypeScript interfaces for the data model
│
└── dist/
    └── package/
        ├── server.js
        ├── parser.js
        ├── types.js
        └── client/
            ├── index.html   — Interactive dashboard (HTML + CSS + JS, fully self-contained)
            └── logo.png

The Dashboard

The dashboard is a single-page application that runs entirely in your browser.

Live statistics — real-time counts for modules, controllers, providers, and routes.

Module graph — the root module sits at the center with SVG lines connecting to its imported child modules. Each card shows controller count, provider count, and imports.

Three layout modes:

• Radial — modules arranged in a circle around the root, with relationship lines
• Tree — hierarchical top-down view showing the dependency tree
• Cards — clean grid view, no lines, just an inventory of all modules

Focus mode — click any module to highlight its relationships and dim everything else.

Detail modals — click a module to see its controllers, providers, and imports. Click a controller to see all routes with HTTP method badges. Click a provider to see its dependencies and public methods.

Color-coded HTTP methods — GET (green), POST (orange), PUT (blue), PATCH (purple), DELETE (red).

Search — filter modules in real time from the header bar.

Keyboard shortcuts — zoom, reset view, fullscreen, and more.

How to Use

Prerequisites

• Node.js v18 or later
• A NestJS project to analyze

Step 1 — Install NestLens

npm install nestlens-viewer

Step 2 — Run It

Navigate to your NestJS project root and run:

npx nest-viewer

NestLens will scan your src/app.module.ts and all files it imports, then open the dashboard automatically at http://localhost:4000.

Step 3 — Explore

• Use the bottom control bar to switch between Radial, Tree, and Cards layouts
• Click any module card to open its detail modal
• Right-click a card to show or hide its relationships
• Scroll to pan, Ctrl + scroll to zoom
• Use the search bar to filter modules by name

Tip: If you're running NestLens from inside the project folder, it will automatically find your src/app.module.ts.

Keyboard Shortcuts

Shortcut	Action
Ctrl + +	Zoom in
Ctrl + -	Zoom out
Ctrl + 0	Reset view
F11	Toggle fullscreen
Escape	Close modal / exit focus mode
Click + Drag	Move cards around

Built With AI

The interactive dashboard (dist/package/client/index.html) was designed and implemented with assistance from OpenCode AI, which helped generate the HTML, CSS, and JavaScript for the visualization layer.

Contributing

NestLens is open-source and welcomes contributions from developers at any level.

Reporting bugs — open an issue with a clear description and steps to reproduce.

Suggesting features — open an issue describing what you need and how it should work.

Submitting pull requests — fix bugs, add features, improve docs, or write tests. Please open an issue first for significant changes so we can discuss the scope.

Improving documentation — corrections, clarifications, and translations are all welcome.

License

This project is licensed under the MIT License. See the LICENSE file for details.

Made with care by developers, for developers.
_{NestLens — See your NestJS architecture, clearly.}