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) => void	Log a discrete event
start	(options: StartOptions) => void	Start a timing measurement
end	(options: EndOptions) => void	End a timing measurement
init	(options: SimpleLogsConfig) => void	Configure the SDK
flush	() => Promise<void>	Flush all pending entries

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

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) => void	Log a discrete event
start	(options: StartOptions) => void	Start a timing measurement
end	(options: EndOptions) => 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>;
}

StartOptions

// Normal start — key optional
type StartOptionsNormal = {
  touchpoint?: string;
  metadata?: Record<string, unknown>;
  key?: string;
  standalone?: false;
};

// Standalone start — key required
type StartOptionsStandalone = {
  key: string;
  standalone: true;
  touchpoint?: string;
  metadata?: Record<string, unknown>;
};

type StartOptions = StartOptionsNormal | StartOptionsStandalone;

EndOptions

interface EndOptions {
  key?: string;
  touchpoint?: string;
  metadata?: Record<string, unknown>;
}

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;
};

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;
}