adonisjs-server-stats 1.5.4 → 1.6.2

package/README.md

@@ -13,6 +13,8 @@ Drop a single Edge tag into your layout and get a live stats bar showing CPU, me
 
 Zero frontend dependencies. Zero build step. Just `@serverStats()` and go.
 
+**New (alpha):** Native [React & Vue components](#react--vue-inertiajs--alpha) for Inertia.js apps — same features, framework-native.
+
 ![adonisjs-server-stats demo](https://raw.githubusercontent.com/simulieren/adonisjs-server-stats/main/screenshots/demo.gif)
 
 ## Screenshots
@@ -42,7 +44,8 @@ Zero frontend dependencies. Zero build step. Just `@serverStats()` and go.
 - **Visibility control** -- show only to admins, specific roles, or in dev mode
 - **SSE broadcasting** -- real-time updates via AdonisJS Transmit
 - **Prometheus export** -- expose all metrics as Prometheus gauges
-- **Self-contained** -- inline HTML/CSS/JS Edge tag, no React, no external assets
+- **Self-contained** -- inline HTML/CSS/JS Edge tag, no external assets
+- **React & Vue support (alpha)** -- native Inertia.js components with the same features as Edge
 - **Graceful degradation** -- missing optional dependencies are handled automatically
 - **Theme support** -- dark and light themes across dashboard, debug panel, and stats bar with system preference detection and manual toggle
 
@@ -82,14 +85,26 @@ server.use([() => import('adonisjs-server-stats/middleware')])
 ```ts
 // config/server_stats.ts
 import { defineConfig } from 'adonisjs-server-stats'
-import { processCollector, systemCollector, httpCollector } from 'adonisjs-server-stats/collectors'
+
+export default defineConfig({})
+```
+
+That's it -- zero config required. Collectors are auto-detected from your installed packages (Lucid, Redis, BullMQ, etc.) and enabled automatically. All other options have sensible defaults.
+
+**Common setup** -- add access control and enable the toolbar/dashboard:
+
+```ts
+// config/server_stats.ts
+import { defineConfig } from 'adonisjs-server-stats'
 
 export default defineConfig({
-  collectors: [processCollector(), systemCollector(), httpCollector()],
+  authorize: (ctx) => ctx.auth?.user?.role === 'admin',
+  toolbar: true,
+  dashboard: true,
 })
 ```
 
-That's it -- this gives you CPU, memory, event loop lag, and HTTP throughput out of the box. All other options have sensible defaults. Add more collectors as needed:
+**Full control** -- override auto-detection with explicit collectors:
 
 ```ts
 // config/server_stats.ts
@@ -107,39 +122,13 @@ import {
 } from 'adonisjs-server-stats/collectors'
 
 export default defineConfig({
-  // How often to collect and broadcast stats (in milliseconds)
-  intervalMs: 3000,
-
-  // Real-time transport: 'transmit' for SSE via @adonisjs/transmit, 'none' for polling only
-  transport: 'transmit',
-
-  // Transmit channel name clients subscribe to
-  channelName: 'admin/server-stats',
-
-  // HTTP endpoint that serves the latest stats snapshot (set to false to disable)
-  endpoint: '/admin/api/server-stats',
-
+  pollInterval: 3000,
   collectors: [
-    // CPU usage, event loop lag, heap/RSS memory, uptime, Node.js version
     processCollector(),
-
-    // OS load averages, total/free system memory, system uptime
     systemCollector(),
-
-    // Requests/sec, avg response time, error rate, active connections
-    // maxRecords: size of the circular buffer for request tracking
     httpCollector({ maxRecords: 10_000 }),
-
-    // Lucid connection pool: used/free/pending/max connections
-    // Requires @adonisjs/lucid
     dbPoolCollector({ connectionName: 'postgres' }),
-
-    // Redis server stats: memory, connected clients, keys, hit rate
-    // Requires @adonisjs/redis
     redisCollector(),
-
-    // BullMQ queue stats: active/waiting/delayed/failed jobs
-    // Requires bullmq -- connects directly to Redis (not via @adonisjs/redis)
     queueCollector({
       queueName: 'default',
       connection: {
@@ -148,12 +137,7 @@ export default defineConfig({
         password: env.get('QUEUE_REDIS_PASSWORD'),
       },
     }),
-
-    // Log file stats: errors/warnings in a 5-minute window, entries/minute
-    logCollector({ logPath: 'logs/adonisjs.log' }),
-
-    // App-level metrics: online users, pending webhooks, pending emails
-    // Requires @adonisjs/lucid
+    logCollector(),
     appCollector(),
   ],
 })
@@ -167,7 +151,7 @@ That's it for setup -- **all API routes are auto-registered by the package**. No
 [server-stats] auto-registered routes: /admin/api/server-stats, /admin/api/debug/*, /__stats/*
 ```
 
-All routes are gated by the `shouldShow` callback if configured (see [Visibility Control](#visibility-control-shouldshow)).
+All routes are gated by the `authorize` callback if configured (see [Visibility Control](#visibility-control-authorize)).
 
 **Edge** (add before `</body>`):
 
@@ -179,44 +163,96 @@ All routes are gated by the `shouldShow` callback if configured (see [Visibility
 
 ## Config Reference
 
-### `ServerStatsConfig`
-
-| Option        | Type                   | Default                     | Description                          |
-| ------------- | ---------------------- | --------------------------- | ------------------------------------ |
-| `intervalMs`  | `number`               | `3000`                      | Collection + broadcast interval (ms) |
-| `transport`   | `'transmit' \| 'none'` | `'transmit'`                | SSE transport. `'none'` = poll-only. |
-| `channelName` | `string`               | `'admin/server-stats'`      | Transmit channel name                |
-| `endpoint`    | `string \| false`      | `'/admin/api/server-stats'` | HTTP endpoint. `false` to disable.   |
-| `collectors`  | `MetricCollector[]`    | `[]`                        | Array of collector instances         |
-| `skipInTest`  | `boolean`              | `true`                      | Skip collection during tests         |
-| `onStats`     | `(stats) => void`      | --                          | Callback after each collection tick  |
-| `shouldShow`  | `(ctx) => boolean`     | --                          | Per-request visibility guard         |
-| `devToolbar`  | `DevToolbarOptions`    | --                          | Dev toolbar configuration            |
-
-### `DevToolbarOptions`
-
-| Option                 | Type                | Default                                      | Description                                                                                                                                                                                                  |
-| ---------------------- | ------------------- | -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `enabled`              | `boolean`           | `false`                                      | Enable the dev toolbar                                                                                                                                                                                       |
-| `maxQueries`           | `number`            | `500`                                        | Max SQL queries to buffer                                                                                                                                                                                    |
-| `maxEvents`            | `number`            | `200`                                        | Max events to buffer                                                                                                                                                                                         |
-| `maxEmails`            | `number`            | `100`                                        | Max emails to buffer                                                                                                                                                                                         |
-| `slowQueryThresholdMs` | `number`            | `100`                                        | Slow query threshold (ms)                                                                                                                                                                                    |
-| `persistDebugData`     | `boolean \| string` | `false`                                      | Persist debug data to disk across restarts. `true` writes to `.adonisjs/server-stats/debug-data.json`, or pass a custom path.                                                                                |
-| `tracing`              | `boolean`           | `false`                                      | Enable per-request tracing with timeline visualization                                                                                                                                                       |
-| `maxTraces`            | `number`            | `200`                                        | Max request traces to buffer                                                                                                                                                                                 |
-| `dashboard`            | `boolean`           | `false`                                      | Enable the full-page dashboard (requires `better-sqlite3`)                                                                                                                                                   |
-| `dashboardPath`        | `string`            | `'/__stats'`                                 | URL path for the dashboard page                                                                                                                                                                              |
-| `retentionDays`        | `number`            | `7`                                          | Days to keep historical data in SQLite                                                                                                                                                                       |
-| `dbPath`               | `string`            | `'.adonisjs/server-stats/dashboard.sqlite3'` | Path to the SQLite database file (relative to app root)                                                                                                                                                      |
-| `debugEndpoint`        | `string`            | `'/admin/api/debug'`                         | Base path for the debug toolbar API endpoints                                                                                                                                                                |
-| `excludeFromTracing`   | `string[]`          | `['/admin/api/debug', '/admin/api/server-stats']`                                         | URL prefixes to exclude from tracing and dashboard persistence. Requests still count toward HTTP metrics but won't appear in the timeline or be stored. The stats endpoint is always excluded automatically. |
-| `panes`                | `DebugPane[]`       | --                                           | Custom debug panel tabs                                                                                                                                                                                      |
+### `ServerStatsConfig` (recommended)
+
+All fields are optional. `defineConfig({})` works with zero configuration.
+
+| Option          | Type                              | Default                     | Description                                                      |
+| --------------- | --------------------------------- | --------------------------- | ---------------------------------------------------------------- |
+| `pollInterval`  | `number`                          | `3000`                      | Collection + broadcast interval (ms)                             |
+| `collectors`    | `'auto' \| MetricCollector[]`     | `'auto'`                    | `'auto'` probes installed packages; or pass an explicit array    |
+| `realtime`      | `boolean`                         | `true`                      | `true` = SSE via Transmit, `false` = poll-only                   |
+| `statsEndpoint` | `string \| false`                 | `'/admin/api/server-stats'` | HTTP endpoint. `false` to disable.                               |
+| `authorize`     | `(ctx) => boolean`                | --                          | Per-request visibility guard                                     |
+| `onStats`       | `(stats) => void`                 | --                          | Callback after each collection tick                              |
+| `toolbar`       | `boolean \| ToolbarConfig`        | --                          | `true` to enable with defaults, or pass a `ToolbarConfig` object |
+| `dashboard`     | `boolean \| DashboardConfig`      | --                          | `true` to enable at `/__stats`, or pass a `DashboardConfig`      |
+| `advanced`      | `AdvancedConfig`                  | --                          | Rarely-needed options (channel name, db path, buffer sizes, etc) |
+
+### `ToolbarConfig`
+
+| Option               | Type       | Default                                           | Description                                     |
+| -------------------- | ---------- | ------------------------------------------------- | ----------------------------------------------- |
+| `slowQueryThreshold` | `number`   | `100`                                             | Slow query threshold (ms)                        |
+| `tracing`            | `boolean`  | `false`                                           | Enable per-request tracing with timeline         |
+| `persist`            | `boolean`  | `false`                                           | Persist debug data to disk across restarts       |
+| `panes`              | `DebugPane[]` | --                                             | Custom debug panel tabs                          |
+| `excludeFromTracing` | `string[]` | `['/admin/api/debug', '/admin/api/server-stats']` | URL prefixes to exclude from tracing/persistence |
+
+### `DashboardConfig`
+
+| Option          | Type     | Default      | Description                            |
+| --------------- | -------- | ------------ | -------------------------------------- |
+| `path`          | `string` | `'/__stats'` | URL path for the dashboard page        |
+| `retentionDays` | `number` | `7`          | Days to keep historical data in SQLite |
+
+### `AdvancedConfig`
+
+| Option          | Type                | Default                                      | Description                                     |
+| --------------- | ------------------- | -------------------------------------------- | ----------------------------------------------- |
+| `skipInTest`    | `boolean`           | `true`                                       | Skip collection during tests                    |
+| `channelName`   | `string`            | `'admin/server-stats'`                       | Transmit channel name                           |
+| `debugEndpoint` | `string`            | `'/admin/api/debug'`                         | Base path for debug toolbar API endpoints       |
+| `renderer`      | `'preact' \| 'vue'` | `'preact'`                                   | Client-side rendering library for Edge          |
+| `dbPath`        | `string`            | `'.adonisjs/server-stats/dashboard.sqlite3'` | Path to the SQLite database file                |
+| `persistPath`   | `string`            | `'.adonisjs/server-stats/debug-data.json'`   | Path for persisted debug data                   |
+| `maxQueries`    | `number`            | `500`                                        | Max SQL queries to buffer                       |
+| `maxEvents`     | `number`            | `200`                                        | Max events to buffer                            |
+| `maxEmails`     | `number`            | `100`                                        | Max emails to buffer                            |
+| `maxTraces`     | `number`            | `200`                                        | Max request traces to buffer                    |
+
+### Legacy config (deprecated)
+
+The following field names still work but will show deprecation warnings at boot. They will be removed in the next major version.
+
+| Legacy Name   | Replacement                     | Notes                                        |
+| ------------- | ------------------------------- | -------------------------------------------- |
+| `intervalMs`  | `pollInterval`                  | Same type and default                        |
+| `transport`   | `realtime`                      | `'transmit'` = `true`, `'none'` = `false`    |
+| `channelName` | `advanced.channelName`          | Same type and default                        |
+| `endpoint`    | `statsEndpoint`                 | Same type and default                        |
+| `shouldShow`  | `authorize`                     | Same type and default                        |
+| `skipInTest`  | `advanced.skipInTest`           | Same type and default                        |
+| `devToolbar`  | `toolbar` + `dashboard` + `advanced` | Split into focused config objects       |
+
+### `DevToolbarOptions` (internal)
+
+> **Note:** This is the internal, fully-expanded format. Most users should prefer the new `toolbar`, `dashboard`, and `advanced` options above -- they map to these fields automatically.
+
+| Option                 | Type                | Default                                           | Description                                                                                                                                                                                                  |
+| ---------------------- | ------------------- | ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `enabled`              | `boolean`           | `false`                                           | Enable the dev toolbar                                                                                                                                                                                       |
+| `maxQueries`           | `number`            | `500`                                             | Max SQL queries to buffer                                                                                                                                                                                    |
+| `maxEvents`            | `number`            | `200`                                             | Max events to buffer                                                                                                                                                                                         |
+| `maxEmails`            | `number`            | `100`                                             | Max emails to buffer                                                                                                                                                                                         |
+| `slowQueryThresholdMs` | `number`            | `100`                                             | Slow query threshold (ms)                                                                                                                                                                                    |
+| `persistDebugData`     | `boolean \| string` | `false`                                           | Persist debug data to disk across restarts. `true` writes to `.adonisjs/server-stats/debug-data.json`, or pass a custom path.                                                                                |
+| `tracing`              | `boolean`           | `false`                                           | Enable per-request tracing with timeline visualization                                                                                                                                                       |
+| `maxTraces`            | `number`            | `200`                                             | Max request traces to buffer                                                                                                                                                                                 |
+| `dashboard`            | `boolean`           | `false`                                           | Enable the full-page dashboard (requires `better-sqlite3`)                                                                                                                                                   |
+| `dashboardPath`        | `string`            | `'/__stats'`                                      | URL path for the dashboard page                                                                                                                                                                              |
+| `retentionDays`        | `number`            | `7`                                               | Days to keep historical data in SQLite                                                                                                                                                                       |
+| `dbPath`               | `string`            | `'.adonisjs/server-stats/dashboard.sqlite3'`      | Path to the SQLite database file (relative to app root)                                                                                                                                                      |
+| `debugEndpoint`        | `string`            | `'/admin/api/debug'`                              | Base path for the debug toolbar API endpoints                                                                                                                                                                |
+| `excludeFromTracing`   | `string[]`          | `['/admin/api/debug', '/admin/api/server-stats']` | URL prefixes to exclude from tracing and dashboard persistence. Requests still count toward HTTP metrics but won't appear in the timeline or be stored. The stats endpoint is always excluded automatically. |
+| `panes`                | `DebugPane[]`       | --                                                | Custom debug panel tabs                                                                                                                                                                                      |
 
 ---
 
 ## Collectors
 
+> When `collectors` is `'auto'` (the default), the package probes installed packages at boot and enables matching collectors automatically. On startup you'll see a log showing all 8 collectors with a checkmark or cross and which packages were found or missing. You only need to specify collectors explicitly if you want to customize their options.
+
 Each collector is a factory function that returns a `MetricCollector`. All collectors run in parallel each tick; missing peer dependencies are handled gracefully (the collector returns defaults instead of crashing).
 
 ### Built-in Collectors
@@ -229,7 +265,7 @@ Each collector is a factory function that returns a `MetricCollector`. All colle
 | `dbPoolCollector(opts?)` | Pool used/free/pending/max connections                          | optional     | `@adonisjs/lucid` |
 | `redisCollector()`       | Status, memory, clients, keys, hit rate                         | none         | `@adonisjs/redis` |
 | `queueCollector(opts)`   | Active/waiting/delayed/failed jobs, worker count                | **required** | `bullmq`          |
-| `logCollector(opts)`     | Errors/warnings/entries (5m window), entries/minute             | **required** | --                |
+| `logCollector(opts?)`    | Errors/warnings/entries (5m window), entries/minute             | optional     | --                |
 | `appCollector()`         | Online users, pending webhooks, pending emails                  | none         | `@adonisjs/lucid` |
 
 ### Collector Options
@@ -253,9 +289,11 @@ queueCollector({
   },
 })
 
-logCollector({
-  logPath: 'logs/adonisjs.log',
-})
+// Zero-config: hooks into AdonisJS Pino logger automatically
+logCollector()
+
+// Or file-based fallback:
+logCollector({ logPath: 'logs/adonisjs.log' })
 ```
 
 ### Custom Collectors
@@ -301,101 +339,104 @@ interface MetricCollector {
 
 ---
 
-## Visibility Control (`shouldShow`)
+## Visibility Control (`authorize`)
 
-Use `shouldShow` to control who can see the stats bar and access all auto-registered API routes (stats, debug, dashboard). The callback receives the AdonisJS `HttpContext` and should return `true` to allow access, `false` to deny (403).
+Use `authorize` to control who can see the stats bar and access all auto-registered API routes (stats, debug, dashboard). The callback receives the AdonisJS `HttpContext` and should return `true` to allow access, `false` to deny (403).
 
-Because `shouldShow` runs **after** middleware (including auth), you have full access to `ctx.auth`.
+Because `authorize` runs **after** middleware (including auth), you have full access to `ctx.auth`.
 
 ```ts
 export default defineConfig({
   // Only show in development
-  shouldShow: () => env.get('NODE_ENV'),
+  authorize: () => env.get('NODE_ENV'),
 })
 ```
 
 ```ts
 export default defineConfig({
   // Only show for logged-in admin users
-  shouldShow: (ctx) => ctx.auth?.user?.isAdmin === true,
+  authorize: (ctx) => ctx.auth?.user?.isAdmin === true,
 })
 ```
 
 ```ts
 export default defineConfig({
   // Only show for specific roles
-  shouldShow: (ctx) => {
+  authorize: (ctx) => {
     const role = ctx.auth?.user?.role
     return role === 'admin' || role === 'superadmin'
   },
 })
 ```
 
-> **Tip:** When `shouldShow` is not set, the bar and all routes are accessible to everyone. In production you almost always want to set this.
+> **Tip:** When `authorize` is not set, the bar and all routes are accessible to everyone. In production you almost always want to set this.
+>
+> **Migration note:** `shouldShow` still works as a deprecated alias for `authorize`. Both have the same signature and behavior.
 
 ---
 
 ## Auto-Registered Routes
 
-All API routes are registered automatically by the package during `boot()` -- no manual controllers or route definitions needed. Each route group is gated by the `shouldShow` callback if configured.
+All API routes are registered automatically by the package during `boot()` -- no manual controllers or route definitions needed. Each route group is gated by the `authorize` callback if configured.
 
 ### Stats bar endpoint
 
-Registered when `endpoint` is a string (default: `/admin/api/server-stats`). Returns the latest stats snapshot as JSON.
+Registered when `statsEndpoint` is a string (default: `/admin/api/server-stats`). Returns the latest stats snapshot as JSON.
 
 ### Debug toolbar routes
 
-Registered when `devToolbar.enabled: true`. Base path configurable via `devToolbar.debugEndpoint` (default: `/admin/api/debug`).
+Registered when `toolbar` is enabled. Base path configurable via `advanced.debugEndpoint` (default: `/admin/api/debug`).
 
-| Method | Path | Description |
-|--------|------|-------------|
-| GET | `/queries` | SQL queries with summary stats |
-| GET | `/events` | Application events |
-| GET | `/routes` | Registered route table |
-| GET | `/logs` | Log file entries (last 256KB) |
-| GET | `/emails` | Captured emails (stripped HTML) |
-| GET | `/emails/:id/preview` | Email HTML preview |
-| GET | `/traces` | Request traces |
-| GET | `/traces/:id` | Trace detail with spans |
+| Method | Path                  | Description                     |
+| ------ | --------------------- | ------------------------------- |
+| GET    | `/queries`            | SQL queries with summary stats  |
+| GET    | `/events`             | Application events              |
+| GET    | `/routes`             | Registered route table          |
+| GET    | `/logs`               | Log file entries (last 256KB)   |
+| GET    | `/emails`             | Captured emails (stripped HTML) |
+| GET    | `/emails/:id/preview` | Email HTML preview              |
+| GET    | `/traces`             | Request traces                  |
+| GET    | `/traces/:id`         | Trace detail with spans         |
 
 ### Dashboard routes
 
-Registered when `devToolbar.dashboard: true`. Base path configurable via `devToolbar.dashboardPath` (default: `/__stats`).
-
-| Method | Path | Description |
-|--------|------|-------------|
-| GET | `/` | Dashboard page (HTML) |
-| GET | `/api/overview` | Overview metrics |
-| GET | `/api/overview/chart` | Time-series chart data |
-| GET | `/api/requests` | Paginated request history |
-| GET | `/api/requests/:id` | Request detail with queries/trace |
-| GET | `/api/queries` | Paginated query list |
-| GET | `/api/queries/grouped` | Queries grouped by normalized SQL |
-| GET | `/api/queries/:id/explain` | EXPLAIN plan for a query |
-| GET | `/api/events` | Paginated event list |
-| GET | `/api/routes` | Route table |
-| GET | `/api/logs` | Paginated log entries |
-| GET | `/api/emails` | Paginated email list |
-| GET | `/api/emails/:id/preview` | Email HTML preview |
-| GET | `/api/traces` | Paginated trace list |
-| GET | `/api/traces/:id` | Trace detail with spans |
-| GET | `/api/cache` | Cache stats and key listing |
-| GET | `/api/cache/:key` | Cache key detail |
-| GET | `/api/jobs` | Job queue overview |
-| GET | `/api/jobs/:id` | Job detail |
-| POST | `/api/jobs/:id/retry` | Retry a failed job |
-| GET | `/api/config` | App config (secrets redacted) |
-| GET | `/api/filters` | Saved filters |
-| POST | `/api/filters` | Create saved filter |
-| DELETE | `/api/filters/:id` | Delete saved filter |
+Registered when `dashboard` is enabled. Base path configurable via `dashboard.path` (default: `/__stats`).
+
+| Method | Path                       | Description                       |
+| ------ | -------------------------- | --------------------------------- |
+| GET    | `/`                        | Dashboard page (HTML)             |
+| GET    | `/api/overview`            | Overview metrics                  |
+| GET    | `/api/overview/chart`      | Time-series chart data            |
+| GET    | `/api/requests`            | Paginated request history         |
+| GET    | `/api/requests/:id`        | Request detail with queries/trace |
+| GET    | `/api/queries`             | Paginated query list              |
+| GET    | `/api/queries/grouped`     | Queries grouped by normalized SQL |
+| GET    | `/api/queries/:id/explain` | EXPLAIN plan for a query          |
+| GET    | `/api/events`              | Paginated event list              |
+| GET    | `/api/routes`              | Route table                       |
+| GET    | `/api/logs`                | Paginated log entries             |
+| GET    | `/api/emails`              | Paginated email list              |
+| GET    | `/api/emails/:id/preview`  | Email HTML preview                |
+| GET    | `/api/traces`              | Paginated trace list              |
+| GET    | `/api/traces/:id`          | Trace detail with spans           |
+| GET    | `/api/cache`               | Cache stats and key listing       |
+| GET    | `/api/cache/:key`          | Cache key detail                  |
+| GET    | `/api/jobs`                | Job queue overview                |
+| GET    | `/api/jobs/:id`            | Job detail                        |
+| POST   | `/api/jobs/:id/retry`      | Retry a failed job                |
+| GET    | `/api/config`              | App config (secrets redacted)     |
+| GET    | `/api/filters`             | Saved filters                     |
+| POST   | `/api/filters`             | Create saved filter               |
+| DELETE | `/api/filters/:id`         | Delete saved filter               |
 
 ### Global middleware note
 
 Auto-registered routes bypass route-level middleware but are still subject to global/server middleware. If you have auth middleware (like `silentAuth`) registered globally, each polling request will trigger a DB query every few seconds.
 
 To avoid this, either:
+
 - Move auth middleware to a named route group instead of global middleware
-- Use the `shouldShow` callback for access control (recommended)
+- Use the `authorize` callback for access control (recommended)
 
 ---
 
@@ -423,10 +464,155 @@ Features:
 
 ---
 
+## React & Vue (Inertia.js) — Alpha
+
+> **Alpha feature.** The React and Vue integrations are new and may have rough edges. Bug reports and feedback are very welcome — please [open an issue](https://github.com/simulieren/adonisjs-server-stats/issues).
+
+If you're using **Inertia.js** with React or Vue instead of Edge templates, you can drop in the same stats bar, debug panel, and dashboard as fully native components. Same data, same styling, same features — just framework-native.
+
+### Install
+
+No extra packages needed. The components ship inside the main package:
+
+```bash
+npm install adonisjs-server-stats
+```
+
+Peer dependencies (all optional — install what you use):
+
+```bash
+# React
+npm install react react-dom
+
+# Vue
+npm install vue
+
+# Real-time updates (optional — falls back to polling)
+npm install @adonisjs/transmit-client
+```
+
+### React
+
+```tsx
+import { ServerStatsBar, DebugPanel, DashboardPage } from 'adonisjs-server-stats/react'
+import 'adonisjs-server-stats/react/css'
+
+// Stats bar — drop into your layout
+<ServerStatsBar endpoint="/admin/api/server-stats" intervalMs={3000} />
+
+// Debug panel — same layout, add below the stats bar
+<DebugPanel endpoint="/admin/api/debug" />
+
+// Dashboard — use as a full Inertia page
+<DashboardPage endpoint="/__stats/api" />
+```
+
+Available hooks:
+
+```tsx
+import {
+  useServerStats,
+  useDebugData,
+  useDashboardData,
+  useTheme,
+  useFeatures,
+} from 'adonisjs-server-stats/react'
+```
+
+### Vue
+
+```vue
+<script setup>
+import { ServerStatsBar, DebugPanel, DashboardPage } from 'adonisjs-server-stats/vue'
+import 'adonisjs-server-stats/vue/css'
+</script>
+
+<template>
+  <!-- Stats bar — drop into your layout -->
+  <ServerStatsBar endpoint="/admin/api/server-stats" :interval-ms="3000" />
+
+  <!-- Debug panel -->
+  <DebugPanel endpoint="/admin/api/debug" />
+
+  <!-- Dashboard — use as a full Inertia page -->
+  <DashboardPage endpoint="/__stats/api" />
+</template>
+```
+
+Available composables:
+
+```ts
+import {
+  useServerStats,
+  useDebugData,
+  useDashboardData,
+  useTheme,
+  useFeatures,
+} from 'adonisjs-server-stats/vue'
+```
+
+### Shared building blocks (React)
+
+For advanced composition, React also exports lower-level UI primitives:
+
+```tsx
+import {
+  ThemeToggle,
+  Badge,
+  MethodBadge,
+  StatusBadge,
+  JsonViewer,
+  Tooltip,
+} from 'adonisjs-server-stats/react'
+```
+
+### Auth & visibility
+
+The components auto-detect your auth setup:
+
+- **Cookie auth** (default Inertia setup) — requests use `credentials: 'include'` automatically
+- **Bearer token** — pass `authToken` as a prop to any component
+
+The same `authorize` callback you configure on the server gates all API routes. If a user isn't authorized, the components detect the 403 and hide themselves.
+
+### Real-time updates
+
+If `@adonisjs/transmit-client` is installed, the stats bar subscribes to SSE for instant updates. Otherwise it falls back to polling at the configured interval. No configuration needed — it just works.
+
+### Theme support
+
+The React and Vue components share the same theme system as Edge. Dark/light preference syncs across all three UIs via `localStorage`, including cross-tab sync.
+
+### Known limitations (alpha)
+
+- The dashboard page is large — lazy-loading helps but initial bundle may be significant
+- Some edge cases in custom pane rendering may not be fully covered yet
+- Error boundaries are minimal — a bad API response may cause a blank panel
+- Only tested with React 18+ and Vue 3.3+
+
+Found a bug? Have feedback? [Open an issue](https://github.com/simulieren/adonisjs-server-stats/issues) — it helps a lot.
+
+---
+
 ## Dev Toolbar
 
 Adds a debug panel with SQL query inspection, event tracking, email capture with HTML preview, route table, live logs, and per-request tracing. Only active in non-production environments.
 
+```ts
+export default defineConfig({
+  toolbar: {
+    slowQueryThreshold: 100,
+    tracing: true,
+    persist: true,
+  },
+})
+```
+
+Debug routes are auto-registered by the package at `/admin/api/debug/*` (configurable via `advanced.debugEndpoint`).
+
+<details>
+<summary>Legacy format (deprecated)</summary>
+
 ```ts
 export default defineConfig({
   devToolbar: {
@@ -435,13 +621,13 @@ export default defineConfig({
     maxEvents: 200,
     maxEmails: 100,
     slowQueryThresholdMs: 100,
-    persistDebugData: true, // or a custom path: 'custom/debug.json'
-    tracing: true, // enable per-request timeline
+    persistDebugData: true,
+    tracing: true,
   },
 })
 ```
 
-Debug routes are auto-registered by the package at `/admin/api/debug/*` (configurable via `debugEndpoint`).
+</details>
 
 ### Built-in Emails Tab
 
@@ -459,7 +645,7 @@ The debug toolbar captures all emails sent via AdonisJS mail (`mail:sending`, `m
 
 ### Persistent Debug Data
 
-Enable `persistDebugData: true` to save queries, events, and emails to `.adonisjs/server-stats/debug-data.json`. You can also pass a custom path (relative to app root) like `persistDebugData: 'custom/debug.json'`. Data is:
+Enable `toolbar.persist: true` (or the legacy `devToolbar.persistDebugData: true`) to save queries, events, and emails to `.adonisjs/server-stats/debug-data.json`. You can customize the path via `advanced.persistPath`. Data is:
 
 - **Loaded** on server startup (before collectors start)
 - **Flushed** every 30 seconds (handles crashes)
@@ -530,37 +716,28 @@ If `better-sqlite3` is not installed, the dashboard will log a helpful message a
 ```ts
 // config/server_stats.ts
 export default defineConfig({
-  devToolbar: {
-    enabled: true,
-    dashboard: true,
-  },
+  dashboard: true,
 })
 ```
 
-Restart your dev server and visit **`/__stats`** (or your configured `dashboardPath`).
+Restart your dev server and visit **`/__stats`** (or your configured `dashboard.path`).
 
 #### Configuration
 
 ```ts
-devToolbar: {
-  enabled: true,
-  dashboard: true,
-
-  // URL path for the dashboard (default: '/__stats')
-  dashboardPath: '/__stats',
-
-  // Days to retain historical data (default: 7)
-  retentionDays: 7,
-
-  // SQLite database file path, relative to app root (default: '.adonisjs/server-stats/dashboard.sqlite3')
-  dbPath: '.adonisjs/server-stats/dashboard.sqlite3',
-
-  // URL prefixes to exclude from tracing and dashboard persistence (default: [])
-  excludeFromTracing: ['/admin/api/debug'],
-
-  // Enable tracing for per-request timeline in the dashboard (recommended)
-  tracing: true,
-}
+export default defineConfig({
+  dashboard: {
+    path: '/__stats',
+    retentionDays: 7,
+  },
+  toolbar: {
+    tracing: true,
+    excludeFromTracing: ['/admin/api/debug'],
+  },
+  advanced: {
+    dbPath: '.adonisjs/server-stats/dashboard.sqlite3',
+  },
+})
 ```
 
 #### Dashboard Sections
@@ -581,15 +758,12 @@ devToolbar: {
 
 #### Access Control
 
-The dashboard reuses the `shouldShow` callback from the main config. If set, all dashboard routes are gated by it -- unauthorized requests receive a 403.
+The dashboard reuses the `authorize` callback from the main config. If set, all dashboard routes are gated by it -- unauthorized requests receive a 403.
 
 ```ts
 export default defineConfig({
-  shouldShow: (ctx) => ctx.auth?.user?.role === 'admin',
-  devToolbar: {
-    enabled: true,
-    dashboard: true,
-  },
+  authorize: (ctx) => ctx.auth?.user?.role === 'admin',
+  dashboard: true,
 })
 ```
 
@@ -613,7 +787,7 @@ The dashboard uses a dedicated SQLite database (separate from your app's databas
 - **Self-cleaning** -- old data is automatically purged based on `retentionDays`
 - **WAL mode** -- concurrent reads don't block writes
 
-The SQLite file is created at the configured `dbPath` (default: `.adonisjs/server-stats/dashboard.sqlite3`). Add it to your `.gitignore`:
+The SQLite file is created at the configured `advanced.dbPath` (default: `.adonisjs/server-stats/dashboard.sqlite3`). Add it to your `.gitignore`:
 
 ```
 .adonisjs/server-stats/
@@ -661,8 +835,7 @@ const webhooksPane: DebugPane = {
 }
 
 export default defineConfig({
-  devToolbar: {
-    enabled: true,
+  toolbar: {
     panes: [webhooksPane],
   },
 })
@@ -773,10 +946,14 @@ All types are exported for consumer use:
 import type {
   ServerStats,
   ServerStatsConfig,
+  ResolvedServerStatsConfig,
   MetricCollector,
   MetricValue,
   LogStats,
   DevToolbarOptions,
+  ToolbarConfig,
+  DashboardConfig,
+  AdvancedConfig,
 } from 'adonisjs-server-stats'
 
 // Debug types
@@ -827,16 +1004,19 @@ import type {
 
 All integrations use lazy `import()` -- missing peer deps won't crash the app. The corresponding collector simply returns defaults.
 
-| Dependency                  | Required By                                   |
-| --------------------------- | --------------------------------------------- |
-| `@adonisjs/core`            | Everything (required)                         |
-| `@adonisjs/lucid`           | `dbPoolCollector`, `appCollector`, dashboard  |
-| `@adonisjs/redis`           | `redisCollector`, dashboard cache inspector   |
-| `@adonisjs/transmit`        | Provider (SSE broadcast), dashboard real-time |
-| `@julr/adonisjs-prometheus` | `serverStatsCollector`                        |
-| `bullmq`                    | `queueCollector`                              |
-| `better-sqlite3`            | Dashboard (`dashboard: true`)                 |
-| `edge.js`                   | Edge tag                                      |
+| Dependency                  | Required By                                         |
+| --------------------------- | --------------------------------------------------- |
+| `@adonisjs/core`            | Everything (required)                               |
+| `@adonisjs/lucid`           | `dbPoolCollector`, `appCollector`, dashboard        |
+| `@adonisjs/redis`           | `redisCollector`, dashboard cache inspector         |
+| `@adonisjs/transmit`        | Provider (SSE broadcast), dashboard real-time       |
+| `@adonisjs/transmit-client` | React/Vue real-time updates (falls back to polling) |
+| `@julr/adonisjs-prometheus` | `serverStatsCollector`                              |
+| `bullmq`                    | `queueCollector`                                    |
+| `better-sqlite3`            | Dashboard (`dashboard: true`)                       |
+| `edge.js`                   | Edge tag                                            |
+| `react`, `react-dom`        | React components (alpha)                            |
+| `vue`                       | Vue components (alpha)                              |
 
 ## License