如何为Next.js应用创建本地React组件库的符号链接用于测试

问题背景 #

基于React、TypeScript、Styled-components、Storybook、Rollup构建了一款作为微前端服务运行的React组件库，可发布至GitHub/npm并导入本地Next.js应用使用。当前测试流程需在Storybook开发组件后发布到GitHub，再更新Next.js依赖才能查看变更，希望创建Next.js应用到本地组件库的符号链接，实现直接在应用内测试组件的效果。

已尝试的无效方案 #

• 在组件库执行npm link，Next.js应用执行npm link <package-name>：无报错，但无法同步组件库的本地修改，已在next.config.js中配置styled-components、react-dom、react的解析别名
• 在Next.js应用执行npm install --no-save <path/to/package-name>：无报错，但组件无更新

排查方向与解决方案 #

组件库通过peerDependencies声明react、react-dom、styled-components的方式是合理的，依赖宿主应用安装不会直接影响链接效果，问题主要出在以下几点：

1. 组件库未实时构建 #

当前组件库仅提供rollup构建命令，没有监听文件变化的自动构建逻辑。符号链接指向的是组件库dist目录下的编译产物，若未重新构建，Next.js无法感知组件库的源码变更。

• 解决办法：在组件库的package.json中添加监听构建脚本：

  "scripts": {
    // 保留原有脚本
    "rollup:watch": "rollup -c --watch"
  }
  

  执行npm run rollup:watch，修改组件库代码时会自动重新编译到dist目录。

2. Next.js缓存未清理 #

Next.js默认会缓存已构建的模块，即使符号链接的文件已更新，也可能未触发重新编译。

• 解决办法：
  • 启动Next.js时关闭缓存：next dev --no-cache
  • 修改组件库代码后，手动修改Next.js应用内任意文件并保存，触发热重载

3. 符号链接的嵌套依赖冲突 #

组件库devDependencies中安装了react、react-dom、styled-components，符号链接后可能会优先加载组件库本地的依赖版本，与Next.js应用的依赖产生冲突，导致组件无法正常更新。

• 解决办法：
  • 确保组件库peerDependencies声明的版本与Next.js应用安装的版本完全一致
  • 进入Next.js应用node_modules/<package-name>目录，若存在嵌套的node_modules文件夹，直接删除，强制使用宿主应用的依赖

验证符号链接是否正确建立 #

• 查看文件系统链接：在Next.js应用的node_modules/<package-name>目录下，执行ls -l（Mac/Linux）或dir /a:l（Windows），若为符号链接，会显示指向本地组件库的路径
• 打印模块加载路径：在Next.js应用中添加代码打印组件库的实际加载路径：

  import packageJson from '<package-name>/package.json';
  console.log('组件库加载路径:', require.resolve('<package-name>'));
  

  运行应用后查看控制台，若路径指向本地组件库的dist目录，说明链接成功；若指向npm缓存或GitHub下载的路径，说明链接未生效。

附相关配置代码 #

组件库Rollup配置 #

import resolve from "@rollup/plugin-node-resolve";
import commonjs from "@rollup/plugin-commonjs";
import typescript from "@rollup/plugin-typescript";
import dts from "rollup-plugin-dts";
import postcss from 'rollup-plugin-postcss';
import peerDepsExternal from 'rollup-plugin-peer-deps-external';

import packageJson from "./package.json" assert { type: "json" };

export default [
  {
    input: "src/index.ts",
    external: ["react-dom", "styled-components"],
    output: [
      {
        file: packageJson.main,
        format: "cjs",
        sourcemap: true,
      },
      {
        file: packageJson.module,
        format: "esm",
        sourcemap: true,
      },
    ],
    plugins: [
      peerDepsExternal(),
      resolve(),
      commonjs(),
      typescript({ tsconfig: "./tsconfig.json" }),
      postcss()
    ],
    globals: { "styled-components": "styled" },
  },
  {
    input: "dist/esm/types/index.d.ts",
    output: [{ file: "dist/index.d.ts", format: "es" }],
    plugins: [dts()],
    external: [/\.(css|less|scss)$/],
  },
  {
    input: "src/themes/index.ts",
    output: [{ file: "dist/themes/index.js", format: "cjs" }],
    plugins: [commonjs(), resolve(), typescript({ tsconfig: "./tsconfig.json" })]
  }
];

