Turborepo：是否必须在Next.js中转译内部包？

结论：不是强制必须，但官方文档和示例的做法是为了规避潜在风险，保证跨环境、跨包管理器的一致性。

一、为什么不配置有时也能正常运行？ #

• Next.js 13+对monorepo的支持大幅升级，当内部包通过npm Workspaces的符号链接引入时，Next会自动识别这些包属于项目源码范畴，而非第三方node_modules依赖，从而跳过默认的「node_modules不转译」规则，直接处理源码。
• 如果你的内部包已经通过Turbo的build任务预转译成纯JS（比如输出到dist目录，package.json的main/module字段指向转译后的文件），Next无需额外转译就能直接使用。

二、为什么官方文档和示例都要求配置transpilePackages？ #

这是为了覆盖以下必须转译的场景，避免隐性bug：

• 未预转译的内部包源码：如果内部包用TypeScript、JSX或ESNext语法编写且未提前build，Next默认不会转译node_modules目录下的内容（即使是符号链接的内部包），生产构建时会直接抛出语法错误。
• 包管理器兼容性：pnpm等包管理器的隔离性更强，不会让Next自动识别到符号链接的内部包源码，必须显式配置transpilePackages才能让Next转译。
• 跨环境一致性：开发环境Next的热更新逻辑相对宽松，可能能正常运行，但生产构建的打包规则更严格，未配置转译会导致构建失败。
• 内部包依赖未转译的第三方库：如果内部包依赖了某个未转译的第三方包，配置transpilePackages可以让Next一起处理这些依赖的转译。

三、实现「直接打包内部包，无需预先转译」的方案（npm作为包管理器） #

如果你想跳过内部包的预build步骤，让Next在构建/开发时直接处理源码，可以按以下步骤操作：

1. 调整内部包的package.json：确保main/module字段指向源码文件（如src/index.tsx），不要指向预转译的dist目录。
2. 在Next应用的next.config.js中显式配置transpilePackages：

/** @type {import('next').NextConfig} */
const nextConfig = {
  transpilePackages: ['@repo/ui', '@repo/math-helpers'], // 列出所有需要转译的内部包
};

module.exports = nextConfig;

3. （可选）精细控制转译范围（通过webpack配置）：

const path = require('path');

/** @type {import('next').NextConfig} */
const nextConfig = {
  webpack: (config) => {
    // 将所有内部包目录加入转译规则
    config.module.rules.push({
      test: /\.(ts|tsx|js|jsx)$/,
      include: [path.resolve(__dirname, '../packages')],
      use: 'babel-loader',
    });
    return config;
  },
};

module.exports = nextConfig;

通过上述配置，Next会在构建/开发过程中直接转译内部包的源码，无需提前执行Turbo的build任务，内部包通过npm Workspaces的符号链接被正确解析并打包进应用。

内容的提问来源于stack exchange，提问作者FelHa