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 } from '@logtide/nextjs/server';

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 automatically enables Core Web Vitals collection, click breadcrumbs, and session tracking.

// 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 --apiKey YOUR_API_KEY

Core Web Vitals

LogTide automatically monitors Google's Core Web Vitals (LCP, FID, CLS, INP, TTFB) through the client-side initialization. You can view these metrics in the Metrics section of your dashboard.

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:

// This is handled automatically by registerLogtide().
// Server-side errors in API routes, Server Components, and Server Actions
// are captured with full request context including:
// - URL, method, headers
// - Route parameters
// - User context (if configured)
// - Breadcrumbs leading to the error

Error Boundary

Use LogtideErrorBoundary to capture client-side React errors:

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

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

export default function ErrorPage({
  error,
  reset,
}: {
  error: Error & { digest?: string };
  reset: () => void;
}) {
  return (
    <LogtideErrorBoundary error={error}>
      <div>
        <h2>Something went wrong</h2>
        <button onClick={reset}>Try again</button>
      </div>
    </LogtideErrorBoundary>
  );
}

Track client-side navigation events as breadcrumbs:

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

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

export function LogtideNavigationTracker() {
  const pathname = usePathname();

  useEffect(() => {
    trackNavigation(pathname);
  }, [pathname]);

  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(pathname)`	`/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.