Configuration

The SDK can be configured via environment variables, the <SimpleLogsProvider> config prop, or the configureSDK() function. Environment variables take the highest priority.

Environment variables

Variable	Type	Default	Description
SIMPLELOGS_SERVER_KEY	string	—	Server API key. Never expose to the browser.
SIMPLELOGS_CLIENT_KEY	string	—	Client API key. Safe to use in browser code.
SIMPLELOGS_SERVERLESS	"true" | "false"	Auto-detected from VERCEL	Forces immediate-flush mode (no batching)
SIMPLELOGS_BATCH_INTERVAL	number (ms)	250	How long to wait before flushing a partial batch
SIMPLELOGS_MAX_BATCH_SIZE	number	100	Maximum entries per flush
SIMPLELOGS_FIRE_AND_FORGET	"true" | "false"	"true"	Client: use sendBeacon (true) or fetch (false)
SIMPLELOGS_DEBUG	"true" | "false"	"true" in dev	Enables verbose console output
SIMPLELOGS_STANDALONE_STARTS	"true" | "false"	"false"	Allows standalone timing starts without an explicit end()

Programmatic configuration

SimpleLogsConfig type

type SimpleLogsConfig = {
  serverKey?: string;
  clientKey?: string;
  serverless?: boolean;
  batchInterval?: number;    // ms
  maxBatchSize?: number;
  fireAndForget?: boolean;
  debug?: boolean;
  allowStandaloneStart?: boolean;
}

Via <SimpleLogsProvider>

<SimpleLogsProvider
  config={{
    serverKey: process.env.SIMPLELOGS_SERVER_KEY!,
    clientKey: process.env.SIMPLELOGS_CLIENT_KEY!,
    debug: false,
    batchInterval: 500,
    fireAndForget: false,
  }}
>
  {children}
</SimpleLogsProvider>

Via configureSDK()

import { configureSDK } from '@simplelogs/next';

configureSDK({
  serverKey: process.env.SIMPLELOGS_SERVER_KEY!,
  clientKey: process.env.NEXT_PUBLIC_SIMPLELOGS_CLIENT_KEY!,
  batchInterval: 500,
});

Via simplelogs.config.json

The server-side SDK reads a simplelogs.config.json file from the project root at module load time (when @simplelogs/next/server is first imported). This is the recommended home for non-secret, environment-specific tuning that you want to commit to version control.

When is this file read? Only on the server. The browser bundle does not load simplelogs.config.json — use configureSDK() or <SimpleLogsProvider config={...}> for client-side config.

All supported fields:

simplelogs.config.json

{
  "serverless": false,
  "batchInterval": 250,
  "maxBatchSize": 100,
  "fireAndForget": true,
  "debug": false,
  "allowStandaloneStart": false
}

Field	Typical value in prod	Typical value in dev/local	Notes
serverless	false (or omit; auto-detected on Vercel)	false	Set true on platforms without persistent processes
batchInterval	250	250	ms between flushes when queue isn't full
maxBatchSize	100	100	Flush early when this many entries are queued
fireAndForget	true	false	false re-queues failed sends; useful during local dev to catch failures
debug	false	true	Enables verbose console output
allowStandaloneStart	false	false	Allows start() without a matching end()

warning

Never put serverKey or clientKey in this file — they are secrets. Use environment variables for all API keys.

A typical local dev config (matches the example project):

simplelogs.config.json

{
  "serverless": false,
  "batchInterval": 250,
  "fireAndForget": false,
  "debug": false
}

Setting fireAndForget: false means the SDK uses fetch instead of sendBeacon, so failures surface as errors you can see during development.

Priority: environment variables override simplelogs.config.json values, which override SDK defaults. The full resolution order is:

1. SIMPLELOGS_* environment variables (highest)
2. configureSDK() / <SimpleLogsProvider config={...}>
3. simplelogs.config.json
4. SDK defaults (lowest)

Key rules

• serverKey — server-only; never pass to the browser
• clientKey — safe for browser use; restricted by origin allowlist
• If neither key is configured when the logger is first used, the SDK emits a warning and skips sending

Default behavior

Setting	Default	Notes
batchInterval	250 ms	Entries accumulate for 250 ms before flushing
maxBatchSize	100	A batch flushes early if it reaches 100 entries
fireAndForget	true	Client uses sendBeacon; no retry on failure
serverless	Auto	true on Vercel; flush immediately, no batching
debug	true in dev	false in production
allowStandaloneStart	false	start() requires a matching end() by default