Storybook 手动为 React Webpack 5 项目启用框架.storybook/main中storybook/react-webpack5的完整配置指南【免费下载链接】storybookStorybook is the industry standard workshop for building, documenting, and testing UI components in isolation项目地址: https://gitcode.com/GitHub_Trending/st/storybookframework是 Storybook 配置中决定用哪套渲染器 哪套构建器的关键字段。本文以官方文档中的react-webpack5-add-framework代码片段为核心说明在手动初始化未使用storybook init脚手架的 React 项目中如何一步步安装并把storybook/react-webpack5配置进.storybook/main.js|ts同时覆盖 CSF 3 与实验性 CSF Next 两代配置写法并结合当前仓库源码解释该字段背后的类型约束与预设加载机制。读完你将能自己动手在任意 React Webpack 5 工程中接好 Storybook 框架并知道如何按需传入构建选项。使用前提这个 Webpack 框架适合谁官方推荐绝大多数新项目直接使用基于 Vite 的storybook/react-vite只有在确实需要 Webpack 特有能力时才切换到storybook/react-webpack5见 框架页说明。具体场景包括项目本身基于 Webpack 5 构建、必须复用既有 Webpack loader / plugin 生态或者使用 Create React AppCRA等与 Webpack 深度绑定的工程。从源码角度看该框架的定位十分明确。在 code/frameworks/react-webpack5/package.json 中可以看到它只依赖三个包并组合了它们的职责依赖包职责storybook/reactReact 渲染器负责把 CSF 文件渲染成组件预览storybook/preset-react-webpack把 React 专属配置JSX 处理、Fast Refresh 等合入 Webpack 构建storybook/builder-webpack5Webpack 5 构建器真正执行打包其 peer 依赖要求 React^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0TypeScript 为可选依赖 4.9.x因此无论项目处于哪个主流 React 大版本都可以接入。第一步安装框架包在项目根目录安装框架npm/pnpm/yarn 均可完整命令参见 react-webpack5-install.mdnpm install --save-dev storybook/react-webpack5pnpm add --save-dev storybook/react-webpack5yarn add --dev storybook/react-webpack5注意安装的是devDependencies因为 Storybook 只参与开发与构建环节。第二步注册编译器 addonSWC 或 BabelWebpack 需要把 React 的 JSX / TSX 编译为 JavaScriptStorybook 通过编译器 addon 决定用 SWC 还是 Babel。官方推荐 SWC非 CRA 项目需要手动注册例如npx storybooklatest add storybook/addon-webpack5-compiler-swcpnpm dlx storybooklatest add storybook/addon-webpack5-compiler-swcyarn dlx storybooklatest add storybook/addon-webpack5-compiler-swc如果项目基于 Create React App可跳过本步因为 CRA 预设storybook/preset-create-react-app已经内置了对 Sass/SCSS 与 TypeScript 等 CRA 特性的支持更多编译器细节参见 builders/webpack.mdx 的 compiler support 章节。第三步核心在.storybook/main.js|ts中配置 framework这是本文要展开的核心动作把framework字段指向storybook/react-webpack5。官方文档对应的代码片段保存在 react-webpack5-add-framework.md共提供了四种等价写法覆盖 JavaScript / TypeScript × CSF 3 / CSF Next 两种配置时代。写法 A.storybook/main.js CSF 3对象字面量export default { // ... framework: storybook/react-webpack5, // Add this };这是最简单、最直接的写法把framework设成包名字符串。Storybook 会读取该包的preset子路径并据此组装出渲染器 构建器 各类预设。写法 B.storybook/main.ts CSF 3带类型检查import type { StorybookConfig } from storybook/react-webpack5; const config: StorybookConfig { // ... framework: storybook/react-webpack5, // Add this }; export default config;TypeScript 项目推荐此写法通过给config声明StorybookConfig类型编辑器与tsc会校验framework值是否是该框架允许的CompatibleStringstorybook/react-webpack5从而在配置期就拦截拼写错误。写法 C.storybook/main.ts CSF Next实验特性// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite) import { defineMain } from storybook/your-framework/node; export default defineMain({ // ... framework: storybook/react-webpack5, // Add this });CSF Next 是 Storybook 新一代配置形态文档中以 标记为实验特性。它改用框架暴露的defineMain()辅助函数包裹配置对象以获得比satisfies StorybookConfig更强的按框架推导配置字面量能力。针对本框架实际的导入路径是storybook/react-webpack5/node——当前仓库中 code/frameworks/react-webpack5/src/node/index.ts 正是其 node 侧入口导出了defineMain(config: StorybookConfig)。示例注释要求把your-framework替换为真实框架例如把storybook/react-webpack5/node换成你正在使用的那个框架的对应入口。写法 D.storybook/main.js CSF Next实验特性// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite) import { defineMain } from storybook/your-framework/node; export default defineMain({ // ... framework: storybook/react-webpack5, // Add this });即使主配置文件是.jsdefineMain也能正常使用逻辑与写法 C 完全一致。框架侧源码framework字段到底做了什么把framework设成字符串后Storybook 会加载该包在 package.jsonexports中暴露的./preset子路径进而执行 code/frameworks/react-webpack5/src/preset.ts 中的预设逻辑核心只有三段从中可以清晰看到框架 渲染器 构建器的组合方式export const addons: PresetPropertyaddons [ fileURLToPath(import.meta.resolve(storybook/preset-react-webpack)), ]; export const core: PresetPropertycore { builder: import.meta.resolve(storybook/builder-webpack5), renderer: import.meta.resolve(storybook/react/preset), }; export const webpack: StorybookConfig[webpack] async (config, options) { config.resolve config.resolve || {}; config.resolve.alias { ...config.resolve?.alias, storybook/react: fileURLToPath(import.meta.resolve(storybook/react)), }; // 若启用 developmentModeForBuild则注入 NODE_ENVdevelopment 的 DefinePlugin // ... return config; };要点解读addons固定挂载storybook/preset-react-webpackReact 的 JSX 转换、快速刷新、HMR 等配置都由这个预设统一收口避免每个用户自行拼装core同时锁定builder与renderer两项这正是选择本框架后.storybook/main中无需再写builder/core.renderer字段的原因webpack钩子会确保storybook/react被正确 alias避免在 monorepo 或多版本场景下解析到错误副本当开启developmentModeForBuild生产构建中使用开发模式功能时还会注入NODE_ENVdevelopment。如果你希望单独定制构建器选项types.ts也允许在core.builder中覆盖保持包名字符串一致即可可参考 code/frameworks/react-webpack5/src/types.ts 的StorybookConfigFramework类型定义。类型骨架framework 的两种合法形态code/frameworks/react-webpack5/src/types.ts 明确定义了framework字段的合法取值理解它有助于看懂所有配置变体type FrameworkName CompatibleStringstorybook/react-webpack5; export type FrameworkOptions ReactOptions { builder?: BuilderOptions; }; type StorybookConfigFramework { framework: | FrameworkName // 形态一纯字符串 | { name: FrameworkName; // 形态二对象携带 options options: FrameworkOptions; }; // ... };即framework有两种写法要么是一个包名兼容字符串写法 A/B/C/D 中framework: storybook/react-webpack5要么是{ name, options }对象——当你需要向框架传入额外配置时使用后者。框架入口 code/frameworks/react-webpack5/src/index.ts 除导出全部类型外还从storybook/react转发了definePreview供新版 preview 配置使用。进阶为 framework 传入 options官方提供的框架 options 片段见 react-webpack5-framework-options.md演示了对象写法export default { framework: { name: storybook/react-webpack5, options: { // ... }, }, };import type { StorybookConfig } from storybook/react-webpack5; const config: StorybookConfig { framework: { name: storybook/react-webpack5, options: { // ... }, }, }; export default config;options的类型是ReactOptions { builder?: BuilderOptions }其中ReactOptions来自storybook/preset-react-webpackReact 侧选项如fastRefresh而builder键则用来透传 Webpack 构建器选项可用配置项可在 Webpack builder 文档中查阅对象写法同样支持 CSF Next 的defineMain包裹。如何验证配置成功完成三步配置后依次执行启动开发模式npm run storybook对应文档 storybook-run-dev.md浏览器正常打开组件预览即代表渲染器链路打通生产构建npm run build-storybook产物默认输出到storybook-static可用outputDir自定义见 build-storybook-production-mode.md在 React 组件旁新增一个 CSF 文件.stories.jsx|tsx确认热更新、Controls、Docs 等核心能力均正常工作。若配置阶段已使用 TypeScript 的StorybookConfig类型或 CSF Next 的defineMain则类型检查本身就会在启动前兜底拦截framework拼写与options结构错误。关联资源速查完整框架指引docs/get-started/frameworks/react-webpack5.mdx含 CRA 支持、手工初始化注意事项、Vite 迁移指引安装命令片段docs/_snippets/react-webpack5-install.md本文核心配置片段docs/_snippets/react-webpack5-add-framework.mdoptions 写法片段docs/_snippets/react-webpack5-framework-options.md框架包源码code/frameworks/react-webpack5类型定义types.ts、预设逻辑preset.ts、node 入口src/node/index.tsReact 相关预设目录code/presets/react-webpackstorybook/preset-react-webpack的实现所在【免费下载链接】storybookStorybook is the industry standard workshop for building, documenting, and testing UI components in isolation项目地址: https://gitcode.com/GitHub_Trending/st/storybook创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考