RedwoodJS 与 Storybook 集成实战：组件驱动开发、配置与源码级原理解析

后端前端Web框架开发工具【免费下载链接】redwoodRedwoodGraphQL项目地址https://gitcode.com/gh_mirrors/re/redwood点击查看免费下载本篇技术指南以 RedwoodJS 框架中的 Storybook 集成为核心主题完整覆盖从yarn rw storybook启动开发服务器到通过storybook.config.js、storybook.manager.js、storybook.preview.js三个配置文件定制服务器、渲染行为与 UI 主题的完整流程并结合当前仓库 packages/storybook 的源码实现深入剖析 RedwoodJS 是如何在 Storybook 中注入 Redwood 运行时Router、Apollo、Auth、MSW mock的底层原理。读完本文你将掌握在 RedwoodJS 项目中以组件优先的方式开发、调试和测试 UI 组件的完整实战方案。Storybook 在 RedwoodJS 中的定位Storybook 带来的是一种前端优先、组件驱动frontend-first, component-driven的开发工作流通过在隔离环境中单独开发 UI 组件开发者可以只关注 UI 本身的需求而不必过早陷入 API 细节之中。这种隔离开发模式同时让调试变得异常轻松——你不再需要为了复现一个 bug 而启动 dev server、登录用户、逐个展开下拉菜单、反复点击按钮也不需要为了修改一个弹窗的颜色而渲染整个页面、发起六次 GraphQL 请求。你只需把组件状态编排成一个个 story在 Storybook 中按需调整、反复验证甚至可以顺手为它补上测试。快速启动 Storybook在 RedwoodJS 项目中启动 Storybook 只需要一条命令yarn rw storybookRedwoodJS 的 CLI 会自动完成 Storybook 的安装与配置随后在本地7910端口启动服务并打开浏览器。首次运行时的自动配置根据当前仓库 docs/docs/storybook.md 中描述的最新行为首次运行yarn rw storybook时Redwood CLI 会替你完成两件事安装 Storybook、框架包framework package以及全部相关依赖在web/.storybook目录下创建配置文件web/.storybook/main.ts——Storybook 的主配置文件其中引用了 RedwoodJS 官方的框架包storybook-framework-redwoodjs-viteweb/.storybook/preview-body.html——用于将根节点 div 的id改为redwood-app这是 Vite 入口文件运行所必需的。值得注意的是当前仓库中的 Storybook 集成已经全面转向 Vite 构建在 preset.ts 中框架明确指定了storybook/builder-vite作为 builder、storybook/react作为 renderer与生产项目的 Vite 构建保持对齐。配置 Storybook三个配置文件RedwoodJS 为 Storybook 提供了开箱即用的默认配置它已经处理好了如何发现 stories、如何配置构建、如何启动 Mock Service Worker等一系列问题。只有当你需要扩展这些默认行为时才需要自定义配置。你可以在项目的web/config目录下添加三个配置文件storybook.config.js——配置 Storybook 的服务器serverstorybook.manager.js——配置 Storybook 的UImanager 界面storybook.preview.js——配置故事stories的渲染方式如果web/config目录尚不存在需要先手动创建cd redwood-project/web mkdir config touch config/storybook.config.js config/storybook.manager.js config/storybook.preview.js这三个文件都会与 RedwoodJS 的默认配置进行合并merge默认配置位于redwoodjs/testing包中。对应关系如下项目配置文件合并的 RedwoodJS 默认配置web/config/storybook.config.jsredwoodjs/testing包中的main.jsweb/config/storybook.manager.jsredwoodjs/testing包中的manager.jsweb/config/storybook.preview.jsredwoodjs/testing包中的preview.js配置服务器storybook.config.js⚠️ 注意由于storybook.config.js配置的是 Storybook 服务器任何改动都需要重启 Storybook才能生效。虽然理论上你可以在storybook.config.js中配置 Storybook 服务器支持的所有选项但实际最常用的只有addonsmodule.exports { /** * This line adds all of Storybooks essential addons. * * see https://storybook.js.org/addons/tag/essentials */ addons: [storybook/addon-essentials], }storybook/addon-essentials聚合了 Storybook 官方推荐的核心插件Controls、Actions、Docs 等是绝大多数项目的标配。配置渲染方式storybook.preview.js当你希望改变所有故事stories的渲染方式时有两个错误的选择把逻辑塞进实际组件会污染组件职责或者在每一个.stories.js文件里重复添加会很快让人崩溃。正确的做法是在storybook.preview.js中用decorators统一装饰所有故事。例如给所有故事添加外边距避免组件紧贴画布左上角export const decorators [ (Story) ( div style{{ margin: 48px }} Story / /div ), ]这种全局装饰器机制与当前仓库的源码实现理念一致在 preview.tsx 中RedwoodJS 框架包自身也正是通过注册全局decorators为每个故事注入StorybookProvider运行时环境的。配置 UIstorybook.manager.js⚠️ 注意对 Storybook UI 的部分改动需要刷新缓存才能生效。最简便的方式是在启动时携带--no-manager-cache标志yarn rw storybook --no-manager-cache一个典型的 UI 定制场景是主题化theming。首先从项目根目录安装两个依赖yarn workspace web add -D storybook/addons storybook/theming然后创建storybook.manager.js并启用 Storybook 的暗色主题import { addons } from storybook/addons import { themes } from storybook/theming addons.setConfig({ theme: themes.dark, })你还可以基于storybook/theming创建自定义主题并将主题导出以复用到 Storybook Docs 中。源码级剖析RedwoodJS 如何驱动 Storybook以上配置文档描述的是用户侧的操作方式。要真正理解 RedwoodJS 的 Storybook 集成需要深入当前仓库 packages/storybook/src 的源码看它在框架层面替你做了什么。这些源码是 Vite 时代的集成实现也是storybook-framework-redwoodjs-vite框架包的核心。Vite 配置合并preset.tspreset.ts 是框架包的核心预设它通过viteFinal钩子深度定制 Vite 构建// packages/storybook/src/preset.ts关键片段 export const viteFinal: StorybookConfig[viteFinal] async (config) { const { plugins [] } config // Needs to run before the react plugin, so add to the front plugins.unshift(reactDocgen()) plugins.unshift(nodePolyfills()) return mergeConfig(config, { // This is necessary as it otherwise just points to the web directory, // but it needs to point to web/src root: redwoodProjectPaths.web.src, plugins: [mockRouter(), mockAuth(), autoImports], resolve: { alias: { ~__REDWOOD__USER_ROUTES_FOR_MOCK: redwoodProjectPaths.web.routes, ~__REDWOOD__USER_WEB_SRC: redwoodProjectPaths.web.src, }, }, ... }) }这段代码揭示了几个关键设计构建根目录指向web/srcVite 的 root 被重定向到web/src而不是整个web目录三个核心插件mockRouter()把redwoodjs/router替换为 Mock 实现、mockAuth()把用户的createAuth替换为测试用 mock、autoImports自动导入 mock 工具函数两个路径别名~__REDWOOD__USER_ROUTES_FOR_MOCK指向用户的Routes文件~__REDWOOD__USER_WEB_SRC指向web/src供 mock 模块按需加载用户源码reactDocgen()与nodePolyfills()分别用于从组件生成文档类型信息、为浏览器环境补齐 Node polyfill。全局运行时注入preview.tsx 与 MockProviderspreview.tsx 注册了框架级的decorators与loaders。其中MockingLoader在 StorybookProvider.tsx 中实现它做了三件事通过 Vite 的 Glob Importimport.meta.glob并开启eager: true预加载web/src下所有*.mock.{js,ts}文件确保任何使用了 Cell 的组件都能拿到 mock 数据调用startMSW(browsers)启动 Mock Service Worker调用setupRequestHandlers()注册请求处理器。随后StorybookProvider会在每个故事渲染前调用mockCurrentUser(null)默认将当前用户置空保证每个故事从干净状态开始。每个故事最终都被包裹在 MockProviders.tsx 提供的完整 Redwood 运行时环境中// packages/storybook/src/mocks/MockProviders.tsx结构示意 RedwoodProvider titleTemplate%PageTitle | %AppTitle RedwoodApolloProvider useAuth{useAuth} UserRoutes / LocationProvider MockParamsProvider{children}/MockParamsProvider /LocationProvider /RedwoodApolloProvider /RedwoodProvider这意味着你的故事默认就拥有完整的 RedwoodJS 运行时能力Redwood Provider页面标题模板、Apollo GraphQL 客户端、用户Routes中的路由对象用于routes.xxx()、路由Location上下文以及 Mock 参数注入——这也是为什么在 Storybook 中你可以直接使用mockGraphQLQuery等工具为 Cell 组件模拟 GraphQL 数据。自动导入的 mock 工具auto-imports.ts 通过unplugin-auto-import为所有.ts/.tsx/.js/.jsx文件自动注册了三个来自redwoodjs/testing/web的全局函数无需手动 import 即可在 story 中直接使用mockGraphQLQuery——模拟 GraphQL Query 响应mockGraphQLMutation——模拟 GraphQL Mutation 响应mockCurrentUser——设置当前登录用户。这与文档中提到的为 Cell 组件 mock GraphQL 再容易不过直接对应也是组件驱动开发体验的关键一环。Auth 与 Router 的运行时替换plugins/mock-auth.ts 会在构建期通过正则改写web/src/auth文件移除原有的createAuth具名导入改从redwoodjs/testing/dist/web/mockAuth.js导入createAuthentication as createAuth从而把真实认证逻辑替换为测试用 mock 实现。plugins/mock-router.ts 则将源码中所有对redwoodjs/router的导入改写为storybook-framework-redwoodjs-vite/dist/mocks/MockRouter让routes对象等路由能力在 Storybook 环境中可用对应 MockRouter.tsx。版本演进说明从 Webpack 到 Vite值得说明的是本文所依据的 version-5.x 文档描述的配置方式web/config下的三个文件与redwoodjs/testing中的默认配置属于该版本的集成方案而当前仓库 packages/storybook 中的实现已演进为基于 Vite 的框架包方案storybook-framework-redwoodjs-vite构建产物与生产项目对齐。如果你此前使用的是旧版 Webpack 集成且没有自定义配置升级后开箱即用体验保持一致如果存在自定义 Storybook 配置例如全局 decorators则需要按新方案迁移全局 decorators 现在可以直接遵循 Storybook 官方文档中的全局 decorator 方式配置。无论采用哪个版本核心的配置心智模型是一致的Storybook 的服务器配置、UI 配置与渲染配置分离并且始终与 RedwoodJS 的默认配置合并生效。总结RedwoodJS 的 Storybook 集成让组件驱动开发成为现实一条yarn rw storybook命令即可在7910端口获得隔离的组件开发环境web/config下的三个配置文件分别掌控服务器、渲染与 UI而框架层源码则默默替你完成了 Redwood 运行时注入、GraphQL mock、认证 mock、路由 mock 与 MSW 启动等全部底层工作。理解这些机制后你既可以在配置层面按需定制也能在遇到问题时从源码层面定位原因——这正是高效使用组件驱动工作流的关键。赞分享后端前端Web框架开发工具【免费下载链接】redwoodRedwoodGraphQL项目地址https://gitcode.com/gh_mirrors/re/redwood点击查看免费下载相关推荐RedwoodJS 使用 Storybook 进行组件驱动开发启动、配置与深度实践指南RedwoodJS 使用 Storybook 进行组件驱动开发启动、配置与深度实践指南 导读 Storybook 是 RedwoodJS 官方推荐的组件驱动开后端前端Web框架开发工具RedwoodJS 组件驱动开发实战从 Storybook 启动、隔离调试到三层配置扩展RedwoodJS 组件驱动开发实战从 Storybook 启动、隔离调试到三层配置扩展 本篇指南围绕 RedwoodJS当前仓库即 redwood htt后端前端Web框架开发工具RedwoodJS Storybook 集成指南基于 Vite 的组件驱动开发工作流RedwoodJS Storybook 集成指南基于 Vite 的组件驱动开发工作流 导读 Storybook 是 RedwoodJS 官方支持的组件驱动开发后端前端Web框架开发工具上一篇EPDiy快速入门从硬件接线到显示第一幅图像的完整教程下一篇Dandelion多环境部署策略如何管理开发、测试、生产环境的配置创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考