Setting up Sentry

Sentry is a full-featured error tracking and performance monitoring platform. Makerkit includes built-in support for Sentry with automatic configuration for both client and server environments.

Install the Sentry SDK

Install the Sentry Next.js SDK in your web application:

pnpm add @sentry/nextjs --filter web

Configure Environment Variables

Add these environment variables:

NEXT_PUBLIC_MONITORING_PROVIDER=sentry
NEXT_PUBLIC_SENTRY_DSN=https://your-dsn@sentry.io/project-id

You can find your DSN in the Sentry dashboard:

1. Go to Settings → Projects → Select your project
2. Click Client Keys (DSN)
3. Copy the DSN value

Optional Environment Variables

# Environment name (defaults to VERCEL_ENV if on Vercel)
NEXT_PUBLIC_SENTRY_ENVIRONMENT=production
# Release version for source maps (set in CI)
SENTRY_RELEASE=1.0.0
# Auth token for uploading source maps (set in CI)
SENTRY_AUTH_TOKEN=your-auth-token

Update Next.js Configuration

Wrap your Next.js configuration with the Sentry configuration:

import { withSentryConfig } from '@sentry/nextjs';
const nextConfig = {
  // Your existing Next.js config
};
export default withSentryConfig(nextConfig);

This enables Sentry's build-time instrumentation and source map uploading.

Upload Source Maps

Source maps help Sentry display readable stack traces instead of minified code. Configure source map uploading for production builds:

import { withSentryConfig } from '@sentry/nextjs';
const IS_PRODUCTION = process.env.NODE_ENV === 'production';
const nextConfig = {
  // Your existing config
};
export default withSentryConfig(nextConfig, {
  org: 'your-sentry-org',
  project: 'your-sentry-project',
  // Auth token for uploading source maps
  authToken: process.env.SENTRY_AUTH_TOKEN,
  // Suppress logs in development
  silent: !IS_PRODUCTION,
  // Recommended settings
  widenClientFileUpload: true,
  autoInstrumentServerFunctions: false,
});

Add SENTRY_AUTH_TOKEN to your CI environment variables. Generate a token in Sentry:

1. Go to Settings → Auth Tokens
2. Click Create New Token
3. Select scopes: project:releases, org:read
4. Copy the token to your CI secrets

Performance Monitoring

Sentry captures performance data automatically. The default configuration includes:

{
  // Capture 100% of transactions (adjust in production)
  tracesSampleRate: 1.0,
  // Capture session replay for 10% of sessions
  replaysSessionSampleRate: 0.1,
  // Capture session replay for 100% of error sessions
  replaysOnErrorSampleRate: 1.0,
}

For high-traffic applications, reduce tracesSampleRate:

{
  // Capture 10% of transactions in production
  tracesSampleRate: process.env.NODE_ENV === 'production' ? 0.1 : 1.0,
}

How It Works

When Sentry is configured, Makerkit's monitoring system:

1. Initializes Sentry automatically on the client and server
2. Captures exceptions through the onRequestError instrumentation hook
3. Associates errors with users when identifyUser is called
4. Uploads source maps during production builds

The SentryMonitoringService handles environment detection and initializes the appropriate Sentry client:

// Browser environment
if (typeof document !== 'undefined') {
  initializeSentryBrowserClient({ environment });
}
// Server environment
else {
  initializeSentryServerClient({ environment });
}

Verifying Your Setup

After configuring Sentry:

1. Trigger a test error - Add a button that throws an error
2. Check the Sentry dashboard - The error should appear within seconds
3. Verify source maps - Stack traces should show readable code

'use client';
export function TestErrorButton() {
  return (
    <button
      onClick={() => {
        throw new Error('Test Sentry error');
      }}
    >
      Throw Test Error
    </button>
  );
}

Troubleshooting

Errors Not Appearing

1. Verify NEXT_PUBLIC_SENTRY_DSN is set and correct
2. Check the browser console for Sentry initialization errors
3. Ensure your Sentry project has available quota

Source Maps Not Working

1. Verify SENTRY_AUTH_TOKEN is set in your CI environment
2. Check the build logs for source map upload errors
3. Ensure org and project match your Sentry dashboard

Performance Data Missing

1. Check tracesSampleRate is greater than 0
2. Verify Sentry's performance monitoring is enabled for your project
3. Wait a few minutes for data to appear in the dashboard

Next: Manual Error Capturing →