Pages Router Setup

Manual setup for Next.js applications using the Pages Router.

For the fastest setup, we recommend using the wizard installer.

This guide covers manual setup for Next.js applications using the Pages Router. For other setups, see:

App Router Setup - For applications using the App Router (Next.js 15+)
Webpack Setup - For applications not using Turbopack

You need:

A Next.js application
A Sentry account and project

Choose the features you want to configure:

Error MonitoringTracingSession Replay

Run the command for your preferred package manager to add the Sentry SDK to your application.

Copied

npm install @sentry/nextjs --save

npm install @sentry/nextjs --save

yarn add @sentry/nextjs

pnpm add @sentry/nextjs

Extend your app's default Next.js options by adding withSentryConfig into your next.config.ts (or next.config.js) file.

Pages Router applications typically use Webpack. The Webpack configuration includes auto-instrumentation options that automatically wrap your API routes and page data fetching methods.

next.config.ts

Copied

import type { NextConfig } from "next";
import { withSentryConfig } from "@sentry/nextjs";

const nextConfig: NextConfig = {
  // Your existing Next.js configuration
};

export default withSentryConfig(nextConfig, {
  org: "___ORG_SLUG___",
  project: "___PROJECT_SLUG___",

  // Only print logs for uploading source maps in CI
  silent: !process.env.CI,

  // Webpack-specific options for Pages Router
  webpack: {
    // Auto-instrument API routes and data fetching methods (default: true)
    autoInstrumentServerFunctions: true,

    // Auto-instrument middleware (default: true)
    autoInstrumentMiddleware: true,

    // Tree-shake Sentry logger statements to reduce bundle size
    treeshake: {
      removeDebugLogging: true,
    },
  },
});

import type { NextConfig } from "next";
import { withSentryConfig } from "@sentry/nextjs";

const nextConfig: NextConfig = {
  // Your existing Next.js configuration
};

export default withSentryConfig(nextConfig, {
  org: "___ORG_SLUG___",
  project: "___PROJECT_SLUG___",

  // Only print logs for uploading source maps in CI
  silent: !process.env.CI,

  // Webpack-specific options for Pages Router
  webpack: {
    // Auto-instrument API routes and data fetching methods (default: true)
    autoInstrumentServerFunctions: true,

    // Auto-instrument middleware (default: true)
    autoInstrumentMiddleware: true,

    // Tree-shake Sentry logger statements to reduce bundle size
    treeshake: {
      removeDebugLogging: true,
    },
  },
});

import type { NextConfig } from "next";
import { withSentryConfig } from "@sentry/nextjs";

const nextConfig: NextConfig = {
  // Your existing Next.js configuration
};

export default withSentryConfig(nextConfig, {
  org: "___ORG_SLUG___",
  project: "___PROJECT_SLUG___",

  // Only print logs for uploading source maps in CI
  silent: !process.env.CI,
});

Create the following files in your application's root directory (or src folder if you have one):

sentry.client.config.ts - Client-side SDK initialization
sentry.server.config.ts - Server-side SDK initialization
sentry.edge.config.ts - Edge runtime SDK initialization (if using edge routes)

Tip

Include your DSN directly in these files, or use a public environment variable like NEXT_PUBLIC_SENTRY_DSN.

sentry.client.config.ts

Copied

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

Sentry.init({
  dsn: "___PUBLIC_DSN___",

  // ___PRODUCT_OPTION_START___ performance

  // Capture 100% in dev, 10% in production
  // Adjust based on your traffic volume
  tracesSampleRate: process.env.NODE_ENV === "development" ? 1.0 : 0.1,
  // ___PRODUCT_OPTION_END___ performance
  integrations: [
    // ___PRODUCT_OPTION_START___ session-replay
    Sentry.replayIntegration(),
    // ___PRODUCT_OPTION_END___ session-replay
  ],
  // ___PRODUCT_OPTION_START___ session-replay

  // Capture Replay for 10% of all sessions,
  // plus for 100% of sessions with an error
  replaysSessionSampleRate: 0.1,
  replaysOnErrorSampleRate: 1.0,
  // ___PRODUCT_OPTION_END___ session-replay
});

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

Sentry.init({
  dsn: "___PUBLIC_DSN___",

  // ___PRODUCT_OPTION_START___ performance

  // Capture 100% in dev, 10% in production
  // Adjust based on your traffic volume
  tracesSampleRate: process.env.NODE_ENV === "development" ? 1.0 : 0.1,
  // ___PRODUCT_OPTION_END___ performance
  integrations: [
    // ___PRODUCT_OPTION_START___ session-replay
    Sentry.replayIntegration(),
    // ___PRODUCT_OPTION_END___ session-replay
  ],
  // ___PRODUCT_OPTION_START___ session-replay

  // Capture Replay for 10% of all sessions,
  // plus for 100% of sessions with an error
  replaysSessionSampleRate: 0.1,
  replaysOnErrorSampleRate: 1.0,
  // ___PRODUCT_OPTION_END___ session-replay
});

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

