---
title: "Webpack Setup"
description: "Additional configuration for Next.js applications using Webpack instead of Turbopack."
url: https://docs.sentry.io/platforms/javascript/guides/nextjs/manual-setup/webpack-setup/
---

# Webpack Setup for Next.js

This guide covers the configuration differences for **Next.js applications using Webpack** (the default bundler before Next.js 15). Complete the [main manual setup](https://docs.sentry.io/platforms/javascript/guides/nextjs/manual-setup.md) first, then apply these Webpack-specific configurations.

For a complete reference of all build configuration options, see the [Build Configuration](https://docs.sentry.io/platforms/javascript/guides/nextjs/configuration/build.md) documentation.

If you're using Next.js 15+ with Turbopack (the default), you don't need this guide. See the [main manual setup](https://docs.sentry.io/platforms/javascript/guides/nextjs/manual-setup.md) instead.

## [Key Differences: Webpack vs Turbopack](https://docs.sentry.io/platforms/javascript/guides/nextjs/manual-setup/webpack-setup.md#key-differences-webpack-vs-turbopack)

| Feature                         | Turbopack                       | Webpack                                              |
| ------------------------------- | ------------------------------- | ---------------------------------------------------- |
| Server function instrumentation | Automatic via Next.js telemetry | Build-time code injection                            |
| Middleware instrumentation      | Automatic via Next.js telemetry | Build-time code injection                            |
| Dependency instrumentation      | Next.js 16+                     | Supported                                            |
| Source map upload               | Post-compile during build       | During build via plugin (default)                    |
| Route exclusion                 | Not supported                   | Supported via `webpack.excludeServerRoutes`          |
| React component annotation      | Next.js 16+                     | Supported                                            |
| Logger tree-shaking             | Not supported                   | Supported via `webpack.treeshake.removeDebugLogging` |

## [Auto-Instrumentation Options](https://docs.sentry.io/platforms/javascript/guides/nextjs/manual-setup/webpack-setup.md#auto-instrumentation-options)

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

### [Configure Auto-Instrumentation](https://docs.sentry.io/platforms/javascript/guides/nextjs/manual-setup/webpack-setup.md#configure-auto-instrumentation)

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()`.

```typescript
import { withSentryConfig } from "@sentry/nextjs/config";

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,
    },
  },
});
```

## [Exclude Routes From Instrumentation](https://docs.sentry.io/platforms/javascript/guides/nextjs/manual-setup/webpack-setup.md#exclude-routes-from-instrumentation)

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

This option has no effect when using Turbopack, as Turbopack relies on Next.js telemetry features instead of build-time instrumentation.

### [Configure Route Exclusions](https://docs.sentry.io/platforms/javascript/guides/nextjs/manual-setup/webpack-setup.md#configure-route-exclusions)

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

```typescript
import { withSentryConfig } from "@sentry/nextjs/config";

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

## [Source Map Upload](https://docs.sentry.io/platforms/javascript/guides/nextjs/manual-setup/webpack-setup.md#source-map-upload)

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.

### [Default: Upload During Build](https://docs.sentry.io/platforms/javascript/guides/nextjs/manual-setup/webpack-setup.md#default-upload-during-build)

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

```typescript
import { withSentryConfig } from "@sentry/nextjs/config";

export default withSentryConfig(nextConfig, {
  org: "<your-org-slug>",
  project: "<your-project-slug>",
  authToken: process.env.SENTRY_AUTH_TOKEN,
});
```

### [Option: Upload After Build (Next.js 15.4.1+)](https://docs.sentry.io/platforms/javascript/guides/nextjs/manual-setup/webpack-setup.md#option-upload-after-build-nextjs-1541)

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

This option requires Next.js 15.4.1 or later. Turbopack always uses this mode.

```typescript
import { withSentryConfig } from "@sentry/nextjs/config";

export default withSentryConfig(nextConfig, {
  org: "<your-org-slug>",
  project: "<your-project-slug>",
  authToken: process.env.SENTRY_AUTH_TOKEN,

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

### [Control Which Files Are Uploaded](https://docs.sentry.io/platforms/javascript/guides/nextjs/manual-setup/webpack-setup.md#control-which-files-are-uploaded)

If the defaults pick up too much or too little, narrow the upload with the `sourcemaps` options. These are top-level options and apply to both Webpack and Turbopack builds. See [Build Configuration](https://docs.sentry.io/platforms/javascript/guides/nextjs/configuration/build.md) for the full list.

```typescript
import { withSentryConfig } from "@sentry/nextjs/config";

