Webpack Setup

Additional configuration for Next.js applications using Webpack instead of Turbopack.

This guide covers the configuration differences for Next.js applications using Webpack (the default bundler before Next.js 15). Complete the main manual setup first, then apply these Webpack-specific configurations.

For a complete reference of all build configuration options, see the Build Configuration documentation.

FeatureTurbopackWebpack
Server function instrumentationAutomatic via Next.js telemetryBuild-time code injection
Middleware instrumentationAutomatic via Next.js telemetryBuild-time code injection
Source map uploadPost-compile during buildDuring build via plugin (default)
Route exclusionNot supportedSupported via webpack.excludeServerRoutes
React component annotationNot supportedSupported via webpack.reactComponentAnnotation
Logger tree-shakingNot supportedSupported via webpack.treeshake.removeDebugLogging

With Webpack, Sentry automatically instruments your server functions, middleware, and app directory components at build time. You can control this behavior:

These options are enabled by default with Webpack. Disable them if you prefer manual instrumentation or experience build issues.

Note: These options instrument Pages Router pages, API routes, and App Router components, but do NOT automatically instrument Server Actions. Server Actions require manual wrapping using withServerActionInstrumentation().

next.config.ts
Copied
import { withSentryConfig } from "@sentry/nextjs";

export default withSentryConfig(nextConfig, {
  webpack: {
    // Instrument Pages Router API routes and data fetching methods (default: true)
    autoInstrumentServerFunctions: true,

    // Instrument Next.js middleware (default: true)
    autoInstrumentMiddleware: true,

    // Instrument App Router components (default: true)
    autoInstrumentAppDirectory: true,

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

With Webpack, you can exclude specific routes from automatic instrumentation. This is useful for health check endpoints or routes that shouldn't be monitored.

Specify routes as URL paths (not file system paths). Routes must have a leading slash and no trailing slash.

next.config.ts
Copied
import { withSentryConfig } from "@sentry/nextjs";

export default withSentryConfig(nextConfig, {
  webpack: {
    excludeServerRoutes: [
      "/api/health",
      "/api/excluded/[parameter]",
      /^\/internal\//, // Regex for all /internal/* routes
    ],
  },
});

By default, Webpack uploads source maps during the build process using the Sentry Webpack Plugin. This happens separately for each build (client, server, edge), which can increase build time.

For faster builds, you can use the post-build upload mode (available in Next.js 15.4.1+), which uploads all source maps in a single operation after all builds complete.

The Sentry Webpack Plugin runs during each webpack compilation and uploads source maps as they're generated.

next.config.ts
Copied
import { withSentryConfig } from "@sentry/nextjs";

export default withSentryConfig(nextConfig, {
  org: "___ORG_SLUG___",
  project: "___PROJECT_SLUG___",
  authToken: process.env.SENTRY_AUTH_TOKEN,
});

Enable post-build upload for faster builds. All source maps are uploaded once after all webpack builds complete.

next.config.ts
Copied
import { withSentryConfig } from "@sentry/nextjs";

export default withSentryConfig(nextConfig, {
  org: "___ORG_SLUG___",
  project: "___PROJECT_SLUG___",
  authToken: process.env.SENTRY_AUTH_TOKEN,

  // Upload after all builds complete (faster)
  useRunAfterProductionCompileHook: true,
});

Pass options directly to the underlying Sentry Webpack Plugin for advanced configuration.

next.config.ts
Copied
import { withSentryConfig } from "@sentry/nextjs";

export default withSentryConfig(nextConfig, {
  org: "___ORG_SLUG___",
  project: "___PROJECT_SLUG___",
  authToken: process.env.SENTRY_AUTH_TOKEN,

  webpack: {
    // Advanced Webpack plugin options
    unstable_sentryWebpackPluginOptions: {
      sourcemaps: {
        assets: ["./build/**/*.js", "./build/**/*.map"],
        ignore: ["node_modules/**"],
      },
    },
  },
});

Server Actions (functions marked with "use server") are not automatically instrumented by Webpack's build-time instrumentation. You must manually wrap them for error and performance monitoring.

Wrap Server Actions with withServerActionInstrumentation() to capture errors and performance data.

app/actions.ts
Copied
"use server";
import * as Sentry from "@sentry/nextjs";

export async function submitForm(formData: FormData) {
  return Sentry.withServerActionInstrumentation(
    "submitForm", // Action name for Sentry
    {
      recordResponse: true, // Include response data
    },
    async () => {
      // Your server action logic
      const result = await processForm(formData);
      return { success: true, data: result };
    },
  );
}

With Webpack, you can enable React component name tracking. This annotates React components with data-sentry-* attributes that allow Sentry to identify which components users interacted with in Session Replay and breadcrumbs.

Enable reactComponentAnnotation to track component names in your application. This is especially useful for debugging user interactions in Session Replay.

next.config.ts
Copied
import { withSentryConfig } from "@sentry/nextjs";

export default withSentryConfig(nextConfig, {
  webpack: {
    reactComponentAnnotation: {
      enabled: true,
    },
  },
});

If you have components you don't want annotated (for privacy or performance reasons), you can exclude them by name.

next.config.ts
Copied
import { withSentryConfig } from "@sentry/nextjs";

export default withSentryConfig(nextConfig, {
  webpack: {
    reactComponentAnnotation: {
      enabled: true,
      ignoredComponents: ["SensitiveForm", "InternalDebugPanel"],
    },
  },
});

Tunneling works identically for both Webpack and Turbopack. Sentry automatically filters tunnel requests from middleware spans to prevent noise in your monitoring data.

Enable tunneling to bypass ad-blockers. Use a fixed route so you can exclude it from middleware if needed.

Using random tunnel routes

You can use tunnelRoute: true to auto-generate a random route. However, random routes cannot be excluded from middleware matchers since the route changes on each build. This may cause issues if you have middleware that intercepts all requests.

Copied
tunnelRoute: true, // Auto-generated random route
next.config.ts
Copied
import { withSentryConfig } from "@sentry/nextjs";

export default withSentryConfig(nextConfig, {
  // Use a fixed route (recommended)
  tunnelRoute: "/monitoring",
});

If you're upgrading to Turbopack:

  1. Remove webpack-only options - excludeServerRoutes and unstable_sentryWebpackPluginOptions have no effect with Turbopack
  2. Understand source map changes - Turbopack always uses post-build upload (no plugin-based upload option)
  3. Test auto-instrumentation - Turbopack uses Next.js telemetry instead of build-time injection; verify your monitoring still works
next.config.ts
Copied
// Before (Webpack)
export default withSentryConfig(nextConfig, {
  excludeServerRoutes: ["/api/health"],
  tunnelRoute: "/monitoring",
});

// After (Turbopack)
export default withSentryConfig(nextConfig, {
  // excludeServerRoutes is not supported with Turbopack
  tunnelRoute: "/monitoring",
});

Previous
Pages Router Setup
Next
Capturing Errors
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").