Sentry.init({
  dsn: "___PUBLIC_DSN___",

  // ___PRODUCT_OPTION_START___ performance

  // Capture 100% in dev, 10% in production
  // Adjust based on your traffic volume
  tracesSampleRate: process.env.NODE_ENV === "development" ? 1.0 : 0.1,
  // ___PRODUCT_OPTION_END___ performance
});

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

Sentry.init({
  dsn: "___PUBLIC_DSN___",

  // ___PRODUCT_OPTION_START___ performance

  // Capture 100% in dev, 10% in production
  // Adjust based on your traffic volume
  tracesSampleRate: process.env.NODE_ENV === "development" ? 1.0 : 0.1,
  // ___PRODUCT_OPTION_END___ performance
});

Adjust sample rates for production

Monitor your usage stats and adjust tracesSampleRate based on your traffic volume. Learn more about sampling configuration.

Create or update pages/_error.tsx to capture errors that occur during server-side rendering or in page components.

The getInitialProps method captures the error asynchronously, ensuring Sentry has time to send the error before serverless functions terminate.

_error.tsx

Copied

import * as Sentry from "@sentry/nextjs";
import type { NextPage } from "next";
import type { ErrorProps } from "next/error";
import Error from "next/error";

const CustomErrorComponent: NextPage<ErrorProps> = (props) => {
  return <Error statusCode={props.statusCode} />;
};

CustomErrorComponent.getInitialProps = async (contextData) => {
  // In case this is running in a serverless function, await this in order to give Sentry
  // time to send the error before the lambda exits
  await Sentry.captureUnderscoreErrorException(contextData);

  // This will contain the status code of the response
  return Error.getInitialProps(contextData);
};

export default CustomErrorComponent;

import * as Sentry from "@sentry/nextjs";
import type { NextPage } from "next";
import type { ErrorProps } from "next/error";
import Error from "next/error";

const CustomErrorComponent: NextPage<ErrorProps> = (props) => {
  return <Error statusCode={props.statusCode} />;
};

CustomErrorComponent.getInitialProps = async (contextData) => {
  // In case this is running in a serverless function, await this in order to give Sentry
  // time to send the error before the lambda exits
  await Sentry.captureUnderscoreErrorException(contextData);

  // This will contain the status code of the response
  return Error.getInitialProps(contextData);
};

export default CustomErrorComponent;

import * as Sentry from "@sentry/nextjs";
import Error from "next/error";

const CustomErrorComponent = (props) => {
  return <Error statusCode={props.statusCode} />;
};

CustomErrorComponent.getInitialProps = async (contextData) => {
  // In case this is running in a serverless function, await this in order to give Sentry
  // time to send the error before the lambda exits
  await Sentry.captureUnderscoreErrorException(contextData);

  // This will contain the status code of the response
  return Error.getInitialProps(contextData);
};

export default CustomErrorComponent;

Add the authToken option to your next.config.ts to enable readable stack traces. Set the SENTRY_AUTH_TOKEN environment variable in your CI/CD.

Important

Keep your auth token secret and out of version control.

next.config.ts

Copied

export default withSentryConfig(nextConfig, {
  org: "___ORG_SLUG___",
  project: "___PROJECT_SLUG___",

  // Pass the auth token
  authToken: process.env.SENTRY_AUTH_TOKEN,

  // Upload a larger set of source maps for prettier stack traces
  widenClientFileUpload: true,
});

export default withSentryConfig(nextConfig, {
  org: "___ORG_SLUG___",
  project: "___PROJECT_SLUG___",

  // Pass the auth token
  authToken: process.env.SENTRY_AUTH_TOKEN,

  // Upload a larger set of source maps for prettier stack traces
  widenClientFileUpload: true,
});

SENTRY_AUTH_TOKEN=___ORG_AUTH_TOKEN___

By default, the SDK sends user identity data (IP address, ID, and similar) and other data like HTTP bodies and URL query parameters. This will give you rich debugging context.

The SDK always filters sensitive values whose keys match a built-in denylist, such as auth or password, and sends [Filtered] instead.

To send less data, turn off the categories you don't need in the dataCollection option. For the full list of categories and their defaults, see the dataCollection options.

Copied

