Sentry

The starter kit includes a Sentry integration for client, server and edge error tracking. It remains inactive in development and when NEXT_PUBLIC_SENTRY_DSN is not configured.

Setup

1. Create a Sentry Account

1. Go to sentry.io and create an account
2. Create a new project (select Next.js as the platform)
3. Copy your DSN (Data Source Name)

2. Configure Environment Variables

Add your Sentry credentials to your .env file:

NEXT_PUBLIC_SENTRY_DSN="https://xxxxx@xxxxx.ingest.sentry.io/xxxxx"
SENTRY_ORG="your-org"
SENTRY_PROJECT="your-project"
SENTRY_AUTH_TOKEN="sntrys_xxxxx"

3. Verify Configuration

Sentry is automatically configured in instrumentation.ts, instrumentation-server.ts, instrumentation-edge.ts, and instrumentation-client.ts. The configuration includes:

• Automatic error capture for client and server
• Performance monitoring
• Production source map uploads through withSentryConfig in next.config.ts
• User and request context for tRPC procedures

Automatic Instrumentation

Sentry is pre-configured to automatically capture:

Client-Side

• Unhandled JavaScript exceptions
• Unhandled promise rejections
• React component errors (via Error Boundaries)
• Performance metrics (Core Web Vitals)
• User session replays (optional)

Server-Side

• API route errors
• Server component errors
• Server action errors
• tRPC procedure errors (via Sentry tRPC middleware)
• Database query errors

tRPC Integration

The starter kit uses the Sentry tRPC middleware to automatically capture errors and performance metrics from all tRPC procedures. The middleware is configured in your tRPC setup and automatically:

• Captures all tRPC procedure errors with full context
• Tracks procedure execution time and performance
• Associates errors with the procedure path and input parameters
• Includes user context when available

The middleware is automatically applied to all procedures, so you don't need to manually instrument your tRPC endpoints.

Manual Error Tracking

Capture Errors

You can manually capture errors in your code:

import * as Sentry from '@sentry/nextjs';

try {
  // Your code
} catch (error) {
  Sentry.captureException(error, {
    tags: {
      section: 'billing'
    },
    extra: {
      userId: user.id,
      amount: 100
    }
  });
  throw error;
}

Capture Messages

Log important events:

import * as Sentry from '@sentry/nextjs';

Sentry.captureMessage('Payment processed', {
  level: 'info',
  tags: {
    feature: 'billing'
  }
});

Set User Context

Associate errors with users:

import * as Sentry from '@sentry/nextjs';

export function setSentryUser(user: { id: string; email: string }) {
  Sentry.setUser({
    id: user.id,
    email: user.email
  });
}

Performance Monitoring

Sentry automatically tracks:

• Page Load Performance - Time to first byte, first contentful paint
• API Route Performance - Response times for API routes
• Core Web Vitals - LCP, FID, CLS metrics

Custom Performance Monitoring

Track custom operations using startSpan:

import * as Sentry from '@sentry/nextjs';

await Sentry.startSpan(
  {
    name: 'Process Payment',
    op: 'payment'
  },
  async () => {
    // Your payment processing code
    await processPayment();
  }
);

Source Maps

Source maps are automatically uploaded during build to provide readable stack traces in production.

Configuration

Source maps are configured by withSentryConfig in next.config.ts. During a production Vercel or CI build, the configuration:

1. Generates source maps during build
2. Uploads them to Sentry (if SENTRY_AUTH_TOKEN, SENTRY_ORG, and SENTRY_PROJECT are set)
3. Associates them with releases

Releases

Releases help you track which version of your code caused an error. They are automatically configured in the instrumentation files:

import { init } from '@sentry/nextjs';

import { env } from '@/lib/env';

init({
  dsn: env.NEXT_PUBLIC_SENTRY_DSN,
  environment: process.env.NODE_ENV
  // Release is automatically set by @sentry/nextjs from Vercel environment variables
});

Session Replay

Session Replay is already enabled in instrumentation-client.ts when Sentry is active. The shipped sample rates capture 10% of ordinary sessions and 100% of sessions containing an error:

import { init, replayIntegration } from '@sentry/nextjs';

init({
  dsn: process.env.NEXT_PUBLIC_SENTRY_DSN,
  integrations: [replayIntegration()],
  replaysSessionSampleRate: 0.1,
  replaysOnErrorSampleRate: 1.0
});

Filtering Errors

The starter kit already includes error filtering in instrumentation-server.ts and instrumentation-edge.ts. You can customize it:

import { init } from '@sentry/nextjs';

import { env } from '@/lib/env';

init({
  dsn: env.NEXT_PUBLIC_SENTRY_DSN,
  beforeSend(event) {
    // Filter out specific errors
    const exception = event.exception?.values?.[0];
    if (exception?.value?.includes('ResizeObserver')) {
      return null; // Don't send this error
    }
    return event;
  }
});

Environment-Specific Configuration

Sentry is automatically disabled in development. The configuration in instrumentation-server.ts and instrumentation-edge.ts includes:

• Automatic disabling in development mode
• Sample rate of 0.1 (10%) for performance traces
• Error filtering for common noisy errors (TRPCError NOT_FOUND, ChunkLoadError, network errors)

Best Practices

1. Set appropriate sample rates - Use lower sample rates in production to reduce costs
2. Filter sensitive data - Don't send passwords, tokens, or PII
3. Use tags - Add tags to categorize errors (e.g., feature: "billing")
4. Set user context - Always set user context for better error tracking
5. Monitor performance - Track slow operations and optimize them
6. Review errors regularly - Set up alerts for critical errors