Skip to main content

Quickstart

This guide gets you from zero to sending logs in under 5 minutes using @simplelogs/next with the recommended Provider pattern.

1. Install and configure​

Follow the Installation guide to install the package and set your environment variables.

2. Add the provider to your root layout​

Open app/layout.tsx and wrap your application with SimpleLogsProvider. The provider handles both server-side and client-side initialization in one step.

app/layout.tsx
import { SimpleLogsProvider } from '@simplelogs/next';

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <SimpleLogsProvider
          config={{
            serverKey: process.env.SIMPLELOGS_SERVER_KEY!,
            clientKey: process.env.SIMPLELOGS_CLIENT_KEY!,
          }}
        >
          {children}
        </SimpleLogsProvider>
      </body>
    </html>
  );
}

3. Log from a server component​

app/dashboard/page.tsx
import { serverLogger } from '@simplelogs/next/server';

export default async function DashboardPage() {
  await serverLogger.log({
    touchpoint: 'app/dashboard/load',
    message: 'Dashboard page loaded',
    level: 'info',
    metadata: { userId: 'user_123' },
  });

  return <div>Dashboard</div>;
}
info

serverLogger methods are async — always await them. See Server Logging → A note on awaiting.

4. Log from a client component​

components/CheckoutButton.tsx
'use client';

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

export function CheckoutButton() {
  const logger = useSimpleLogs();

  function handleClick() {
    logger.log({
      touchpoint: 'ui/checkout/button-clicked',
      message: 'Checkout button clicked',
      level: 'info',
    });
  }

  return <button onClick={handleClick}>Checkout</button>;
}

5. Measure timing​

app/actions/submit-order.ts
'use server';

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

export async function submitOrder(formData: FormData) {
  await serverLogger.start({ touchpoint: 'api/orders/submit' });

  try {
    await processOrder(formData);
    await serverLogger.end({
      touchpoint: 'api/orders/submit',
      metadata: { success: true },
    });
  } catch (error) {
    await serverLogger.end({
      touchpoint: 'api/orders/submit',
      metadata: { success: false, error: String(error) },
    });
    throw error;
  }
}

Since submitOrder is a Server Action, this entry is automatically tagged with the same pageIdentifier/sessionIdentifier as the client-side click that invoked it — no extra code required. See Page & Session Correlation.

That's it​

Your logs and timings will appear in the SimpleLogs web app within seconds. Check the Log Explorer to see your first log events and Timing Performance to see your first timing measurements.

Example project​

The simplelogs-next-example repository is a minimal Next.js App Router app that demonstrates all four integration patterns side-by-side on a single page:

  1. Hook + Provider (inline init)
  2. Hook + Provider (separate <SimpleLogsClientInit />)
  3. No provider — manual SimpleLogs.init() in a client component
  4. Server-side logging from an API route with flushServer()

It also includes a ready-to-use simplelogs.config.json for local development. Clone it to get a working reference you can run immediately.

Next steps: