@codezetta/ng-profiler

A tiny in-app profiler overlay for Angular that works in both zoned and zoneless applications. It helps developers quickly see approximate render counts and frame timings without leaving the app.

🎯 Purpose

Show an overlay inside the Angular app (top-right corner) that displays:

- Last tick/frame duration (ms) and average duration
- Top 10 components/elements by render count (approximate)
- Heatmap outlines on DOM nodes that render too often (green → yellow → red)
- Auto-detect Zone.js and adapt measurement accordingly

✨ Features

$3

- Toggle with hotkey (default Ctrl+Shift+P)
- Shows last/average tick time with color-coded warnings
- List of top 10 elements/components by render count
- Snapshot button → downloads JSON with current stats
- Reset button to clear all statistics

$3

- Adds data-ng-profiler="low|medium|high" attribute to DOM elements
- CSS outlines with severity indicators:
- 🟢 Green: Low render count (6-20)
- 🟡 Yellow: Medium render count (21-50)
- 🔴 Red: High render count (50+)

$3

- Zoned apps: Patches ApplicationRef.tick() to measure each change detection cycle
- Zoneless apps: Uses requestAnimationFrame deltas + PerformanceObserver('longtask')

$3

- Disabled automatically in production unless forced
- Configurable thresholds and behavior

🚀 Installation

``bash
npm install @codezetta/ng-profiler
`

📦 Setup

$3

#### 1. Import the Module

`typescript
import { NgProfilerModule } from '@codezetta/ng-profiler';

@NgModule({
imports: [
NgProfilerModule.forRoot({
// Optional configuration
enableInProduction: false,
hotkey: 'Ctrl+Shift+P',
position: 'top-right',
renderCountThreshold: 10,
frameDurationThreshold: 16.67,
enableHeatmap: true,
enableMeasurement: true
})
]
})
export class AppModule { }
`

#### 2. Add the Overlay Component

Add the overlay component to your app component template:

`html


`

#### 3. Initialize the Profiler

`typescript
import { NgProfilerService } from '@codezetta/ng-profiler';

@Component({...})
export class AppComponent implements OnInit {
constructor(private profilerService: NgProfilerService) {}

ngOnInit() {
this.profilerService.initialize();
}
}
`

$3

#### 1. Configure Providers

`typescript
// app.config.ts
import { ApplicationConfig } from '@angular/core';
import { provideNgProfiler } from '@codezetta/ng-profiler';

export const appConfig: ApplicationConfig = {
providers: [
// ... other providers
...provideNgProfiler({
enableInProduction: false,
hotkey: 'Ctrl+Shift+P',
position: 'top-right',
enableHeatmap: true,
enableMeasurement: true
})
]
};
`

#### 2. Import Components in Your App

`typescript
// app.component.ts
import { Component, OnInit } from '@angular/core';
import { NgProfilerOverlayComponent, NgProfilerDirective } from '@codezetta/ng-profiler';
import { NgProfilerService } from '@codezetta/ng-profiler';

@Component({
selector: 'app-root',
standalone: true,
imports: [
NgProfilerOverlayComponent,
NgProfilerDirective
],
template:

})
export class AppComponent implements OnInit {
constructor(private profilerService: NgProfilerService) {}

ngOnInit() {
this.profilerService.initialize();
}
}
`

$3

Add the directive to components you want to track:

`html







`

$3

For heatmap styles, include the CSS in your global styles:

`typescript
// angular.json
{
"styles": [
"node_modules/@codezetta/ng-profiler/styles/ng-profiler.css"
]
}
`

Or import in your global styles:

`css
/ styles.css /
@import '@codezetta/ng-profiler/styles/ng-profiler.css';
`

⚙️ Configuration

`typescript
interface NgProfilerConfig {
/* Enable profiler in production (default: false) /
enableInProduction?: boolean;

/* Hotkey to toggle overlay (default: 'Ctrl+Shift+P') /
hotkey?: string;

/* Position of overlay (default: 'top-right') /
position?: 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';

/* Threshold for render count warnings (default: 10) /
renderCountThreshold?: number;

/* Threshold for frame duration warnings in ms (default: 16.67) /
frameDurationThreshold?: number;

/* Enable heatmap outlines (default: true) /
enableHeatmap?: boolean;

/* Enable performance measurement (default: true) /
enableMeasurement?: boolean;
}
`

🎮 Usage

$3


- Press Ctrl+Shift+P (or your configured hotkey)
- Click the close button (✕) in the overlay
- Press Escape key

$3

Click the 📊 button in the overlay to download a JSON file with current statistics.

$3

Click the 🔄 button in the overlay to clear all collected data.

🔍 How It Works

$3

The profiler automatically detects if Zone.js is present and adapts its measurement strategy:

- Zoned: Patches ApplicationRef.tick() to measure change detection cycles
- Zoneless: Uses requestAnimationFrame timing and PerformanceObserver for long tasks

$3


The codezettaNgProfiler directive uses ngDoCheck and ngAfterViewChecked to increment render counts for tracked components.

$3

Components with high render counts get data-ng-profiler attributes that trigger CSS outlines:
- Low: Green outline
- Medium: Yellow outline
- High: Red outline with pulsing animation

📊 Performance Impact

The profiler is designed to have minimal performance impact:
- Measurements are batched and averaged
- Heatmap updates are throttled
- All profiling is disabled in production by default
- Memory usage is limited with configurable history size

🛠️ Development

$3

`bash
ng build ng-profiler
`

$3

`bash
ng test ng-profiler
`

$3

`bash
npm publish --access public
``

📝 License

MIT

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.