@mdfrough/ngx-dev-flow

A developer tool for Angular projects that visualizes your component and service dependency graph in real time, with a floating overlay and D3-powered graph. Includes codemod for automatic decorator insertion.

Features

• Visualize Angular component and service relationships live in your app
• Automatic detection of parent-child and DI (service) edges
• Floating overlay with interactive D3 graph
• Codemod to auto-insert @TrackComponent and @TrackService decorators
• Designed for development only (easy to disable in production)

Installation

or with yarn: yarn add --dev @mdfrough/ngx-dev-flow

npm install @mdfrough/ngx-dev-flow --save-dev

or with yarn:

yarn add --dev @mdfrough/ngx-dev-flow

Usage

1. Import the Overlay

Add the overlay component to your root or feature module/component:

import { DevFlowOverlayComponent } from "@mdfrough/ngx-dev-flow";

@Component({
  // ...
  imports: [DevFlowOverlayComponent],
})
export class AppComponent {}

Add <ngx-dev-flow-overlay /> to your root template (e.g. app.component.html).

2. Decorate Components and Services

Decorate your Angular components and services:

npx ngx-dev-flow-codemod npm run devflow-codemod

import { TrackComponent, TrackService } from '@mdfrough/ngx-dev-flow';

@TrackComponent()
@Component({...})
export class MyComponent {}

@TrackService()
@Injectable({ providedIn: 'root' })
export class MyService {}

3. Use the Codemod (Auto Decorator)

To automatically add decorators to all components and services, run:

npx ngx-dev-flow-codemod

or (if installed globally):

npm run devflow-codemod

Codemod Path Auto-Detection

The codemod now automatically detects both standard and monorepo Angular layouts:

• Standard Angular app:
  • Scans src/app/**/*.ts by default.
• Angular monorepo (Nx, Angular CLI multi-project, etc):
  • Scans all projects/**/src/app/**/*.ts folders automatically.

If no app files are found, the codemod will prompt you to specify a path.

For Custom Layouts or Troubleshooting

You can always specify the path to your app files explicitly:

node dist/@mdfrough/ngx-dev-flow/add-devflow-decorators.js <path-to-app-files>

For example:

node dist/@mdfrough/ngx-dev-flow/add-devflow-decorators.js projects/my-app/src/app/**/*.ts

This ensures the codemod works for any project structure, including published npm usage and monorepos.

Tip: If you do not see any "Updated: ..." messages, check that the codemod is scanning the correct files and that your files are not excluded by .gitignore or tsconfig settings.

Disabling in Production

Never enable DevFlow in production!

• The overlay and tracking are controlled by the DEV_FLOW_ENABLED injection token.
• In your main.ts or app module, provide it based on environment:

import { DEV_FLOW_ENABLED } from "@mdfrough/ngx-dev-flow";
import { environment } from "../environments/environment";

bootstrapApplication(AppComponent, {
  providers: [{ provide: DEV_FLOW_ENABLED, useValue: !environment.production }],
});

• The overlay and tracking will only activate if DEV_FLOW_ENABLED is true.

How It Works

• Uses Angular decorators and runtime metadata to track DI and parent-child relationships.
• Maintains a registry of all components and services in the app.
• Renders a live graph overlay using D3.js.
• Codemod uses ts-morph to insert decorators and imports automatically.

License

MIT

Author

• MDFrough