Docteur

AdonisJS cold start profiler - Analyze and optimize your application boot time

Docteur profiles your AdonisJS application's cold start performance. It measures how long each module takes to load and helps you identify bottlenecks in your boot process.

Installation

Install globally:

npm install -g @densetsuuu/docteur
# or
pnpm add -g @densetsuuu/docteur

Usage

Navigate to your AdonisJS project and run:

# Quick diagnosis
docteur diagnose

# Interactive explorer
docteur xray

Commands

docteur diagnose

Analyzes cold start performance and displays a report.

docteur diagnose [options]

| Option | Description | Default | | ------------------- | --------------------------------------- | --------------- | | --top | Number of slowest modules to display | 20 | | --threshold | Only show modules slower than this (ms) | 1 | | --no-node-modules | Exclude node_modules from analysis | false | | --no-group | Don't group modules by package | false | | --entry | Custom entry point to profile | bin/server.ts |

docteur xray

Interactive TUI for exploring module dependencies.

docteur xray [options]

| Option | Description | Default | | --------- | ------------------ | --------------- | | --entry | Custom entry point | bin/server.ts |

Features:

• Browse slowest modules
• Drill down into module dependencies
• See why a module was loaded (import chain)
• View lazy import recommendations for heavy dependencies
• Explore provider lifecycle times (register, boot, start, ready)

Keyboard shortcuts:

• ↑/↓ Navigate
• Enter Select
• Tab Switch between Modules/Providers view
• ←/Backspace/ESC Go back
• q Quit

Example Output

  🩺 Docteur - Cold Start Analysis
  ─────────────────────────────────

  📊 Summary

  Total boot time:       459.26ms
  Total modules loaded:  447
    App modules:         19
    Node modules:        221
    AdonisJS modules:    186
  Module import time:    72.91ms
  Provider exec time:    12.35ms

  📁 App Files by Category

  🚀 Start Files (4 files, 15.23ms)
  ┌───────────────────────┬──────────┬──────────┬────────────────────────┐
  │ routes.ts             │ 10.53ms  │ 0.19ms   │ █████████████████████  │
  │ kernel.ts             │  2.15ms  │ 0.08ms   │ ████░░░░░░░░░░░░░░░░░  │
  │ env.ts                │  1.89ms  │ 0.12ms   │ ████░░░░░░░░░░░░░░░░░  │
  └───────────────────────┴──────────┴──────────┴────────────────────────┘

  ⚡ Provider Execution Times
  Time spent in register() and boot() methods

  ┌─────────────────────┬──────────┬──────────┬──────────┬────────────┐
  │ Provider            │ Register │ Boot     │ Total    │            │
  ├─────────────────────┼──────────┼──────────┼──────────┼────────────┤
  │ EdgeServiceProvider │ 0.15ms   │ 2.76ms   │ 2.91ms   │ ████████   │
  │ HashServiceProvider │ 0.08ms   │ 1.23ms   │ 1.31ms   │ ████       │
  └─────────────────────┴──────────┴──────────┴──────────┴────────────┘

  ✅ No major issues detected!

How It Works

Docteur measures cold start performance through two complementary approaches:

1. Module Loading: Uses Node.js ESM loader hooks to intercept every import() and measure how long each module takes to load.

2. Provider Lifecycle: Subscribes to AdonisJS's built-in tracing channels to measure the duration of provider lifecycle methods (register, boot, start, ready).

Timing Columns

• Total: Time including all transitive dependencies (cascading impact)
• Self: Time for just that file (excluding dependencies)

Execution Flow

1. docteur diagnose
       │
       ▼
2. Spawns child process with --import loader.ts
       │
       ▼
3. loader.ts registers ESM hooks + subscribes to tracing channels
       │
       ▼
4. hooks.ts intercepts every import, measures load time
       │
       ▼
5. AdonisJS app starts, HTTP server listens
       │
       ▼
6. CLI detects "started HTTP server", requests results
       │
       ▼
7. Results sent via IPC, report displayed

Requirements

• AdonisJS v7+
• Node.js 22+

License

MIT