Sentry.init({
  dsn: "___PUBLIC_DSN___",
  dataCollection: {
    userInfo: false,
    // other categories
  },
});

Sentry.init({
  dsn: "___PUBLIC_DSN___",
  dataCollection: {
    userInfo: false,
    // other categories
  },
});

Test your error monitoring setup by throwing an error and viewing it in Sentry.

Add this button to any page and click it to trigger a test error.

pages/index.tsx

Copied

export default function Home() {
  return (
    <button
      type="button"
      onClick={() => {
        throw new Error("Sentry Test Error");
      }}
    >
      Throw Test Error
    </button>
  );
}

export default function Home() {
  return (
    <button
      type="button"
      onClick={() => {
        throw new Error("Sentry Test Error");
      }}
    >
      Throw Test Error
    </button>
  );
}

Open Issues in Sentry to see your test error. Learn more about capturing errors.

Based on the features you selected above, verify each one is working correctly.

Session Replay captures video-like reproductions of user sessions. It's configured with replayIntegration() in your client config.

Verify: Trigger an error or navigate your app, then check Replays in Sentry.

sentry.client.config.ts

Copied

Sentry.init({
  dsn: "___PUBLIC_DSN___",

  integrations: [Sentry.replayIntegration()],

  replaysSessionSampleRate: 0.1,
  replaysOnErrorSampleRate: 1.0,
});

Sentry.init({
  dsn: "___PUBLIC_DSN___",

  integrations: [Sentry.replayIntegration()],

  replaysSessionSampleRate: 0.1,
  replaysOnErrorSampleRate: 1.0,
});

Tracing is configured with tracesSampleRate in your SDK init files. Next.js routes and API calls are automatically instrumented.

Verify: Navigate to any page, then check Traces in Sentry.

sentry.server.config.ts

Copied

Sentry.init({
  dsn: "___PUBLIC_DSN___",

  tracesSampleRate: process.env.NODE_ENV === "development" ? 1.0 : 0.1,
});

Sentry.init({
  dsn: "___PUBLIC_DSN___",

  tracesSampleRate: process.env.NODE_ENV === "development" ? 1.0 : 0.1,
});

Logs are enabled by default. Use the Sentry logger to send structured logs.

Verify: Add a log statement, trigger it, then check Logs in Sentry.

Copied

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

Sentry.logger.info("User action", { userId: "123" });
Sentry.logger.warn("Warning message");
Sentry.logger.error("Error occurred");

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

Sentry.logger.info("User action", { userId: "123" });
Sentry.logger.warn("Warning message");
Sentry.logger.error("Error occurred");

Track and analyze custom application metrics to understand trends and patterns in your app's performance and behavior over time. Application Metrics are enabled by default.

Verify: Add a metrics statement, trigger it, then check Metrics in Sentry.

Copied

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

Sentry.metrics.count("checkout.failed", 1);
Sentry.metrics.gauge("queue.depth", 42);
Sentry.metrics.distribution("api_latency", 187, {
  unit: "millisecond",
});

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

Sentry.metrics.count("checkout.failed", 1);
Sentry.metrics.gauge("queue.depth", 42);
Sentry.metrics.distribution("api_latency", 187, {
  unit: "millisecond",
});

Automatically create Cron Monitors in Sentry for your Vercel cron jobs.

Add the automaticVercelMonitors option to your next.config.ts.

next.config.ts

Copied

import { withSentryConfig } from "@sentry/nextjs";

export default withSentryConfig(nextConfig, {
  automaticVercelMonitors: true,
});

import { withSentryConfig } from "@sentry/nextjs";

export default withSentryConfig(nextConfig, {
  automaticVercelMonitors: true,
});

Hybrid Apps (App Router + Pages Router)

If your application uses both the App Router and Pages Router:

Follow the App Router Setup for App Router components
Add the pages/_error.tsx file from this guide for Pages Router error handling
Both routers share the same Sentry configuration files

The Sentry SDK automatically detects which router is being used and applies the appropriate instrumentation.

Next Steps

Logs Integrations - Connect popular logging libraries like Pino, Winston, and Bunyan
Distributed Tracing - Trace requests across services and microservices
Agent Tracing - Monitor agents built with Vercel AI SDK, LangChain, and more
Connect GitHub + Seer - Enable AI-powered root cause analysis
Configuration Options - Explore extended SDK configuration

Are you having problems setting up the SDK?

Try the installation wizard for automatic setup
Get support

Was this helpful?

Help improve this content
Our documentation is open source and available on GitHub. Your contributions are welcome, whether fixing a typo (drat!) or suggesting an update ("yeah, this would be better").

How to contribute | Edit this page | Create a docs issue | Get support