如何在NextJS应用中导入Monorepo包并实现热重载？

1. 调整本地包的package.json配置 #

修改packages/x/package.json，让NextJS直接加载源码入口而非预构建的dist目录：

{
  "name": "@packages/x",
  "main": "./index.tsx",
  "types": "./index.tsx",
  "exports": {
    ".": "./index.tsx"
  }
}

此配置会让应用直接读取packages/x/index.tsx源码，跳过预构建产物。

2. 配置NextJS转译本地包 #

在apps/a/next.config.js中添加transpilePackages，告诉NextJS需要转译@packages/x的源码（默认NextJS不会转译node_modules内的包，但本地工作区包需特殊处理）：

/** @type {import('next').NextConfig} */
const nextConfig = {
  // 转译指定的本地包，实现热重载基础
  transpilePackages: ['@packages/x'],
}

module.exports = nextConfig

这一步是热重载的核心：NextJS会监听packages/x下的文件变化，自动触发页面热更新。

3. 处理本地包内部的别名路径 #

如果packages/x内部使用了自定义别名（比如@/components/xxx），需要让NextJS的webpack能解析这些别名，提供两种方案：

方案1：通过根tsconfig共享路径映射 #

在根目录的tsconfig.json中添加路径配置：

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@packages/x": ["packages/x/index.tsx"],
      "@packages/x/*": ["packages/x/*"],
      // 对应packages/x内部的@/*别名
      "@/*": ["packages/x/src/*"]
    }
  }
}

让apps/a/tsconfig.json继承根配置：

{
  "extends": "../../tsconfig.json",
  "compilerOptions": {
    // 保留应用自身的编译配置
    "target": "es5",
    "lib": ["dom", "dom.iterable", "esnext"],
    "allowJs": true,
    "skipLibCheck": true,
    "strict": true,
    "noEmit": true,
    "jsx": "preserve",
    "incremental": true
  },
  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx"],
  "exclude": ["node_modules"]
}

方案2：用webpack插件解析本地包的tsconfig #

如果不想污染根目录配置，安装tsconfig-paths-webpack-plugin：

npm install --save-dev tsconfig-paths-webpack-plugin

修改apps/a/next.config.js：

const TsconfigPathsPlugin = require('tsconfig-paths-webpack-plugin');

/** @type {import('next').NextConfig} */
const nextConfig = {
  transpilePackages: ['@packages/x'],
  webpack: (config) => {
    // 让webpack读取packages/x的tsconfig，解析内部别名
    config.resolve.plugins.push(new TsconfigPathsPlugin({
      configFile: './packages/x/tsconfig.json'
    }));
    return config;
  },
}

module.exports = nextConfig;

4. 修正应用的依赖声明 #

把apps/a/package.json中@packages/x的依赖改为工作区协议，确保包管理器优先使用本地源码：

"dependencies": {
  "@packages/x": "workspace:*"
}

验证热重载 #

启动NextJS开发服务：

cd apps/a
npm run dev

修改packages/x下的组件代码（比如Foo组件），NextJS会自动触发热重载，无需重新构建本地包。

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