AdonisJS Server Stats

1.12.3 verified Fri May 01 auth: no javascript

Current stable version 1.12.3. Real-time server monitoring and debug toolbar for AdonisJS v6/v7 applications, inspired by Laravel Telescope. Provides live CPU, memory, requests/sec, database pool, Redis, queue, and log stats via a single Edge component (`@serverStats()`). Includes a full debug toolbar with SQL query inspection, event tracing, route listing, log tailing, and custom panels. Ships TypeScript types and integrates with Lucid ORM, Redis, BullMQ, and Edge templates. Zero frontend dependencies; also offers alpha React/Vue components for Inertia.js. Peer dependencies span multiple major versions (e.g., @adonisjs/core ^6.0.0 || ^7.0.0).

Common errors

error Cannot find module 'adonisjs-server-stats' or its corresponding type declarations. ↓

cause Missing peer dependencies or incorrect installation.

fix

Run node ace add adonisjs-server-stats to install peer deps automatically.

error Edge tag not rendered: `@serverStats()` is unknown. ↓

cause Middleware not registered or package not configured.

fix

Register the middleware in start/kernel.ts: import serverStatsMiddleware from 'adonisjs-server-stats/edge'; and add it to server middleware stack.

error TypeError: configure is not a function ↓

cause Incorrect import path for configure function.

fix

Change import to import { configure } from 'adonisjs-server-stats/configure'.

Warnings

breaking v1.0.0 changed the import path for configure to subpath 'adonisjs-server-stats/configure' instead of root. ↓

fix Use 'adonisjs-server-stats/configure' for configure imports.

deprecated Use of `@serverStats({ collector: 'sqlite' })` option is deprecated; use database config instead. ↓

fix Remove the collector option and rely on the database config block.

gotcha The toolbar only shows for requests with IP in the authorization array (defaults to 127.0.0.1). In production, you must set AUTHORIZED_IPS env or configure authorization. ↓

fix Set AUTHORIZED_IPS=your-ip in .env or add to config/server-stats.ts authorization array.

gotcha Slow query logging requires a running database connection; if no connection is established, the queries panel may appear empty. ↓

fix Ensure your database driver (e.g., better-sqlite3) is installed and configured in config/database.ts.

Install

npm install adonisjs-server-stats

yarn add adonisjs-server-stats

pnpm add adonisjs-server-stats

Imports

configure
wrong
```
import { configure } from 'adonisjs-server-stats'
```
correct
```
import { configure } from 'adonisjs-server-stats/configure'
```
The configure function is exported from the configure subpath. Direct import from root won't work.

serverStatsMiddleware

wrong

import { serverStatsMiddleware } from 'adonisjs-server-stats'

correct

import serverStatsMiddleware from 'adonisjs-server-stats/edge'

The middleware is registered as an Edge tag; import the default export from the 'edge' subpath.

ServerStatsCollectorOptions

wrong

import { ServerStatsCollectorOptions } from 'adonisjs-server-stats'

correct

import type { ServerStatsCollectorOptions } from 'adonisjs-server-stats/types'

Type imports should use the 'types' subpath for proper TypeScript support.

Quickstart

Basic setup: install via Ace, configure in config file, and render toolbar in Edge layout.

// Install: node ace add adonisjs-server-stats
// Configure in config/server-stats.ts:
import { defineConfig } from 'adonisjs-server-stats'
export default defineConfig({
  enabled: true,
  authorization: ['127.0.0.1'],
  collect: {
    requests: true,
    database: true,
    redis: true,
    queue: true,
    logs: true,
  },
  queries: {
    slowQueryThreshold: 100,
  },
})
// In layout edge template:
@serverStats()
// Then visit your app; toolbar appears for localhost requests.