Storybook TanStack React 迁移指南.storybook/preview.*从storybook/react-vite平滑切换【免费下载链接】storybookStorybook is the industry standard workshop for building, documenting, and testing UI components in isolation项目地址: https://gitcode.com/GitHub_Trending/st/storybook本篇技术指南以 Storybook 官方文档中的迁移片段 tanstack-react-preview-migrate.md 为核心讲解如何将 TanStack Router / TanStack Start 项目的 Storybook 预览配置从storybook/react-vite迁移到storybook/tanstack-react。读完本文你将掌握preview.tsx中Preview类型与definePreview工厂函数的迁移写法、完整的手动迁移三步流程、automigrate一键迁移的原理以及迁移后必须清理手动 TanStack Router decorator 的原因。为什么需要迁移.storybook/preview.*storybook/tanstack-react是 Storybook 针对 TanStack Router 与 TanStack Start 应用的框架集成它构建在storybook/react-vite之上额外提供了路由感知的故事渲染、自动路由 mock 以及 TanStack Start server function 的 mock 能力详见 tanstack-react.mdx。当你从storybook/react-vite切换到该框架后.storybook/preview.tsx中引入的Preview类型与definePreview工厂函数都必须改从新包导入否则类型系统将沿用旧框架的ProjectAnnotations无法获得 TanStack 路由参数的类型推导。这是迁移中继package.json依赖和.storybook/main.*框架声明之后的最后一步配置收尾。核心改动preview.tsx的 import 语句迁移原文档片段 tanstack-react-preview-migrate.md 提供了两种写法的 diff分别对应 CSF 3 与 CSF Next 两种 Storybook 配置风格两种写法必须完整切换。CSF 3切换Preview类型来源- import type { Preview } from storybook/react-vite; import type { Preview } from storybook/tanstack-react; const preview: Preview { //... }; export default preview;Preview类型在storybook/tanstack-react中被定义为ProjectAnnotationsReactTypes TanStackTypesTRoute从源码 index.ts 可以看到它合并了 React 渲染器类型与 TanStack 专属的TanStackTypes。这意味着切换后preview对象中的parameters.tanstack.router等字段会获得完整的类型约束路由相关参数如params、query、routeOverrides的类型将被静态校验。CSF Next切换definePreview工厂函数- import { definePreview } from storybook/react-vite; import { definePreview } from storybook/tanstack-react; export default definePreview({ //... });storybook/tanstack-react的definePreview与storybook/react-vite的版本签名兼容但内部有本质差异从源码 index.ts 可以看出它会将框架内置的tanstackPreview来自 preview.tsx作为 addon 注入到预览配置之前从而自动挂载路由 decorator、loader 与 beforeEach 逻辑。手动迁移完整三步流程preview.*的迁移是手动迁移流程的最后一步前面两步不可或缺第一步安装框架包npm install --save-dev storybook/tanstack-react其他包管理器对应命令见 tanstack-react-install.md。该集成要求项目中存在tanstack/react-router若使用 TanStack Start 的 server function 等 API还需保留对应的 Start 包React ≥ 18Vite ≥ 7。第二步更新.storybook/main.js|ts的框架声明- import type { StorybookConfig } from storybook/react-vite; import type { StorybookConfig } from storybook/tanstack-react; const config: StorybookConfig { // ... - framework: storybook/react-vite, framework: storybook/tanstack-react, }; export default config;使用 CSF Next 的defineMain写法时将storybook/react-vite/node一并替换为storybook/tanstack-react/node完整 diff 见 tanstack-react-add-framework.md。第三步更新.storybook/preview.*即本文第一节展示的两种 diff 写法。改完这三处后运行npm run storybook验证预览是否正常加载。迁移后必做移除手动 TanStack Router decorator官方文档在迁移说明中反复强调一个关键点见 tanstack-react.mdx 中的 Calloutstorybook/tanstack-react会自动为每个 story 包裹一个 TanStack Router因此迁移后应移除任何手动编写的RouterProvider/createRouter/createMemoryHistory/createRootRoutedecorator。需要指定路由的 story 应改用parameters.tanstack.router。框架自动注入的内容从框架预览入口 preview.tsx 的源码可以看到新框架自动提供了三层机制tanstackRouteDecorator路由 decorator通过applyDecorators注入且特意排列在jsxDecorator之外层以避免已知的渲染问题routeComponentLoader从parameters.tanstack.router.route提取路由的 React 组件routerBeforeEach在每条 story 渲染前重置内存路由状态。这意味着旧项目中手写的路由装饰器不仅冗余还可能与新框架的 decorator 顺序冲突导致故事渲染异常。如何定位手动 decoratorStorybook 官方 automigrate 工具使用一组特征标记来识别手动 decorator包括createMemoryHistory、createRootRoute、createRouter、RouterProvider见 react-vite-to-tanstack-react.ts并会扫描.storybook/目录下的所有*.ts|tsx|js|jsx|mjs|cjs文件以及全部*.stories.*文件。你可以用同样的关键词自查项目代码。自动迁移automigrate一键完成官方推荐的迁移方式是直接运行迁移工具npx storybook automigrate react-vite-to-tanstack-react从该迁移 fix 的源码实现 react-vite-to-tanstack-react.ts 可以梳理出它执行的完整动作更新package.json将storybook/react-vite替换为storybook/tanstack-react更新.storybook/main.js|ts中的framework属性对常规配置与defineMain配置均生效扫描并更新所有引用storybook/react-vite的 import 语句包括 story 文件与 Storybook 配置文件含 CSF Next 使用的storybook/react-vite/node——preview.*中的Preview/definePreview导入即由这一步完成切换检测到手动 TanStack Router decorator 时CLI 会生成一段可直接粘贴给 AI 助手、指导其移除冗余 decorator 的提示词复制到剪贴板。需要注意自动迁移只处理代码可以安全变换的部分手动 decorator 的移除仍需人工或借助 AI 提示词完成。迁移后的新能力parameters.tanstack.router迁移完成后preview.tsx中可以按需声明 TanStack 相关的全局参数。框架在tanstack.router命名空间下提供以下参数完整说明见 tanstack-react.mdx 的 Parameters 章节参数类型作用routeAnyRoute \| route options object直接提供路由实例或从路由选项创建临时故事路由paramsResolveParamsPath将路由参数插值进当前路径如/$id路由的{ id: string }pathstring设置故事路由的初始 URL 路径queryRecordstring, unknown向初始 URL 追加 search 参数contextRecordstring, unknown \| ({ storyContext }) Recordstring, unknown注入路由上下文工厂函数在路由初始加载前执行可被loader/beforeLoad读取routeOverridesPartialRecordstring, RouteOverrideOptions按路由 ID 覆盖loader、beforeLoad、validateSearch、loaderDeps、context用__root__定位根路由useRouterContext({ storyContext }) RouterContext以 React hook 方式在渲染期间计算路由上下文可读取 provider 中的值但无法进入初始loader/beforeLoad此外框架会自动将tanstack/react-router的导入重定向到 Storybook 兼容的 mock 层useNavigate、useSearch、useParams等 hook 在故事中可用且导航行为可被 spy 观测TanStack Start 的createServerFn()处理器也会被替换为可在故事与测试中覆写的 mock 函数。小结与常见问题迁移后 story 渲染失败并报 does not provide an export named default 或 AsyncLocalStorage is not defined说明 server-only 模块被加载进了浏览器应参考文档的 Handling server-only dependencies 章节为距离 Node.js 依赖最近的、自己编写的模块添加__mocks__文件。样式丢失在.storybook/preview.*中导入应用 CSS例如import ../src/styles/app.css。需要全局 React Context Provider通过 project-level decorator 在 preview 中注入而非在旧的手动路由 decorator 中处理。何时不应迁移如果你的项目是普通 React Vite 且不使用 TanStack Router应继续使用storybook/react-vite迁移反而引入不必要的路由 mock 层。从storybook/react-vite到storybook/tanstack-react的预览配置迁移本身只有两行 import 的变化但其背后是从手动路由装饰器到框架内置内存路由的架构升级。完成上述迁移与清理后你的 TanStack 应用组件便能在 Storybook 中以真实的路由上下文、类型安全的参数配置和可 mock 的 server function 环境下独立开发与测试。【免费下载链接】storybookStorybook is the industry standard workshop for building, documenting, and testing UI components in isolation项目地址: https://gitcode.com/GitHub_Trending/st/storybook创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考