A tiny in-app profiler overlay for Angular that works in both zoned and zoneless applications
npm install @code-zetta/ng-profilerA 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.
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
Ctrl+Shift+P)data-ng-profiler="low|medium|high" attribute to DOM elementsApplicationRef.tick() to measure each change detection cyclerequestAnimationFrame deltas + PerformanceObserver('longtask')``bash`
npm install @codezetta/ng-profiler
#### 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();
}
}
`
#### 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
``MIT
Contributions are welcome! Please feel free to submit a Pull Request.