Typescript复合项目集成NextJS遇noEmit冲突，求解决方案及示例

核心思路：用双tsconfig分离Next.js编译和TS项目引用需求 #

Next.js要求noEmit: true来接管编译打包，但TS项目引用必须让子项目开启输出（noEmit: false），给Next.js子项目配置两个tsconfig文件就能解决冲突：

1. Next.js主配置（tsconfig.json） #

保留Next.js官方推荐配置，维持noEmit: true，同时正常引用其他工作区子项目：

{
  "extends": "../../tsconfig.base.json",
  "compilerOptions": {
    "noEmit": true,
    "jsx": "preserve",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "baseUrl": ".",
    "paths": {
      "@your-workspace/utils/*": ["../utils/src/*"]
    }
  },
  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx"],
  "exclude": ["node_modules"],
  "references": [{"path": "../utils"}]
}

2. TS项目引用专用配置（tsconfig.build.json） #

专门给根目录npx tsc --build命令使用，关闭noEmit但只输出类型声明文件，重点满足CommonJS类型需求：

{
  "extends": "./tsconfig.json",
  "compilerOptions": {
    "noEmit": false,
    "emitDeclarationOnly": true,
    "declaration": true,
    "declarationDir": "./dist/types",
    "module": "CommonJS",
    "moduleResolution": "node"
  },
  "exclude": ["node_modules", ".next", "next-env.d.ts"]
}

3. 根目录tsconfig关联配置 #

将根tsconfig.json中Next.js子项目的引用指向上述专用配置文件：

{
  "files": [],
  "references": [
    {"path": "./packages/utils"},
    {"path": "./packages/next-app/tsconfig.build.json"}
  ]
}

CommonJS与ES模块兼容处理 #

• CommonJS类型：在tsconfig.build.json中指定module: "CommonJS"和moduleResolution: "node"，生成的.d.ts文件会完全符合CJS规范。
• ES模块：Next.js主配置保留module: "ESNext"即可，Next.js打包时会自动完成模块转换，不影响应用运行逻辑。

脚本优化建议 #

在Next.js子项目的package.json中添加两个脚本，方便单独执行类型检查或生成声明文件：

{
  "scripts": {
    "type-check": "tsc --noEmit",
    "build-types": "tsc --project tsconfig.build.json"
  }
}

根目录执行npx tsc --build时，会自动触发所有子项目的类型编译流程，包括Next.js的声明文件输出。

额外提醒 #

• 所有子项目尽量共用根目录的tsconfig.base.json，统一strict、target等基础配置，避免出现类型不一致问题。
• 无需依赖已废弃的next-transpile-modules，Next.js 13及以上版本自带的模块解析能力可以直接处理工作区内部依赖。

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