Capítulo 249 de 456

transpilePackages

Core Idea

Força a compilação/bundling de dependências (workspace do monorepo ou pacotes de node_modules) que entregam TypeScript/JSX/sintaxe moderna não transpilada, em vez de tratá-las como código runtime intocado. Substitui o antigo pacote next-transpile-modules.

Key Concepts

  • transpilePackages: array de nomes de pacotes (incluindo escopados, ex. @scope/pkg); não aceita paths nem glob patterns.
  • Turbopack vs webpack: Turbopack já transpila pacotes de workspace (npm/pnpm/Yarn) automaticamente em ambos os routers; webpack faz o mesmo só para o App Router.
  • serverExternalPackages: mutuamente exclusivo com transpilePackages — um pacote não pode aparecer nos dois (Next.js lança erro no início do build se isso acontecer).
  • optimizePackageImports e default-transpiled-packages.json: pacotes já listados ali são adicionados automaticamente, não precisa repetir.

Code Examples

/** @type {import('next').NextConfig} */
const nextConfig = {
  transpilePackages: ['package-name', '@scope/pkg'],
}

module.exports = nextConfig
  • O que demonstra: como listar pacotes de node_modules ou do monorepo para serem compilados pelo Next.js.

Reference Tables

VersionChanges
v13.0.0transpilePackages added.

Anti-patterns

  • Listar um pacote em transpilePackages e serverExternalPackages ao mesmo tempo: causa erro no início do build.
  • Usar paths ou globs: a opção só aceita nomes de pacote, não caminhos de arquivo.

Key Takeaways

  1. Use quando uma dependência de node_modules entrega TS/JSX cru, ou quando webpack no Pages Router precisa bundlar código de fora do diretório do app.
  2. App Router já bundla dependências de Server Component/Route Handler automaticamente, a menos que estejam em serverExternalPackages.
  3. Turbopack reduz a necessidade desta opção para pacotes de workspace, mas não para pacotes não-transpilados em node_modules.

Connects To

  • serverExternalPackages: opção complementar/oposta para excluir pacotes do bundling.
  • optimizePackageImports: lista automática que já cobre parte dos pacotes comuns.
AnteriortrailingSlashPróximoturbopack