如何在Next.js Turbopack中使用本地npm关联依赖包？

问题背景 #

开发my-package本地包时，在Next.js示例项目中通过file:..关联依赖，非Turbo模式运行正常，但使用next dev --turbo时出现Module not found: Can't resolve 'my-package'错误。

解决方案 #

1. 确保本地包已完成构建

Turbopack不会自动编译未构建的源码包，先在my-package根目录执行构建命令：

npm run build

需确保my-package/package.json中配置了正确的构建脚本（比如TypeScript编译到dist目录）。

2. 配置Turbopack识别本地依赖

在示例项目（example/）的turbo.config.js中添加外部依赖配置，让Turbopack明确处理本地包：

// example/turbo.config.js
/** @type {import('turbo').Config} */
module.exports = {
  experimental: {
    externalDependencies: ['my-package']
  }
}

3. 校验本地包的入口配置

确认my-package/package.json的入口字段指向构建后的产物，示例配置：

{
  "main": "./dist/index.js",
  "module": "./dist/index.mjs",
  "types": "./dist/index.d.ts",
  "exports": {
    ".": {
      "import": "./dist/index.mjs",
      "require": "./dist/index.js",
      "types": "./dist/index.d.ts"
    }
  }
}

4. 重启Turbopack服务

修改配置后，停止当前next dev --turbo进程，重新启动服务让配置生效。

替代方案：使用npm工作区管理依赖 #

用npm workspaces替代file:协议，能让Turbopack更友好地识别本地依赖：

1. 在my-package根目录的package.json添加工作区配置：

{
  "name": "my-package",
  "version": "1.2.3",
  "workspaces": ["./example"]
}

2. 在根目录执行npm install，自动关联工作区内的依赖；
3. 示例项目的package.json中my-package依赖会自动指向本地包，无需手动设置file:..。

问题原因 #

Turbopack的模块解析逻辑与Webpack不同，默认不会深度遍历file:协议指向的本地目录，也不会自动编译未构建的源码依赖，因此需要通过配置明确声明或使用工作区规范来让Turbopack正确识别本地包。

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