transpilePackages

Core Idea

Compiles and bundles specific dependencies (local monorepo packages or node_modules) instead of treating them as untouched runtime code. Replaces the old next-transpile-modules package.

Key Concepts

• transpilePackages: array of package names (supports scoped names like @scope/pkg); paths/globs not supported.
• When needed: a node_modules dep ships raw TypeScript/JSX; webpack + Pages Router needs a monorepo dependency bundled; Pages Router needs a node_modules dep bundled into the route instead of loaded via Node require at runtime.
• Turbopack auto-transpiles workspace packages (npm/pnpm/Yarn) automatically; webpack does the same only for App Router.
• Mutual exclusivity: a package cannot be in both transpilePackages and serverExternalPackages (build fails if it is).

Code Examples

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

module.exports = nextConfig

• O que demonstra: como listar pacotes locais/externos para transpilação.

Reference Tables

Version	Changes
v13.0.0	transpilePackages added.

Anti-patterns

• Listar um pacote em transpilePackages e serverExternalPackages ao mesmo tempo: Next.js lança erro no início do build.

Key Takeaways

1. Use quando um dependency de node_modules entrega TS/JSX cru sem build.
2. Turbopack já transpila pacotes de workspace automaticamente; a config é mais relevante pra webpack/Pages Router.
3. Pacotes de optimizePackageImports e default-transpiled-packages.json já entram automaticamente, não precisa repetir.

Connects To

• serverExternalPackages: opção mutuamente exclusiva para App Router.
• optimizePackageImports: pacotes lá já entram na lista automática.