如何在本地Next.js项目中测试TSDX开发的React UI组件库

方案1：Next.js原生配置方案（无第三方依赖，推荐） #

适配Next.js 13.1及以上版本，从根源规避npm link的软链异常问题：

1. 组件库侧配置

• 进入TSDX组件库根目录，执行npm run build --watch开启监听模式，修改源码后自动更新构建产物
• 检查组件库package.json字段配置：
  • main字段指向cjs产物，默认值为dist/index.js
  • module字段指向esm产物，默认值为dist/index.esm.js
  • types字段指向类型声明文件，默认值为dist/index.d.ts
  • 将react、react-dom移到peerDependencies，不要放在dependencies中，避免重复打包引入多份React实例

2. Next.js项目侧配置

• 在Next.js项目根目录执行命令，通过file协议引入本地组件库：
  yarn add file:../path-to-your-tsdx-project（替换为你本地TSDX项目的实际相对/绝对路径）
• 修改项目根目录下的next.config.js，添加transpilePackages配置，声明需要编译的本地组件库包名：

/** @type {import('next').NextConfig} */
const nextConfig = {
  transpilePackages: ['your-tsdx-package-name'], // 替换为组件库package.json中name字段的实际值
  reactStrictMode: true,
}
module.exports = nextConfig

• 正常启动Next.js dev服务即可导入组件使用，修改组件库代码触发重新构建后，如果Next.js没有自动热更新，重启dev服务即可，不会出现模块找不到的报错。

方案2：yalc本地包管理方案（兼容所有Next.js版本） #

如果使用低于13.1的Next.js版本，用yalc替代npm link稳定性更高，不会出现软链导致的依赖解析异常：

1. 全局安装yalc：npm i yalc -g
2. 进入TSDX组件库目录，先执行npm run build生成初始产物，再执行yalc publish将组件库发布到本地全局包仓库
3. 进入Next.js项目目录，执行yalc add your-tsdx-package-name将本地包添加到项目依赖
4. 保持TSDX目录下npm run build --watch运行，修改组件库代码完成构建后，在Next.js项目执行yalc update your-tsdx-package-name即可拉取最新代码，也可以配合文件监听工具实现自动更新。
5. 调试结束后，在Next.js项目执行yalc remove your-tsdx-package-name，重新安装依赖即可恢复线上包引用。

原有方案报错原因说明 #

• npm link方案异常：软链机制会导致Next.js解析依赖时，分别在组件库目录、Next.js项目目录查找react/react-dom，触发多React实例问题；同时TSDX watch模式下重建产物存在短暂的文件删除空窗期，Next.js扫描到文件不存在后会缓存模块找不到的状态，即使后续产物重建也不会自动重新解析，就会出现报错时node_modules下依赖文件实际存在的现象。
• 直接yarn add 本地路径方案异常：Next.js默认不会编译node_modules下的依赖文件，TSDX输出的产物如果包含未被编译的语法，会直接触发解析报错，添加transpilePackages配置即可解决该问题。

注意：调试过程中不要在两个项目目录下重复执行依赖安装，否则可能在node_modules中生成多份React副本，触发钩子调用异常或模块找不到错误。如果出现该类问题，删除两个目录下的node_modules、lock文件后重新安装依赖即可恢复。

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