@logtide/nextjs

v0.5.6

Published

13 days ago

LogTide SDK integration for Next.js — auto error capture, request tracing, and performance spans

0High
0Medium
0Low

polliog

Features

Server-side request tracing with automatic span creation
Error capture via Next.js onRequestError hook
Client-side error boundary for React components
Navigation tracking as breadcrumbs
W3C Trace Context propagation (traceparent)
App Router & Pages Router support
Full TypeScript support with strict types

Installation

npm install @logtide/nextjs
# or
pnpm add @logtide/nextjs
# or
yarn add @logtide/nextjs

Quick Start

1. Server-side Setup

Create (or update) your instrumentation.ts at the project root:

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

export async function register() {
  await registerLogtide({
    dsn: 'https://[email protected]',
    // Or use apiUrl + apiKey instead of dsn:
    // apiUrl: 'https://your-instance.com',
    // apiKey: 'lp_your_key',
    service: 'my-nextjs-app',
    environment: process.env.NODE_ENV,
  });
}

export const onRequestError = captureRequestError;

2. Client-side Setup

Initialize LogTide in your root layout:

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

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

initLogtide({
  dsn: 'https://[email protected]',
  // Or use apiUrl + apiKey instead of dsn:
  // apiUrl: 'https://your-instance.com',
  // apiKey: 'lp_your_key',
  service: 'my-nextjs-app',
});

export default function RootLayout({ children }: { children: React.ReactNode }) {
  useEffect(() => trackNavigation(), []);

  return (
    <html>
      <body>{children}</body>
    </html>
  );
}

Server API

`registerLogtide(options)`

Initialize LogTide in Next.js instrumentation.ts. Automatically installs ConsoleIntegration and GlobalErrorIntegration.

import { registerLogtide } from '@logtide/nextjs/server';

await registerLogtide({
  dsn: 'https://lp_key@host',
  service: 'my-app',
  environment: 'production',
  release: '1.0.0',
});

`captureRequestError(error, request, context)`

Next.js onRequestError handler. Automatically captures errors with route context, HTTP metadata, and breadcrumbs.

import { captureRequestError } from '@logtide/nextjs/server';

// instrumentation.ts
export const onRequestError = captureRequestError;

Captured metadata includes:

route.path, route.kind, route.type
http.method, http.url
render.source (if available)

`instrumentRequest(request)`

Manually instrument a server-side request (creates a span and scope):

import { instrumentRequest, finishRequest } from '@logtide/nextjs/server';

const result = instrumentRequest({
  headers: new Headers(),
  method: 'GET',
  url: 'http://localhost:3000/api/data',
});

// ... handle request ...

finishRequest(result!.spanId, 200);

`finishRequest(spanId, statusCode)`

Finish a request span. Marks as error for 5xx status codes, ok otherwise.

Client API

`initLogtide(options)`

Initialize LogTide on the client side. Installs GlobalErrorIntegration for unhandledrejection events.

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

initLogtide({
  dsn: 'https://lp_key@host',
  service: 'my-app',
});

`trackNavigation()`

Track client-side navigation (pushState, replaceState, popstate) as breadcrumbs. Returns a cleanup function.

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

export default function Layout({ children }) {
  useEffect(() => trackNavigation(), []);
  return <>{children}</>;
}

Exports

// Main entry — re-exports both server and client
import { registerLogtide, captureRequestError } from '@logtide/nextjs';
import { initLogtide, trackNavigation } from '@logtide/nextjs';

// Server-specific
import { registerLogtide, captureRequestError, instrumentRequest, finishRequest } from '@logtide/nextjs/server';

// Client-specific
import { initLogtide, trackNavigation } from '@logtide/nextjs/client';

License

MIT License - see LICENSE for details.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme