NX Monorepo中React库的Storybook无法启动问题

问题核心 #

启动Storybook时触发ModuleNotFoundError，提示无法解析../_isolated-hnrs/dist/emotion-react-_isolated-hnrs.browser.esm.js。该文件是@emotion/react内部依赖模块，因安装不完整、版本兼容或Webpack解析配置问题导致缺失。

复现步骤 #

1. 创建NX工作区 #

npx create-nx-workspace@latest

配置选项：

• 工作区名称：monorepo
• 工作区类型：react
• 应用名称：webpage
• 默认样式表格式：emotion

2. 添加React库并配置Storybook #

npx nx g @nrwl/react:lib ui
npm i storybook -D
nx g @nrwl/react:storybook-configuration ui
nx g @nrwl/react:stories ui

3. 启动Storybook #

nx run ui:storybook

解决方案 #

方案1：重新安装依赖（优先尝试） #

大概率是依赖安装不完整导致文件缺失，执行以下步骤：

# Windows系统
rmdir /s /q node_modules
del package-lock.json yarn.lock

# macOS/Linux系统
rm -rf node_modules package-lock.json yarn.lock

# 重新安装
npm install

方案2：锁定@emotion/react兼容版本 #

部分新版本@emotion/react的内部目录结构变化，与NX/Storybook预设不兼容，降级到稳定兼容版本：

1. 修改package.json中@emotion/react版本为^11.10.6（或其他经测试兼容的版本）
2. 执行npm install重新安装

方案3：调整Storybook Webpack配置 #

通过别名强制Webpack解析正确的@emotion/react模块，在项目根目录或库目录下的.storybook/main.js中添加：

module.exports = {
  webpackFinal: async (config) => {
    config.resolve.alias = {
      ...config.resolve.alias,
      '@emotion/react': require.resolve('@emotion/react'),
    };
    return config;
  },
};

方案4：使用NX官方emotion初始化流程 #

创建React库时直接指定emotion样式，避免手动安装导致的版本不一致：

nx g @nrwl/react:lib ui --style=emotion

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