Capítulo 250 de 456

turbopack

Core Idea

Opção top-level turbopack para customizar como o Turbopack (bundler Rust do Next.js) transforma arquivos e resolve módulos: root dir, webpack loaders compatíveis, tipos de módulo, aliases de resolução, extensões, e debug IDs. Substitui o antigo experimental.turbo (13.0.0-15.2.x, ainda funciona como alias).

Key Concepts

  • root: path absoluto para o diretório raiz da aplicação; Turbopack só resolve módulos dentro dele (detectado automaticamente via lockfiles, pnpm-lock.yaml/package-lock.json/yarn.lock/bun.lock(b)).
  • rules: mapeia extensões/globs de arquivo a uma lista de webpack loaders suportados, com as para renomear a saída e type para setar o module type.
  • resolveAlias: equivalente a resolve.alias do webpack, com suporte a alias condicional (browser).
  • resolveExtensions: sobrescreve a lista de extensões resolvidas na importação (deve incluir os defaults).
  • debugIds: gera debug IDs nos bundles JS e source maps.
  • Import attributes (with { turbopackLoader: ... }): aplica um loader Turbopack por import individual, sem afetar globalmente o tipo de arquivo.
  • condition (em rules): sintaxe avançada (all/any/not, path, content, query, contentType) mais condições built-in (browser, foreign, development, production, node, edge-light) para restringir onde um loader roda.

Code Examples

module.exports = {
  turbopack: {
    rules: {
      '*.svg': {
        loaders: ['@svgr/webpack'],
        as: '*.js',
      },
    },
  },
}
  • O que demonstra: registrar um webpack loader (@svgr/webpack) pra transformar .svg em componente React via Turbopack.
import rawText from '../data.txt' with { turbopackLoader: 'raw-loader', turbopackAs: '*.js' }
  • O que demonstra: aplicar loader só a um import específico via import attributes, sem regra global em turbopack.rules.
module.exports = {
  turbopack: {
    rules: {
      '*': {
        condition: {
          all: [
            { not: 'foreign' },
            { path: /^img\/[0-9]{3}\// },
            { any: [{ path: '*.svg' }, { query: /[?&]svgr(?=&|$)/ }, { content: /\<svg\W/ }] },
          ],
        },
        loaders: ['@svgr/webpack'],
        as: '*.js',
      },
    },
  },
}
  • O que demonstra: condição composta restringindo o loader a arquivos não-node_modules, sob img/NNN/, que sejam SVG por path, query ou conteúdo.

Reference Tables

OptionDescription
rootSets the application root directory (absolute path).
rulesWebpack loaders suportados a aplicar rodando com Turbopack.
resolveAliasMapeia imports aliasados para módulos substitutos.
resolveExtensionsLista de extensões a resolver ao importar arquivos.
debugIdsGera debug IDs nos bundles JS e source maps.

Module types (turbopack.rules.*.type): asset, ecmascript, typescript, css, css-module, json, wasm, node, raw/text, bytes.

Loaders testados: babel-loader (auto se houver config Babel), @svgr/webpack, svg-inline-loader, yaml-loader, string-replace-loader, raw-loader, sass-loader (auto), graphql-tag/loader.

Features de loader webpack SEM suporte: importModule, loadModule, emitFile, this.version, this.mode, this.target, this.utils, this.resolve (usar getResolve). this.fs só suporta fs.readFile.

VersionChanges
16.2.0turbopackLoader import attributes; rules.*.type; rules.*.condition.contentType/.query added.
16.0.0turbopack.debugIds; turbopack.rules.*.condition added.
15.3.0experimental.turbo renomeado para turbopack.
13.0.0experimental.turbo introduzido.

Anti-patterns

  • Passar módulos plugin via require() como valor de opção de loader: opções devem ser primitivos/objetos/arrays JavaScript puros, não é possível.
  • Usar loaders que transformam para não-JS (stylesheets, imagens): só loaders que retornam código JavaScript são suportados.
  • Confiar em turbo.loaders (nome antigo, pré-13.4.4): renomeado para turbopack.rules, com sintaxe de extensão mudada de .mdx para *.mdx.

Key Takeaways

  1. Turbopack tem suporte nativo a CSS e JS moderno, então não precisa de css-loader/postcss-loader/babel-loader para funcionalidade básica.
  2. Para linked dependencies fora do root (npm link etc.), aponte turbopack.root para o diretório pai comum.
  3. type pode ser combinado com loaders: os loaders rodam primeiro, depois o resultado é processado conforme o type.
  4. Import attributes (turbopackLoader) são exclusivas do Turbopack; não funcionam no webpack e exigem with (não assert).
  5. Regras rules podem ser array de objetos para modelar condições disjuntas (ex: comportamento diferente em browser vs servidor).

Connects To

  • turbopackChunking: configura o chunker de produção do Turbopack, separado de rules/loaders.
  • turbopack.ignoreIssue: suprime erros/warnings específicos do Turbopack.
  • turbopackFileSystemCache: cache persistente do Turbopack entre execuções.
AnteriortranspilePackagesPróximoturbopackChunking