RedwoodJS Storybook 集成指南：组件驱动开发与 Storybook 配置详解

后端前端Web框架开发工具【免费下载链接】redwoodRedwoodGraphQL项目地址https://gitcode.com/gh_mirrors/re/redwood点击查看免费下载Storybook 为 RedwoodJS 项目带来了一种前端优先、组件驱动的开发工作流你可以脱离 API 与数据层在完全隔离的环境中单独构建、调试和测试 UI 组件。本文基于 RedwoodJS 官方文档version-6.x 的 storybook.md展开结合仓库源码packages/cli-packages/storybook-vite、packages/cli/src/lib/configureStorybook.js等深入讲解如何启动、配置 Storybook并解释其底层实现原理帮助你掌握一套可复制的组件驱动开发与调试方案。为什么需要 Storybook组件驱动开发的价值在传统的全栈开发中改一个按钮颜色往往意味着启动 dev server、登录用户、在层层下拉菜单中穿梭、点击数次按钮甚至为了修改一个 modal 的颜色而渲染整个页面、发出六次 GraphQL 请求。Storybook 改变了这一切隔离开发将每个 UI 组件作为独立的 story 进行开发让你可以完全专注于 UI 自身的需求不必过早陷入 API 细节的泥潭高效调试不需要完整地跑通业务路径才能复现 bug直接在 story 中调整状态与数据即可定位问题可测试性每个 story 既是开发沙盒也是测试的基础可以在其中直接验证组件行为。在 RedwoodJS 中Storybook 的集成还有一层额外优势Redwood 的 Cells 与 GraphQL 数据获取逻辑可以直接在 Storybook 中被 mock配合 Mock Service WorkerMSW甚至无需真实后端即可渲染带数据的组件。快速开始启动 Storybook在 RedwoodJS 项目中启动 Storybook 只需要一条命令yarn rw storybookyarn rw storybook同时支持sb作为别名见 storybook.ts即yarn rw sb与上述命令等价。如果是第一次运行Redwood CLI 会自动完成以下准备工作安装依赖自动安装 Storybook 本体、框架包storybook-framework-redwoodjs-vite以及所有相关依赖生成配置文件CLI 会在web/.storybook目录下创建两个必要的配置文件web/.storybook/main.ts—— Storybook 的主配置文件它引用 Redwood 专属框架包storybook-framework-redwoodjs-viteweb/.storybook/preview-body.html—— 将根 div 的id设置为redwood-app这是 Vite 入口文件所要求的。配置文件的生成逻辑在 storybookHandler.ts 中实现CLI 会先检查web/.storybook下是否已存在对应配置文件不存在时才从模板创建。值得注意的是模板文件是 TypeScript 编写main.ts.template对于 JavaScript 项目CLI 会通过transformTSToJS自动将其转换为 JS 版本文件名为main.js。TypeScript 与 JavaScript 项目的检测与转换逻辑在 storybookHandler.ts 中可以看到。初始化 Mock Service WorkerCLI 会执行yarn msw init在web/public下生成MockServiceWorker.js这是 Redwood 的 Cells 在 Storybook 中能够被 mock 的前提见 storybookHandler.ts。一切就绪后Storybook 会在localhost:7910端口启动并自动打开浏览器。深入 CLIyarn rw storybook的可用参数从源码 storybook.ts 可以看出yarn rw storybook暴露了如下可配置选项参数类型默认值说明--buildbooleanfalse构建 Storybook 静态站点而不是启动开发服务器--build-directorystringpublic/storybook构建产物输出目录位于web/下--cibooleanfalseCI 模式启动服务器无交互式提示--openbooleantrue启动时是否自动在浏览器中打开--portnumber7910Storybook 监听端口--smoke-testbooleanfalseCI 模式 冒烟测试跳过提示、不打开浏览器、启动成功后立即退出源码中还对参数组合做了校验见 storybookHandler.ts--build与--smoke-test同时提供会直接抛错二者语义冲突--build与--open同时提供时--open不生效构建模式下没有浏览器可打开会输出警告。构建模式下CLI 实际执行的命令形如yarn storybook build --config-dir web/.storybook --output-dir public/storybook开发模式下则执行yarn storybook dev --config-dir web/.storybook --port 7910 --no-version-updates实际命令的拼接逻辑见 storybookHandler.ts。此外针对 Node.js20.19.0至22.0.0之间的版本CLI 会自动注入NODE_OPTIONS--no-experimental-require-module以规避已知兼容问题见 storybookHandler.ts。配置 Storybook两套方案的演进方案一web/config下的配置文件v6 时代的经典方式在 RedwoodJS 的 v6 时代Storybook 集成基于 Webpack并且采用了一套 Redwood 特有的配置约定。如果你不需要扩展 Redwood 的默认配置默认配置已涵盖如何查找 stories、配置 Webpack、启动 Mock Service Worker 等则无需任何额外配置。如果需要自定义需要在项目的web/config目录下创建两个文件注意该目录可能需要手动创建cd redwood-project/web mkdir config touch config/storybook.config.js config/storybook.preview.js两个文件职责明确web/config/storybook.config.js—— 配置 Storybook 的服务器端例如 addonsweb/config/storybook.preview.js—— 配置stories 的渲染方式例如全局 decorators。这些文件会与 Redwood 的默认配置进行合并。当时 Redwood 的默认配置位于redwoodjs/testing包的config/storybook目录下main.js 与 preview.js合并逻辑采用自定义配置优先覆盖、数组与对象深度合并的策略。配置服务器端storybook.config.jsmodule.exports { /** * This line adds all of Storybooks essential addons. * * see {link https://storybook.js.org/addons/tag/essentials} */ addons: [storybook/addon-essentials], }storybook.config.js可以配置 Storybook server 的任何可用选项但日常使用中你大概率只需要配置addons。官方推荐的storybook/addon-essentials聚合了 Storybook 的核心增强插件Actions、Controls、Viewport、Docs 等一行即可全部启用。注意由于storybook.config.js作用于 Storybook 服务器端修改该文件后可能需要重启 Storybook才能生效。配置渲染方式storybook.preview.jsstorybook.preview.js用于统一改变所有 stories 的渲染方式。把渲染逻辑写进每个组件会混淆关注点mixing concerns而逐个在.stories.{jsx,tsx}文件里复制又会很快让人厌倦。正确的做法是在storybook.preview.js中为所有 stories 统一注入自定义渲染逻辑。例如为所有 stories 添加外边距避免组件紧贴浏览器左上角export const decorators [ (Story) ( div style{{ margin: 48px }} Story / /div ), ]更多关于配置 story 渲染方式的内容可参考 Storybook 官方文档。这一合并机制在源码 configureStorybook.js 中有完整实现extendStorybookConfiguration函数会把你的自定义配置文件与已有的 Storybook preview 配置做 AST 级别的智能合并针对ImportDeclaration、ArrayExpression、ObjectExpression、ArrowFunctionExpression、FunctionDeclaration等节点类型分别采用interleave、concatUnique、keepBothStatementParents、keepBoth等合并策略最后用 Prettier 格式化后写回文件见 configureStorybook.js。方案二Vite 时代的web/.storybook当前版本随着 RedwoodJS 将 Storybook 集成迁移到 Vite其框架包为storybook-framework-redwoodjs-vite使用 Vite 作为打包器与生产项目保持一致的构建链配置方式也随之演进——现在直接遵循 Storybook 官方配置文档 即可。CLI 生成的主配置文件内容如下见 main.ts.templateimport type { StorybookConfig } from storybook-framework-redwoodjs-vite import { getPaths, importStatementPath } from redwoodjs/project-config const redwoodProjectPaths getPaths() const config: StorybookConfig { framework: storybook-framework-redwoodjs-vite, stories: [ ${importStatementPath( redwoodProjectPaths.web.src )}/**/*.stories.(js|jsx|ts|tsx|mdx), ], addons: [storybook/addon-essentials], } export default config这段模板揭示了几个关键信息framework指定 Redwood 的 Storybook 框架包storybook-framework-redwoodjs-vite这是整个集成的核心stories通过redwoodjs/project-config的getPaths()动态解析项目结构将web/src下所有*.stories.{js,jsx,ts,tsx,mdx}文件自动识别为 story无需手动维护文件列表addons默认启用storybook/addon-essentials。同时生成的preview-body.html见 preview-body.html.template内容只有一个关键元素div idredwood-app/div这是 Vite 入口文件要求的根节点模板的固定性由测试用例锁定见 storybookConfigFixtures.test.ts测试通过 inline snapshot 断言了这两个模板文件的精确内容防止配置漂移。从 Webpack 版迁移到 Vite 版如果你一直在使用旧版Webpack 驱动的Storybook 集成迁移时请先做一次自我检查没有任何自定义 Storybook 配置无需任何改动开箱即用体验与旧版一致直接启动即可有自定义配置如全局 decorators需要手动将配置迁移到新文件体系例如全局 decorators 现在直接遵循官方文档的做法配置在web/.storybook/preview.ts或 preview.js中而不是旧的web/config/storybook.preview.js。换句话说Vite 版集成不再使用web/config/storybook.config.js与web/config/storybook.preview.js这套 Redwood 私有约定而是全面拥抱 Storybook 社区标准的web/.storybook目录结构。如果你正在使用 v6 文档描述的web/config配置方式并计划升级到采用 Vite 集成的新版本请务必将上述配置迁移到web/.storybook下的标准文件中。在 Storybook 中 Mock GraphQL 请求Storybook 集成最具实战价值的场景之一是在其中 mock 组件的 GraphQL 数据请求。Redwood 的 Cells 组件在 Storybook 中默认通过 Mock Service Worker 拦截请求因此你可以为 Cell 提供 mock 数据在无后端的情况下完整渲染加载成功状态分别编写加载中、错误、空数据等不同状态的 story覆盖组件的所有渲染分支结合全局 decorators为所有 stories 统一注入 Mock Providers如 Router、Auth 上下文。关于 Cells 与 GraphQL mocking 的完整实践可参考仓库中的 mocking-graphql-in-storybook.md 以及 Redwood 测试工具包中packages/testing/src/web/下的 mock 基础设施mockRequests.ts、findCellMocks.ts。小结RedwoodJS 的 Storybook 集成经历了两代演进v6 时代的web/config/storybook.config.jsweb/config/storybook.preview.js私有配置约定基于 Webpack、配置自动合并以及当前基于 Vite 与storybook-framework-redwoodjs-vite的标准web/.storybook配置方式。无论使用哪种方式核心工作流都是一致的yarn rw storybook一键启动、组件隔离开发、GraphQL 请求可 mock、配置按需扩展。对于正在从旧版迁移的开发者重点在于将全局 decorators 等自定义配置迁移到web/.storybook下的标准文件中对于新用户开箱即用即可获得完整的组件驱动开发体验。赞分享后端前端Web框架开发工具【免费下载链接】redwoodRedwoodGraphQL项目地址https://gitcode.com/gh_mirrors/re/redwood点击查看免费下载相关推荐RedwoodJS 集成 Storybook 实战指南组件驱动开发与三文件配置体系RedwoodJS 集成 Storybook 实战指南组件驱动开发与三文件配置体系 本篇技术指南围绕 RedwoodJS 框架中 Storybook 的集成方后端前端Web框架开发工具RedwoodJS 与 Storybook 集成实战组件驱动开发、配置与源码级原理解析RedwoodJS 与 Storybook 集成实战组件驱动开发、配置与源码级原理解析 本篇技术指南以 RedwoodJS 框架中的 Storybook 集成后端前端Web框架开发工具RedwoodJS Storybook 集成指南基于 Vite 的组件驱动开发工作流RedwoodJS Storybook 集成指南基于 Vite 的组件驱动开发工作流 导读 Storybook 是 RedwoodJS 官方支持的组件驱动开发后端前端Web框架开发工具创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考