Configuration Options

All configuration is optional. LoadFlux works with zero config using sensible defaults.

LoadFluxConfig

interface LoadFluxConfig {
  path?: string;
  framework?: "express" | "fastify";
  database?: {
    adapter?: "sqlite" | "mongodb";
    connectionString?: string;
  };
  auth?: {
    username: string;
    password: string;
  };
  collection?: {
    systemInterval?: number;
    aggregationWindow?: number;
  };
  retention?: {
    days?: number;
    cronExpression?: string;
  };
  slowRequestThreshold?: number;
  excludeRoutes?: string[];
  /** Skip mounting LoadFlux when the resolved listen host is loopback */
  disableOnLocalhost?: boolean;
  /** Server bind host; used with `disableOnLocalhost` (env: `LOADFLUX_LISTEN_HOST`, `HOST`) */
  listenHost?: string;
  /** Use `X-Forwarded-For` for login rate limiting (env: `LOADFLUX_TRUST_PROXY`) */
  trustProxy?: boolean;
}

Options reference

path

Type	string
Default	"/loadflux"

The URL path where the dashboard is served. Must start with /.

loadflux({ path: "/monitor" })
// Dashboard at http://localhost:3000/monitor

framework

Type	"express" | "fastify"
Default	Auto-detected

You don't need to set this — it's automatically set by loadflux() (Express) or loadfluxFastify() (Fastify).

database

Type	{ adapter?: string; connectionString?: string }

database.adapter

Type	"sqlite" | "mongodb"
Default	"sqlite"

database.connectionString

Type	string
Default	"./loadflux.db" (SQLite) or "mongodb://localhost:27017/loadflux" (MongoDB)

For SQLite, this is the file path. For MongoDB, this is the connection URI.

auth

Type	{ username: string; password: string } | undefined
Default	undefined

When set, the dashboard requires login. Credentials are hashed with bcrypt and stored in the database. If the password changes between server restarts (e.g., updated in .env), LoadFlux automatically syncs the hash on startup.

When not set, the dashboard shows a setup prompt on first visit.

collection.systemInterval

Type	number (milliseconds)
Default	5000
Minimum	1000

How often system metrics (CPU, RAM, disk, network) are collected.

collection.aggregationWindow

Type	number (milliseconds)
Default	5000
Minimum	1000

How often buffered request metrics are flushed to the database. During each flush, percentiles (p50/p90/p95/p99) are computed in-memory.

retention.days

Type	number
Default	90
Minimum	1

Number of days to keep metrics data. A daily cron job deletes older records.

retention.cronExpression

Type	string (cron expression)
Default	"0 2 * * *" (2:00 AM daily)

When the retention cleanup runs.

slowRequestThreshold

Type	number (milliseconds)
Default	500
Minimum	0

Requests exceeding this duration appear in the "Slow Requests" section.

excludeRoutes

Type	string[]
Default	[]

URL paths to exclude from metrics collection. Useful for health checks or internal routes.

Supports:

• Exact matches: the path must match exactly.
• Prefix patterns: any entry ending with * is treated as startsWith on the URL path.

loadflux({
  excludeRoutes: [
    "/health",                  // exact match
    "/ready",                   // exact match
    "/documentation/*",         // excludes /documentation, /documentation/api, /documentation/v1/...
    "/.well-known/acme-challenge", // exact match
  ],
})

disableOnLocalhost

Type	boolean
Default	false

When true, LoadFlux does not register middleware or routes if the resolved listen host is a loopback address (127.0.0.1, ::1, localhost, etc.). Use this so local development servers do not expose the dashboard.

The listen host is taken from listenHost in config, then LOADFLUX_LISTEN_HOST, then HOST, in that order. It should match the host you pass to app.listen(...).

listenHost

Type	string
Default	From LOADFLUX_LISTEN_HOST or HOST, else unset

Explicit bind host of your HTTP server. Only needed for disableOnLocalhost (and should mirror your real listen address).

trustProxy

Type	boolean
Default	false

When true, login rate limiting uses the client IP from X-Forwarded-For (first hop). Enable only behind a trusted reverse proxy that sets this header correctly. You can also set LOADFLUX_TRUST_PROXY=1.

Full example with all options

app.use(loadflux({
  path: "/monitor",
  database: {
    adapter: "sqlite",
    connectionString: "./data/monitoring.db",
  },
  auth: {
    username: "admin",
    password: "secure-password",
  },
  collection: {
    systemInterval: 10000,     // collect system metrics every 10s
    aggregationWindow: 5000,   // flush request metrics every 5s
  },
  retention: {
    days: 30,                  // keep 30 days of data
    cronExpression: "0 3 * * *", // clean up at 3 AM
  },
  slowRequestThreshold: 1000, // flag requests > 1 second
  excludeRoutes: ["/health", "/ready", "/documentation/*"],
  disableOnLocalhost: true,
  listenHost: "0.0.0.0", // must match app.listen host when using disableOnLocalhost
  trustProxy: true, // only behind a trusted reverse proxy
}));