Set up Overseer in your Next.js application

Next.js Integration

Overseer provides a dedicated Next.js integration with automatic error boundary integration and server-side error tracking.

Installation

npm install @codmir/overseer

yarn add @codmir/overseer

pnpm add @codmir/overseer

bun add @codmir/overseer

Client-Side Setup

Create instrumentation-client.ts in your src/ directory:

// src/instrumentation-client.ts
import * as Overseer from '@codmir/overseer/nextjs';

Overseer.init({
  dsn: process.env.NEXT_PUBLIC_OVERSEER_DSN,
  environment: process.env.NODE_ENV,
  release: process.env.NEXT_PUBLIC_APP_VERSION,
  
  // Session replay sampling
  replaysSessionSampleRate: 0.1,  // 10% of sessions
  replaysOnErrorSampleRate: 1.0,  // 100% of sessions with errors
  
  // Debug mode in development
  debug: process.env.NODE_ENV === 'development',
  
  // Filter noisy errors
  beforeSend(event) {
    // Skip hydration errors
    if (event.message?.includes('Hydration')) {
      return null;
    }
    return event;
  },
});

// Export for use in components
export { captureException, captureMessage, setUser } from '@codmir/overseer/nextjs';

Server-Side Setup

Create instrumentation.ts for server-side error tracking:

// src/instrumentation.ts
export async function register() {
  console.log('[Overseer] Server instrumentation registered');
}

export const onRequestError = async (
  error: Error,
  request: { method?: string; url?: string },
  context?: { routePath?: string }
) => {
  console.error('[Overseer] Request error:', error.message);
  
  // Report to Overseer API
  await fetch(`${process.env.NEXT_PUBLIC_APP_URL}/api/error-report`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      message: error.message,
      stack: error.stack,
      url: request.url,
      page: context?.routePath,
    }),
  });
};

Error Boundary

Update your app/error.tsx to report errors:

'use client';

import { useEffect } from 'react';
import { captureException } from '../instrumentation-client';

export default function Error({
  error,
  reset,
}: {
  error: Error & { digest?: string };
  reset: () => void;
}) {
  useEffect(() => {
    captureException(error);
  }, [error]);

  return (
    <div className="flex flex-col items-center justify-center min-h-screen">
      <h2>Something went wrong!</h2>
      <p className="text-muted-foreground">{error.message}</p>
      {error.digest && (
        <code className="text-xs mt-2">Reference: {error.digest}</code>
      )}
      <button onClick={reset} className="mt-4 btn">
        Try again
      </button>
    </div>
  );
}

Global Error Boundary

For critical errors, update app/global-error.tsx:

'use client';

import { useEffect } from 'react';
import { captureException } from '../instrumentation-client';

export default function GlobalError({
  error,
  reset,
}: {
  error: Error & { digest?: string };
  reset: () => void;
}) {
  useEffect(() => {
    captureException(error);
  }, [error]);

  return (
    <html>
      <body>
        <h2>Something went wrong!</h2>
        <button onClick={reset}>Try again</button>
      </body>
    </html>
  );
}

Usage in Components

'use client';

import { captureException, addBreadcrumb, setUser } from '@codmir/overseer/nextjs';

export function CheckoutButton({ user }: { user: User }) {
  // Set user context
  useEffect(() => {
    setUser({ id: user.id, email: user.email });
  }, [user]);

  const handleClick = async () => {
    // Add breadcrumb
    addBreadcrumb({
      category: 'checkout',
      message: 'User clicked checkout',
      level: 'info',
    });

    try {
      await processCheckout();
    } catch (error) {
      captureException(error, {
        tags: { feature: 'checkout' },
        extra: { cartTotal: cart.total },
      });
    }
  };

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

Environment Variables

# .env.local
NEXT_PUBLIC_OVERSEER_DSN=/api/overseer
NEXT_PUBLIC_OVERSEER_ENABLED=true
NEXT_PUBLIC_APP_VERSION=1.0.0

Configuration Options

Option	Type	Default	Description
`dsn`	string	-	Overseer endpoint URL
`environment`	string	-	Environment name (production, staging, development)
`release`	string	-	App version for release tracking
`replaysSessionSampleRate`	number	0.1	Percentage of sessions to record (0-1)
`replaysOnErrorSampleRate`	number	1.0	Percentage of error sessions to record (0-1)
`debug`	boolean	false	Enable debug logging
`beforeSend`	function	-	Filter or modify events before sending
`enabled`	boolean	true	Enable/disable the SDK