webpack()

webpack?: (config: any, context: { buildId: string; dev: boolean; isServer: boolean; defaultLoaders: { babel: any }; nextRuntime?: 'nodejs' | 'edge'; webpack: typeof import('webpack') }) => any

The webpack option is a function that receives the configuration Next.js has already assembled and returns a modified version of it. It is executed three times per build — twice for the server (Node.js and Edge runtimes) and once for the client — so almost every real customisation starts by branching on isServer or nextRuntime.

When to reach for it

Only after confirming Next.js has no first-class option for what you want. CSS, CSS Modules, Sass, MDX (@next/mdx) and bundle analysis (@next/bundle-analyzer) are all supported without touching the bundler. Reach for this hook for genuinely bespoke loaders, DefinePlugin values, or vendor plugins that ship no Next.js integration.

What trips people up

• Forgetting the final return config. The function's return value is the config; dropping it produces a build with no configuration at all.
• Since Next.js 16 Turbopack is the default bundler, and next build fails when it finds a webpack function. Run next build --webpack to keep webpack, next build --turbopack to build anyway and ignore the hook, or port the customisation to the turbopack option.
• If you see that failure but never wrote this option, a plugin wrapper in your config is adding it for you.
• The shape of the config object is not covered by semver, so a minor Next.js release can move things you depend on.

import type { NextConfig } from 'next'

const nextConfig: NextConfig = {
  webpack: (
    config,
    { buildId, dev, isServer, defaultLoaders, nextRuntime, webpack }
  ) => {
    if (!isServer) {
      config.plugins.push(
        new webpack.DefinePlugin({
          'process.env.BUILD_ID': JSON.stringify(buildId),
        })
      )
    }

    // Important: return the modified config
    return config
  },
}

export default nextConfig

import type { NextConfig } from 'next'

const nextConfig: NextConfig = {
  webpack: (config, options) => {
    config.module.rules.push({
      test: /\.mdx/,
      use: [
        options.defaultLoaders.babel,
        {
          loader: '@mdx-js/loader',
          options: {},
        },
      ],
    })

    return config
  },
}

export default nextConfig

import type { NextConfig } from 'next'

const nextConfig: NextConfig = {
  webpack: (config, { isServer, nextRuntime }) => {
    if (isServer && nextRuntime === 'nodejs') {
      config.externals = [...(config.externals ?? []), 'my-native-addon']
    }

    if (isServer && nextRuntime === 'edge') {
      // The Edge compilation has no Node.js built-ins available
      config.resolve.alias = {
        ...config.resolve.alias,
        'my-native-addon': false,
      }
    }

    return config
  },
}

export default nextConfig

{
  "scripts": {
    "dev": "next dev",
    "build": "next build --webpack",
    "start": "next start"
  }
}