nest-cartograph
Map a NestJS app — modules, providers, controllers and who injects what — straight from its TypeScript source, then explore the map in your browser.
npx nest-cartograph
Nothing in your app runs: no database, no environment variables, no build. The analyzer reads the code with the TypeScript compiler API, the same way your editor does.
How it works
Two steps, like go test -coverprofile followed by go tool cover -html:
| Step | Command | Output |
|---|
| 1. Analyze | npx nest-cartograph analyze | cartograph.json |
| 2. View | npx nest-cartograph view cartograph.json | an interactive map at http://localhost:4300 |
npx nest-cartograph with no command does both, without writing the JSON.
cartograph.json is deterministic — no timestamps, everything sorted — so you can commit it and review how the architecture changed in a pull request.
Commands
npx nest-cartograph analyze # writes ./cartograph.json
npx nest-cartograph analyze -p apps/api/tsconfig.json -o docs/cartograph.json
npx nest-cartograph analyze -o - | jq '.cycles' # JSON to stdout
npx nest-cartograph analyze --fail-on-cycles # exit code 2 on circular imports without forwardRef()
npx nest-cartograph view # serves ./cartograph.json and opens the browser
npx nest-cartograph view docs/cartograph.json --port 5055 --no-open
npx nest-cartograph view -o cartograph.html # one self-contained HTML file, no server needed
Summaries, warnings and cycles go to stderr. Run npx nest-cartograph --help for everything.
Following one flow
On a big app the Providers view is too dense to read. Type a name in the search box and press
Enter to see only the flow around the matches, laid out left to right from controllers to
repositories and Kafka producers. The panel on the left filters it:
- Relationship: what the matches call, what calls them, or both, and how many hops away.
- Layers: controllers, services, database, Kafka / events, external APIs, guards, logger / config
and interfaces, guessed from names. Logger / config, guards and interfaces start hidden; a hidden
interface is skipped over, so
Controller → IFooService → FooService reads Controller → FooService.
- Modules: every module the flow reaches, for example
ReportModule when searching employee,
with a checkbox to drop it.
Esc closes the panels, then leaves the flow view. Show flow in a node's details does the same
for that node.
Opening the code
When the map is served by nest-cartograph view (or plain npx nest-cartograph), a node's details
have Open in VS Code and Open in Zed links that jump to the class's line, through the editors'
vscode:// and zed:// links. A file written with -o leaves them out: it is meant to be shared, so
it carries no paths from your machine.
What the analyzer understands
| In your code | On the map |
|---|
@Module({ imports, providers, controllers, exports }) | modules, what they own, what they export |
ConfigModule.forRoot(...), TypeOrmModule.forFeature(...) | an import labelled with the method |
static forRoot() { return { module: ThisModule, providers, exports, global } } | the returned module's providers and exports |
@Global() | global modules |
forwardRef(() => X) in imports and @Inject() | dashed edges and cycle detection |
[...SHARED_PROVIDERS], providers: ORDERS_PROVIDERS, .concat() | arrays held in constants, across files |
useClass, useValue, useFactory + inject, useExisting | custom providers |
constructor parameters, @Inject(TOKEN), @Optional(), @Inject() properties | injection edges |
string tokens, Symbol('x'), constants holding either | one node per token, shared by provider and consumer |
@InjectRepository(User), @InjectModel(Cat.name), ... | a token named after the decorator call |
It also warns about decorated classes that no module registers, injections without a token, and anything it could not resolve.
Limits. Static analysis does not run code: modules picked at runtime (both sides of cond ? A : B are shown), providers built in loops, and providers created inside third-party dynamic modules are not visible.
The JSON format
{
"schemaVersion": 1,
"project": { "root": ".", "tsconfig": "tsconfig.json" },
"nodes": [
{ "id": "src/users/users.module.ts#UsersModule", "kind": "module", "name": "UsersModule", "file": "src/users/users.module.ts", "line": 6 },
{ "id": "src/users/users.service.ts#UsersService", "kind": "provider", "providerType": "class", "name": "UsersService", "file": "src/users/users.service.ts", "line": 8 }
],
"edges": [
{ "from": "src/app.module.ts#AppModule", "to": "src/users/users.module.ts#UsersModule", "kind": "imports" },
{ "from": "src/users/users.module.ts#UsersModule", "to": "src/users/users.service.ts#UsersService", "kind": "provides" }
],
"cycles": [{ "ids": ["..."], "names": ["UsersModule", "OrdersModule"], "guarded": true }],
"warnings": []
}
Edge kinds: imports, provides, controls, exports, injects, aliases. The full types are in src/schema.ts, and also exported:
import { analyze, type Cartograph } from 'nest-cartograph';
const map: Cartograph = analyze({ project: 'tsconfig.json' });
Requirements
Node.js 22 or later. The analyzer brings its own TypeScript 6, so it works whatever TypeScript your project uses — including TypeScript 7, which has no compiler API yet.
Development
npm install
npm test # analyzer golden test + UI logic tests (vitest)
npm run test:update # rewrite test/testdata/app.golden.json after an intended change
npm run lint # oxlint
npm run typecheck # src + test, and ui/
npm run build # tsc → dist/, then vite → dist/ui/index.html
npm run dev:ui # UI with hot reload, on the fixture app's map
npm run build:website # website/ → website/dist, with the fixture app's map as the live demo
node dist/cli/index.js -p test/fixtures/tsconfig.json # try the built CLI
src/
cli/ index.ts (commands) · analyze.ts (step 1) · view.ts (step 2: server, browser) · html.ts (embed JSON in the UI)
analyzer/ index.ts (the passes) · program.ts (tsconfig → ts.Program) · resolve.ts (names → classes, tokens, arrays)
modules.ts (@Module, forRoot) · providers.ts (custom providers) · injection.ts (constructors, @Inject)
context.ts (shared state) · ast.ts (syntax helpers)
graph/ builder.ts (dedupe, placeholders, stable order) · cycles.ts (Tarjan)
schema.ts the cartograph.json contract, shared with the UI
ui/ React + React Flow (@xyflow/react) + elkjs, built by Vite into ONE html file
src/ App.tsx · load.ts · toFlow.ts (JSON → nodes/edges) · layout.ts (ELK positions + edge routes)
measure.ts (text widths) · nodes/ · edges/RoutedEdge.tsx · panels/
test/
fixtures/app a NestJS app exercising every case above
testdata/ golden output
Releases: bump version in package.json, commit, then git tag v0.1.0 && git push --tags. The release workflow publishes with npm Trusted Publishing. The very first version has to be published by hand (npm publish), because the Trusted Publisher setting lives on the package's page on npmjs.com.
License
MIT. The bundled UI includes elkjs (EPL-2.0) and React Flow (MIT).
