如何使用Turborepo管理独立公开Node模块及TS包发布配置

我的项目结构规划如下：

./project               (name 'project', private)
   ./apps
      ./playground      (name '@project/playground', private)
   ./packages
      ./base            (name '@project/base', public)
      ./plugin-a        (name '@project/plugin-a', public)
      ./plugin-b        (name '@project/plugin-b', public)

考虑到Turborepo的易用性打算采用它，但默认布局中./packages/ui的TypeScript文件直接放在包根目录，因此有以下疑问：

1. TypeScript模块能否直接发布到npm供非TS项目使用？（直觉认为不转译源码不行，因此衍生第二个问题）
2. 这些包的package.json需如何配置，才能发布到npm并同时支持TS和JS项目？
3. 设想用src文件夹存放TypeScript文件，dist文件夹存放转译后的JavaScript，该方案是否正确？

问题解答 #

1. TypeScript模块能否直接发布到npm供非TS项目使用？ #

不行。非TypeScript项目（比如纯JS项目、未配置TS的构建工具环境）无法识别.ts/.tsx后缀的文件，会直接抛出模块解析错误。必须将TypeScript源码转译为标准JavaScript后，才能让这类项目正常引入使用。

2. 包的package.json配置方案 #

要同时兼容TS和JS项目，需要在每个公共包的package.json中配置以下核心字段：

• main: 指定转译后CommonJS格式的入口文件，适配Node.js或传统构建工具
• module: 指定转译后ES模块格式的入口文件，适配现代浏览器、ES模块优先的构建工具
• types: 指定TypeScript类型定义文件的路径，让TS项目能自动识别类型
• files: 明确列出要发布到npm的文件列表，避免上传源码、本地配置等无关内容
• scripts: 添加构建脚本，用于将src下的TS代码转译为JS并生成类型文件
• publishConfig.access: 设置为public，确保私有组织下的包能正常发布到npm

示例配置片段：

{
  "name": "@project/base",
  "version": "1.0.0",
  "main": "dist/index.cjs.js",
  "module": "dist/index.esm.js",
  "types": "dist/types/index.d.ts",
  "files": ["dist", "package.json", "README.md"],
  "scripts": {
    "build": "tsup src/index.ts --format cjs,esm --dts"
  },
  "publishConfig": {
    "access": "public"
  }
}

注：示例中用tsup作为构建工具，也可根据需求替换为Rollup、esbuild或TypeScript官方编译器。

3. src存TS、dist存转译JS的方案是否正确？ #

这个方案是多包项目的通用最佳实践，优势非常明确：

• 源码与构建产物完全分离，目录结构清晰易维护
• 发布时仅上传dist和必要配置，大幅减小npm包体积
• 配合Turborepo的缓存机制，能实现子包构建结果的高效复用，提升整体构建速度

同时在Turborepo根目录的turbo.json中，需要配置构建任务的依赖关系，确保子包按正确顺序构建：

{
  "pipeline": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": ["dist/**"]
    }
  }
}

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