Turbopack no Next.js 16: configuração atual, migração do Webpack e limites

Este artigo foi reescrito em setembro de 2026. A versão anterior, de 2025, ensinava a ligar o Turbopack com experimental: { turbo: true } no next.config.js e chamava a ferramenta de experimental. No Next.js 16 as duas afirmações estão erradas: o Turbopack é o bundler padrão de next dev e de next build, e essa chave nem existe mais. Tudo abaixo foi executado com o Next.js 16.2.1 (a versão que este blog roda) num projeto criado com create-next-app, e a saída dos comandos está reproduzida sem edição.

O que mudou: Turbopack é o padrão, Webpack é a exceção

No Next.js 16 o Turbopack é estável e é usado por padrão nos dois comandos. Os scripts do package.json não precisam de flag nenhuma:

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

A primeira linha da saída do build já diz qual bundler está ativo:

▲ Next.js 16.2.1 (Turbopack)
  Creating an optimized production build ...
✓ Compiled successfully in 1084ms

Quem precisa do Webpack (plataformas sem binário nativo do Turbopack, como FreeBSD, ou um plugin que só existe para Webpack) passa a optar por ele explicitamente:

next dev --webpack
next build --webpack

No mesmo projeto, a mesma build com --webpack levou 3,4 s contra 1,07 s do Turbopack. É um projeto de duas rotas, então o número só serve para mostrar que a diferença aparece desde o primeiro build; em projetos reais a proporção varia com a quantidade de módulos e de loaders.

O que acontece com a configuração antiga

Se você ainda tem experimental.turbo no seu next.config, o Next.js 16 não quebra a build. Ele ignora a chave e avisa:

⚠ Invalid next.config.ts options detected:
⚠     Unrecognized key(s) in object: 'turbo' at "experimental"
⚠ See more info here: https://nextjs.org/docs/messages/invalid-next-config
▲ Next.js 16.2.1 (Turbopack)
- Experiments (use with caution):
  ? turbo (invalid experimental key)

Ou seja: o projeto já estava usando Turbopack sem a chave, e a chave só produzia ruído no log. Remova o bloco experimental.turbo inteiro. Se havia opções dentro dele (resolveAlias, rules), elas migram para a chave turbopack de primeiro nível, descrita a seguir.

A configuração válida no Next.js 16

A chave é turbopack, no nível raiz do next.config, compartilhada entre App Router e Pages Router. As opções documentadas são root, rules, resolveAlias, resolveExtensions e debugIds.

// next.config.ts
import type { NextConfig } from "next";
 
const nextConfig: NextConfig = {
  turbopack: {
    // Troca um módulo por outro na resolução, como o alias do Webpack.
    resolveAlias: {
      underscore: "lodash",
    },
    // Extensões consideradas ao resolver imports sem extensão.
    resolveExtensions: [".mdx", ".tsx", ".ts", ".jsx", ".js", ".json"],
    // Loaders de Webpack aplicados por glob. O "as" diz como o resultado
    // deve ser tratado depois do loader.
    rules: {
      "*.svg": {
        loaders: ["@svgr/webpack"],
        as: "*.js",
      },
    },
  },
};
 
export default nextConfig;

Essa configuração passa no schema do Next.js 16.2.1 e a build segue idêntica à sem configuração:

▲ Next.js 16.2.1 (Turbopack)
✓ Compiled successfully in 1070ms
✓ Generating static pages using 5 workers (4/4) in 427ms

Duas observações práticas:

• resolveAlias e resolveExtensions só afetam a resolução de módulos; não substituem paths do tsconfig.json, que o Next.js continua lendo para o alias @/.
• rules só faz sentido para arquivos que o Turbopack não sabe tratar sozinho. CSS, CSS Modules, PostCSS, imagens, fontes e TypeScript já são nativos; declarar loader para eles é redundante.

Loaders: o erro mais comum ao migrar

O rules executa loaders de Webpack, mas eles precisam estar instalados. A configuração acima referencia @svgr/webpack; com um logo.svg importado como componente e o pacote ausente, a build para:

▲ Next.js 16.2.1 (Turbopack)
  Creating an optimized production build ...
> Build error occurred
Error: Turbopack build failed with 1 errors:
./src/app/icon-test/logo.svg
Error evaluating Node.js code
Error: Cannot find module '@svgr/webpack'

A correção é instalar o loader (npm install -D @svgr/webpack) ou remover a regra e importar o SVG como URL de imagem, que o Turbopack já resolve sem loader. O mesmo raciocínio vale para qualquer regra herdada de um webpack() customizado: o Turbopack não lê a função webpack do next.config; cada loader precisa ser declarado de novo em turbopack.rules, e plugins de Webpack (não loaders) não têm equivalente.

Migração do Webpack em quatro passos

1. Rode next build sem flag e leia a primeira linha da saída. Se aparecer (Turbopack), você já está migrado no que depende do Next.js.
2. Remova experimental.turbo e a flag --turbopack dos scripts; no Next.js 16 os dois são redundantes.
3. Se existe uma função webpack() no next.config, liste o que ela faz. Loaders viram entradas em turbopack.rules; aliases viram resolveAlias; plugins precisam de alternativa (na maioria dos casos, a funcionalidade já é nativa ou existe como pacote sem plugin).
4. Só depois disso compare next build e next build --webpack no seu projeto, com o mesmo cache limpo (rm -rf .next antes de cada um). Guarde os dois números: são a sua medida, não a de um tutorial.

Limites que continuam valendo

• Plugins de Webpack não rodam no Turbopack. Se um plugin é indispensável, --webpack continua disponível.
• turbopack.rules aceita loaders, mas nem todo loader funciona: os que dependem de APIs internas do Webpack falham em tempo de build, como no exemplo do @svgr/webpack ausente.
• A função webpack() do next.config é ignorada quando o Turbopack está ativo; manter as duas configurações lado a lado é a forma de suportar --webpack como plano B.
• Os tempos de build dependem de máquina, cache e tamanho do projeto. Os 1,07 s contra 3,4 s acima vêm de um projeto mínimo num notebook; não extrapole.

Como reproduzir

npx [email protected] turbopack-demo --ts --app --src-dir --no-eslint --no-tailwind --use-npm --yes
cd turbopack-demo
npx next build            # (Turbopack), ~1 s
npx next build --webpack  # (webpack), ~3,4 s

Para ver o aviso da chave obsoleta, coloque experimental: { turbo: true } no next.config.ts e rode npx next build de novo. Para ver a falha de loader, adicione a regra de *.svg sem instalar o @svgr/webpack.

Leia também

• Server Components no Next.js 16: guia com exemplos reais
• Caching no Next.js: ISR, on-demand e stale-while-revalidate
• Monorepos com Turborepo: estrutura, cache e deploy
• Turbopack no glossário