turbopack (next.config.js option)

Core Idea

Configures Turbopack to transform files and change module resolution — the turbopack top-level config key (previously experimental.turbo, still aliased for 13.0.0-15.2.x).

Key Concepts

root: absolute path setting the application root directory (auto-detected via lockfiles; set manually for non-workspace layouts or npm/yarn/pnpm link).
rules: maps file glob patterns to webpack loaders (only a subset of the webpack loader API works; only loaders returning JS are supported).
resolveAlias: aliases imports to other modules, similar to webpack resolve.alias; supports conditional aliasing via { browser: ... }.
resolveExtensions: overrides the list of extensions resolved on import (must repeat defaults you still want).
debugIds: enables debug ID generation in JS bundles/source maps.
Import attributes (with { turbopackLoader, turbopackLoaderOptions, turbopackAs, turbopackModuleType }): apply a loader per-import instead of globally.
condition: advanced rule matching (path, content, query, contentType, plus built-ins browser, foreign, development, production, node, edge-light).
Module type: sets output type directly (asset, ecmascript, typescript, css, css-module, json, wasm, node, raw/text, bytes) without a loader.

Code Examples

module.exports = {
  turbopack: {
    rules: {
      '*.svg': {
        loaders: ['@svgr/webpack'],
        as: '*.js',
      },
    },
  },
}

O que demonstra: configura um loader (@svgr/webpack) pra importar .svg como componente React.

import rawText from '../data.txt' with { turbopackLoader: 'raw-loader', turbopackAs: '*.js' }

O que demonstra: aplica loader só a um import específico via import attributes, sem afetar o arquivo globalmente.

Reference Tables

Option	Description
`root`	Sets the application root directory (absolute path).
`rules`	Webpack loaders to apply when running with Turbopack.
`resolveAlias`	Map aliased imports to modules to load in their place.
`resolveExtensions`	List of extensions to resolve when importing files.
`debugIds`	Enable debug ID generation in JS bundles and source maps.

Module types: asset, ecmascript, typescript, css, css-module, json, wasm, node, raw/text, bytes.

Anti-patterns

Confiar em recursos de loader não suportados (importModule, loadModule, emitFile, this.utils, this.resolve): Turbopack's loader-runner não cobre a API completa do webpack; só fs.readFile funciona em fs.
Passar require() de plugin modules como valor de opção de loader: só primitivos/objetos/arrays JS puros são aceitos.

Key Takeaways

turbopack substitui experimental.turbo; migrar com npx @next/codemod@latest next-experimental-turbo-to-turbopack ..
Rules podem ser objeto ou array (array modela condições disjuntas); todas as regras que casam rodam em ordem.
Import attributes (with { turbopackLoader: ... }) exigem with, não assert, e não têm equivalente em webpack.

Connects To

turbopackChunking (ch421): outra opção experimental de Turbopack, mas focada em chunking de produção, não em loaders.
useLightningcss (ch424): Turbopack sempre usa Lightning CSS, ignorando essa flag.