export default withSentryConfig(nextConfig, {
  org: "<your-org-slug>",
  project: "<your-project-slug>",
  authToken: process.env.SENTRY_AUTH_TOKEN,

  sourcemaps: {
    assets: [".next/**/*.js", ".next/**/*.map"],
    ignore: ["**/node_modules/**"],
  },
});
```

## [Server Actions with Webpack](https://docs.sentry.io/platforms/javascript/guides/nextjs/manual-setup/webpack-setup.md#server-actions-with-webpack)

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.

### [Manual Server Action Instrumentation](https://docs.sentry.io/platforms/javascript/guides/nextjs/manual-setup/webpack-setup.md#manual-server-action-instrumentation)

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

```typescript
"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 };
    },
  );
}
```

## [React Component Annotation](https://docs.sentry.io/platforms/javascript/guides/nextjs/manual-setup/webpack-setup.md#react-component-annotation)

Component annotation adds `data-sentry-*` attributes to your React components at build time, so Sentry can tell you which component a user interacted with in [Session Replay](https://docs.sentry.io/platforms/javascript/guides/nextjs/session-replay.md) and [breadcrumbs](https://docs.sentry.io/platforms/javascript/guides/nextjs/enriching-events/breadcrumbs.md).

`reactComponentAnnotation` is a top-level option and drives both Webpack and Turbopack builds. On Turbopack it requires Next.js 16 or higher, enable it on an older version and the SDK warns at build time. The bundler-specific `webpack.reactComponentAnnotation` and `_experimental.turbopackReactComponentAnnotation` options still work but are deprecated, and will be removed in the next major version.

### [Enable Component Annotation](https://docs.sentry.io/platforms/javascript/guides/nextjs/manual-setup/webpack-setup.md#enable-component-annotation)

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

```typescript
import { withSentryConfig } from "@sentry/nextjs/config";

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

### [Exclude Specific Components](https://docs.sentry.io/platforms/javascript/guides/nextjs/manual-setup/webpack-setup.md#exclude-specific-components)

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

```typescript
import { withSentryConfig } from "@sentry/nextjs/config";

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

## [Tunneling with Webpack](https://docs.sentry.io/platforms/javascript/guides/nextjs/manual-setup/webpack-setup.md#tunneling-with-webpack)

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

### [Configure Tunnel Route](https://docs.sentry.io/platforms/javascript/guides/nextjs/manual-setup/webpack-setup.md#configure-tunnel-route)

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.

```typescript
tunnelRoute: true, // Auto-generated random route
```

```typescript
import { withSentryConfig } from "@sentry/nextjs/config";

export default withSentryConfig(nextConfig, {
  // Use a fixed route (recommended)
  tunnelRoute: "/sentry-tunnel",
});
```

## [Migrating from Webpack to Turbopack](https://docs.sentry.io/platforms/javascript/guides/nextjs/manual-setup/webpack-setup.md#migrating-from-webpack-to-turbopack)

If you're upgrading to Turbopack:

1. **Drop webpack-only options** - anything under `webpack` has no effect with Turbopack, including `excludeServerRoutes` and `treeshake`
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

```typescript
// Before (Webpack)
export default withSentryConfig(nextConfig, {
  webpack: {
    excludeServerRoutes: ["/api/health"],
  },
  tunnelRoute: "/sentry-tunnel",
});

// After (Turbopack)
export default withSentryConfig(nextConfig, {
  // webpack.excludeServerRoutes is not supported with Turbopack
  tunnelRoute: "/sentry-tunnel",
});
```

## [Next Steps](https://docs.sentry.io/platforms/javascript/guides/nextjs/manual-setup/webpack-setup.md#next-steps)

* [Logs Integrations](https://docs.sentry.io/platforms/javascript/guides/nextjs/logs.md#integrations) - Connect popular logging libraries like Pino, Winston, and Bunyan
* [Distributed Tracing](https://docs.sentry.io/platforms/javascript/guides/nextjs/tracing/distributed-tracing.md) - Trace requests across services and microservices
* [Agent Tracing](https://docs.sentry.io/platforms/javascript/guides/nextjs/agent-tracing.md) - Monitor agents built with Vercel AI SDK, LangChain, and more
* [Connect GitHub + Seer](https://docs.sentry.io/integrations/source-code-mgmt/github.md#installing-github) - Enable AI-powered [root cause analysis](https://docs.sentry.io/product/ai-in-sentry/seer.md)
* [Configuration Options](https://docs.sentry.io/platforms/javascript/guides/nextjs/configuration.md) - Explore extended SDK configuration