Next.js SDK

@logtide/nextjs integrates LogTide with Next.js App Router. It provides server-side instrumentation, client-side error boundaries, Core Web Vitals collection, and session tracking.

Installation

npm install @logtide/nextjs

Server-Side Setup

Use Next.js instrumentation to initialize LogTide on the server. Create or update instrumentation.ts in your project root:

// instrumentation.ts
import { registerLogtide, captureRequestError } from '@logtide/nextjs/server';

export const onRequestError = captureRequestError;

export async function register() {
  if (process.env.NEXT_RUNTIME === 'nodejs') {
    registerLogtide({
      dsn: process.env.LOGTIDE_DSN!,
      service: 'nextjs-app-server',
      environment: process.env.NODE_ENV,
      release: process.env.NEXT_PUBLIC_APP_VERSION,
    });
  }
}

Enable the instrumentation hook in next.config.mjs or next.config.js:

// next.config.mjs
const nextConfig = {
  experimental: {
    instrumentationHook: true,
  },
};

export default nextConfig;

Client-Side Setup

Initialize LogTide on the client in your root layout. This enables click and network breadcrumbs, offline buffering, and session tracking (Core Web Vitals are opt-in, see below).

// app/layout.tsx
'use client';

import { initLogtide } from '@logtide/nextjs/client';

initLogtide({
  dsn: process.env.NEXT_PUBLIC_LOGTIDE_DSN!,
  environment: process.env.NODE_ENV,
  release: process.env.NEXT_PUBLIC_APP_VERSION,
});

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>{children}</body>
    </html>
  );
}

Source Maps (CLI)

To see original source code in your stack traces, upload your source maps during the build process. Next.js generates source maps in the .next/static/chunks directory.

# Install the CLI
npm install -g @logtide/cli

# Upload source maps after build
logtide sourcemaps upload --path ./.next/static/chunks --release 1.0.0 --api-key YOUR_API_KEY

Core Web Vitals

Core Web Vitals (LCP, INP, CLS) are opt-in: set browser.webVitals to true and install the optional web-vitals package. They are sent as info-level log events.

Session Tracking

LogTide correlates all client-side logs, errors, and performance metrics using a unique session_id. This allows you to trace the entire user journey leading up to an error.

Error Capture

The SDK automatically captures request errors in server components and route handlers via captureRequestError:

// Export captureRequestError as onRequestError in instrumentation.ts (see above).
// Server-side errors in API routes, Server Components, and Server Actions
// are then captured with request context including:
// - URL and method
// - Route path, kind, and type
// - Mechanism (e.g. react.server-component)
// - Breadcrumbs leading to the error

Error Boundary

Use LogtideErrorBoundary to capture client-side React errors:

// app/error-boundary.tsx
'use client';

import { LogtideErrorBoundary } from '@logtide/nextjs/client';

export function AppErrorBoundary({ children }: { children: React.ReactNode }) {
  return (
    <LogtideErrorBoundary fallback={<div>Something went wrong</div>}>
      {children}
    </LogtideErrorBoundary>
  );
}

Track client-side navigation events as breadcrumbs:

// app/providers.tsx
'use client';

import { trackNavigation } from '@logtide/nextjs/client';
import { useEffect } from 'react';

export function LogtideNavigationTracker() {
  useEffect(() => trackNavigation(), []);

  return null;
}

// app/layout.tsx
import { LogtideNavigationTracker } from './providers';

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body>
        <LogtideNavigationTracker />
        {children}
      </body>
    </html>
  );
}

Configuration

Environment variables for Next.js:

# .env.local

# Server-side DSN (not exposed to client)
LOGTIDE_DSN=https://[email protected]

# Client-side DSN (public, limited permissions)
NEXT_PUBLIC_LOGTIDE_DSN=https://[email protected]

# App version
NEXT_PUBLIC_APP_VERSION=1.0.0

API Reference

Export	Module	Description
`registerLogtide(options)`	`/server`	Initialize in instrumentation.ts, sets up captureRequestError
`initLogtide(options)`	`/client`	Initialize on the client side
`LogtideErrorBoundary`	`/client`	React error boundary that captures errors
`trackNavigation()`	`/client`	Track route changes as breadcrumbs
`captureRequestError`	`/server`	Automatic server error capture (set up by registerLogtide)

See the JavaScript SDK core docs for the full @logtide/core API.