npm package: @mdfrough/ngx-dev-flow
Description: 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.
Latest version: 0.0.6

# @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

```bash
npm install @mdfrough/ngx-dev-flow --save-dev
```

or with yarn:

```bash
yarn add --dev @mdfrough/ngx-dev-flow
```

---

## Usage

### 1. Import the Overlay

Add the overlay component to your root or feature module/component:

```typescript
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

```typescript
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:

```typescript
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](https://github.com/MDFrough)