Capítulo 263 de 456

webpack

Core Idea

Permite estender a config interna do webpack do Next.js via uma função em next.config.js, para quando o suporte nativo (CSS imports/modules, Sass, plugins como @next/mdx) não cobre o caso de uso. Mudanças de webpack config não seguem semver, use por sua conta e risco.

Key Concepts

  • webpack(config, options): função que recebe a config webpack e um objeto de options, deve retornar a config modificada. Executa três vezes: duas para o servidor (Node.js / edge runtime) e uma para o cliente.
  • options.buildId: String, identificador único do build.
  • options.dev: Boolean, indica se a compilação é de desenvolvimento.
  • options.isServer: Boolean, true para compilação server-side, false para client-side.
  • options.nextRuntime: String | undefined, "edge" ou "nodejs" para compilação server; undefined no client. isServer é true quando nextRuntime é "edge" ou "nodejs".
  • options.defaultLoaders.babel: config default do babel-loader usada internamente pelo Next.js, útil para compor com outros loaders custom.

Code Examples

module.exports = {
  webpack: (
    config,
    { buildId, dev, isServer, defaultLoaders, nextRuntime, webpack }
  ) => {
    // Important: return the modified config
    return config
  },
}
  • O que demonstra: assinatura completa da função de customização e todos os parâmetros disponíveis.
// Exemplo baseado no @next/mdx
module.exports = {
  webpack: (config, options) => {
    config.module.rules.push({
      test: /\.mdx/,
      use: [
        options.defaultLoaders.babel,
        {
          loader: '@mdx-js/loader',
          options: pluginOptions.options,
        },
      ],
    })

    return config
  },
}
  • O que demonstra: como encadear defaultLoaders.babel com um loader customizado (@mdx-js/loader) para adicionar suporte a um novo tipo de arquivo.

Anti-patterns

  • Adicionar webpack config custom sem checar se o Next.js já suporta o caso: a doc pede para verificar CSS imports/modules, Sass/SCSS imports/modules e plugins existentes (@next/mdx, @next/bundle-analyzer) antes de mexer na config webpack.
  • Esquecer de return config: a função precisa retornar a config modificada, senão a customização é perdida.

Key Takeaways

  1. Mudanças na API de webpack config não são cobertas por semver, versões futuras do Next.js podem quebrar sua customização.
  2. isServer sozinho não distingue edge de node; use nextRuntime para isso.
  3. nextRuntime: "edge" atualmente é só para proxy e Server Components em edge runtime.

Connects To

  • turbopack: caminho alternativo/moderno de customização de bundler, com API diferente (rules, loaders, resolveAlias).
AnterioruseTypeScriptCliPróximowebVitalsAttribution