API Reference

Complete reference for all exports from @simplelogs/next.

---

Main entry point

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

SimpleLogs

The unified logger singleton. Works in both server and client contexts by detecting the environment at call time.

Method	Signature	Description
log	(options: LogOptions) => Promise<void> | void	Log a discrete event
start	(options: StartOptions) => Promise<void> | void	Start a timing measurement
end	(options: EndOptions) => Promise<void> | void	End a timing measurement
init	(options: SimpleLogsConfig) => void	Configure the SDK
flush	() => Promise<void>	Flush all pending entries

info

log/start/end return a Promise when running on the server (correlation headers are read via next/headers() before the entry is queued) and resolve synchronously on the client. Always await these calls server-side — see Server Logging → A note on awaiting.

getPageIdentifier() / getSessionIdentifier()

function getPageIdentifier(): string | undefined;
function getSessionIdentifier(): string | undefined;

Return the current page/session correlation identifiers. undefined outside a browser context. See Page & Session Correlation.

SimpleLogsProvider

React Server Component that initializes the SDK for both server and client.

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

Props (SimpleLogsProviderProps)

Prop	Type	Default	Description
config	SimpleLogsConfig	required	SDK configuration
children	React.ReactNode	required	—
clientInit	boolean	true	Set to false to defer client initialization; place <SimpleLogsClientInit /> manually

SimpleLogsClientInit

Client component that triggers SDK initialization. Used when clientInit={false} on <SimpleLogsProvider>.

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

No props.

useSimpleLogs()

React hook that returns the client logger singleton.

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

const logger = useSimpleLogs();
// logger.log | logger.start | logger.end | logger.record | logger.flush | logger.init
// logger.getPageIdentifier | logger.getSessionIdentifier

configureSDK(options: SimpleLogsConfig)

Imperatively configure the SDK. Merges into existing config.

resetConfig()

Resets the SDK config to defaults. Primarily useful in tests.

---

Server entry point

import { ... } from '@simplelogs/next/server';

serverLogger

The server-side logger singleton.

Method	Signature	Description
log	(options: LogOptions) => Promise<void>	Log a discrete event
start	(options: StartOptions) => Promise<void>	Start a timing measurement
end	(options: EndOptions) => Promise<void>	End a timing measurement

flushServer(): Promise<void>

Flush all queued server-side entries immediately.

getServerQueueSize(): number

Returns the number of entries currently waiting to be sent.

---

Hooks entry point

import { ... } from '@simplelogs/next';
// hooks are exported from the main entry point

Hook	Description
usePageLoadTime(options?)	Measures navigation start → page load (or element appearance)
useComponentMountTime(options?)	Measures navigation start → component mount
useTimedCallback(cb, options?)	Wraps a callback to record its duration on each invocation
useWebVitals(options)	Observes a Core Web Vital via PerformanceObserver
useSimpleLogs()	Returns the client logger singleton

---

Types

import type {
  SimpleLogsConfig,
  LogOptions,
  StartOptions,
  EndOptions,
  LogEntry,
  TimingEntry,
  SDKConfig,
  ILogger,
} from '@simplelogs/next';

LogOptions

interface LogOptions {
  touchpoint?: string;
  key?: string;
  message?: string;
  level?: 'info' | 'warn' | 'error' | 'debug';
  metadata?: Record<string, unknown>;
  // Server-only correlation overrides — see Page & Session Correlation
  pageIdentifier?: string;
  sessionIdentifier?: string;
  requestHeaders?: Headers | Record<string, string | string[] | undefined>;
}

StartOptions

// Normal start — key optional
type StartOptionsNormal = {
  touchpoint?: string;
  metadata?: Record<string, unknown>;
  key?: string;
  standalone?: false;
  pageIdentifier?: string;
  sessionIdentifier?: string;
  requestHeaders?: Headers | Record<string, string | string[] | undefined>;
};

// Standalone start — key required
type StartOptionsStandalone = {
  key: string;
  standalone: true;
  touchpoint?: string;
  metadata?: Record<string, unknown>;
  pageIdentifier?: string;
  sessionIdentifier?: string;
  requestHeaders?: Headers | Record<string, string | string[] | undefined>;
};

type StartOptions = StartOptionsNormal | StartOptionsStandalone;

EndOptions

interface EndOptions {
  key?: string;
  touchpoint?: string;
  metadata?: Record<string, unknown>;
  // Server-only correlation overrides — see Page & Session Correlation
  pageIdentifier?: string;
  sessionIdentifier?: string;
  requestHeaders?: Headers | Record<string, string | string[] | undefined>;
}

RecordOptions

interface RecordOptions {
  startTime: number;     // Unix ms
  endTime: number;       // Unix ms
  duration: number;      // ms
  touchpoint?: string;
  key?: string;
  metadata?: Record<string, unknown>;
}

SimpleLogsConfig

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

See Page & Session Correlation → Configuration for sessionTimeout and autoPropagateHeaders.

LogEntry

interface LogEntry {
  key?: string;
  touchpoint?: string;
  message?: string;
  level: 'info' | 'warn' | 'error' | 'debug';
  timestamp: number;
  metadata?: Record<string, unknown>;
  duration?: number;
}

TimingEntry

interface TimingEntry {
  key?: string;
  touchpoint?: string;
  startTime: number;
  endTime?: number;
  duration?: number;
  metadata?: Record<string, unknown>;
  standalone?: boolean;
}