CLI tool for profiling Chromium-based browsers via CDP and identifying rendering bottlenecks with actionable fixes
npm install render-debuggerA CLI tool for profiling Chromium-based browsers via CDP and identifying rendering bottlenecks with actionable fixes.


```
┌─────────────────────────────────────────────────────────────────┐
│ CLI Interface │
├─────────────────────────────────────────────────────────────────┤
│ init │ profile │ analyze │ compare │ fix │ monitor │ rules │
└───────────────────────────┬─────────────────────────────────────┘
│
┌───────────────────────────▼─────────────────────────────────────┐
│ Core Engine │
├─────────────┬─────────────┬─────────────┬─────────────┬─────────┤
│ Recorder │ Analyzer │ Suggester │ Patcher │ Monitor │
│ │ │ │ │ │
│ • CDP │ • Layout │ • CSS │ • Diff │ • Roll │
│ • Trace │ • GPU │ • JS │ • Git │ • Alert │
│ • Scenario │ • Tasks │ • Native │ • Apply │ • Trend │
└─────────────┴─────────────┴─────────────┴─────────────┴─────────┘
│
┌───────────────────────────▼─────────────────────────────────────┐
│ Browser Adapters │
├─────────────────────────────┬───────────────────────────────────┤
│ Chromium CDP Adapter │ WebKit Native Adapter │
│ (Chrome, Edge, Arc, Dia) │ (Safari via Swift SDK) │
└─────────────────────────────┴───────────────────────────────────┘
`bash`
npm install -g render-debugger
`bashInitialize workspace
render-debugger init --browser-path /path/to/chrome
CLI Commands
| Command | Alias | Description |
|---------|-------|-------------|
|
analyze [trace] | a | Analyze trace (auto-detects latest if omitted) |
| profile | p | Profile a web page under a specific scenario |
| compare | c | Compare traces (uses latest for head if omitted) |
| fix [trace] | f | Generate and optionally apply patches |
| monitor | m | Continuous performance monitoring |
| init | - | Initialize workspace with config and scenarios |
| rules list | - | Display configured rules |
| rules validate | - | Validate rules configuration |Command Examples
$3
`bash
Auto-detect and analyze latest trace
render-debugger aAnalyze specific trace
render-debugger a trace.jsonWith custom name and JSON output
render-debugger a trace.json --name "homepage" --json report.jsonGenerate HTML report
render-debugger a trace.json --out report.html
`$3
`bash
Basic profile
render-debugger p --url "https://example.com" --scenario scroll-heavyWith options
render-debugger p \
--url "https://example.com" \
--scenario scroll-heavy \
--profile-duration 30 \
--fps-target 60 \
--headless
`$3
`bash
Compare baseline against latest trace
render-debugger c baseline.jsonCompare two specific traces
render-debugger c baseline.json current.jsonFail CI on high severity regressions
render-debugger c baseline.json --fail-on high --json diff.json
`Impact Score Interpretation:
- 0-40: Minor changes - Small optimizations or negligible regressions
- 41-70: Moderate impact - Noticeable improvements or concerning regressions
- 71-100: Major impact - Significant improvements or critical regressions
The impact score uses enterprise-grade weighted scoring:
- Critical metrics (FPS, dropped frames) weighted 2x
- Severity-based weighting for regressions (info: 1x, warning: 2x, high: 4x, critical: 8x)
- Normalized across all detected changes for consistent scoring
$3
`bash
Preview fixes for latest trace
render-debugger fPreview fixes for specific trace
render-debugger f trace.json --dry-runAuto-apply with Git
render-debugger f --auto-apply --git-branch perf/fixes
`$3
`bash
Basic monitoring
render-debugger m --url "https://example.com" --scenario scroll-heavyWith rolling window and alerts
render-debugger m \
--url "https://example.com" \
--scenario scroll-heavy \
--rolling 60 \
--alert-cmd "notify-send 'Performance Alert'"
`CI/CD Integration
`yaml
GitHub Actions
- name: Performance Check
run: |
npm install -g render-debugger
render-debugger init --browser-path /usr/bin/chromium-browser
render-debugger p --url "$APP_URL" --scenario scroll-heavy --headless
render-debugger a --json report.json
render-debugger c baseline.json --fail-on high
`Exit Codes
| Code | Description |
|------|-------------|
| 0 | Success |
| 1-9 | General errors |
| 10-19 | CDP/Browser errors |
| 20-29 | Git/Patch errors |
| 30-39 | Trace errors |
| 40-49 | Rule errors |
| 50-59 | CI threshold exceeded |
Tech Stack
- Runtime: Node.js 18+
- Framework: NestJS
- Language: TypeScript
- CDP: chrome-remote-interface
- Testing: Jest
Browser Support
| Browser | Adapter | Method |
|---------|---------|--------|
| Chrome | CDP | Remote debugging |
| Edge | CDP | Remote debugging |
| Arc | CDP | Remote debugging |
| Safari | WebKit | Swift SDK |
Requirements
- Node.js 18+
- npm 9+
- Chromium-based browser
- Git (for
--auto-apply`)- CLI Commands Reference
- Browser Setup
- Swift SDK
MIT © Aryan Yadav