组件库package.json #

{
  "name": "xxxxx",
  "version": "0.2.11",
  "description": "React Component Library",
  "scripts": {
    "rollup": "rollup -c",
    "test": "jest",
    "storybook": "storybook dev -p 6006",
    "build-storybook": "storybook build",
    "chromatic": "npx chromatic --project-token=xxxxx",
    "clean": "rm -rf node_modules && rm -rf package-lock.json && npm i",
    "generate": "node ./src/util/create-component"
  },
  "keywords": [],
  "author": {
    "name": "xxxxx"
  },
  "license": "ISC",
  "devDependencies": {
    "@babel/core": "^7.22.5",
    "@babel/preset-env": "^7.22.5",
    "@babel/preset-react": "^7.22.5",
    "@babel/preset-typescript": "^7.22.5",
    "@rollup/plugin-commonjs": "^25.0.1",
    "@rollup/plugin-node-resolve": "^15.1.0",
    "@rollup/plugin-terser": "^0.4.3",
    "@rollup/plugin-typescript": "^11.1.1",
    "@storybook/addon-essentials": "^7.0.21",
    "@storybook/addon-interactions": "^7.0.21",
    "@storybook/addon-links": "^7.0.21",
    "@storybook/addon-styling": "^1.3.0",
    "@storybook/blocks": "^7.0.21",
    "@storybook/react": "^7.0.21",
    "@storybook/react-webpack5": "^7.0.21",
    "@storybook/testing-library": "^0.0.14-next.2",
    "@testing-library/react": "^14.0.0",
    "@types/jest": "^29.5.2",
    "@types/react": "^18.2.12",
    "@types/styled-components": "^5.1.26",
    "babel-jest": "^29.5.0",
    "babel-plugin-styled-components": "^2.1.3",
    "chromatic": "^6.19.8",
    "identity-obj-proxy": "^3.0.0",
    "jest": "^29.5.0",
    "jest-environment-jsdom": "^29.5.0",
    "prop-types": "^15.8.1",
    "react": "^18.2.0",
    "react-dom": "^18.2.0",
    "rollup": "^3.25.1",
    "rollup-plugin-dts": "^5.3.0",
    "rollup-plugin-peer-deps-external": "^2.2.4",
    "rollup-plugin-postcss": "^4.0.2",
    "storybook": "^7.0.21",
    "styled-components": "^6.0.0-rc.3",
    "tslib": "^2.5.3",
    "typescript": "^5.1.3"
  },
  "peerDependencies": {
    "react": "^18.2.0",
    "react-dom": "^18.2.0",
    "styled-components": "^6.0.0-rc.3"
  },
  "main": "dist/cjs/index.js",
  "module": "dist/esm/index.js",
  "files": [
    "dist"
  ],
  "types": "dist/index.d.ts",
  "publishConfig": {
    "registry": "xxxxx"
  },
  "readme": "ERROR: No README data found!",
  "_id": "xxxxx@0.0.3"
}

Next.js应用配置 #

const path = require("path");

/** @type {import('next').NextConfig} */
const nextConfig = {
  webpack(config) {
    config.experiments = {
      asyncWebAssembly: true,
      layers: true,
    };

    config.resolve.alias = {
      ...config.resolve.alias,
      "styled-components": path.resolve("./node_modules/styled-components"),
      "react-dom": path.resolve("./node_modules/react-dom"),
      "react": path.resolve("./node_modules/react")
    };

    return config;
  },
  reactStrictMode: true,
  swcMinify: true,
  compiler: {
    styledComponents: true,
  },
};

module.exports = nextConfig;

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