如何在 TanStack Router/Start 项目中安装并运行 Storybook 渲染依赖路由的组件【免费下载链接】storybookStorybook is the industry standard workshop for building, documenting, and testing UI components in isolation项目地址: https://gitcode.com/GitHub_Trending/st/storybook如果你的应用基于 TanStack Router 或 TanStack Start 构建组件往往依赖路由参数、loader 数据或 Start 的服务端函数直接放进普通 Storybook 会缺少路由上下文而无法渲染。Storybook 的storybook/tanstack-react框架集成专为这类项目设计它基于storybook/react-vite为每个 story 自动包一层 memory-backed TanStack Router自动 mock 路由导航和 Start 服务端入口让依赖路由或createServerFn()的组件在 Storybook 中渲染而不必启动完整的应用运行时。本文适用的环境使用 React 和 Vite 构建的 TanStack Router / TanStack Start 项目要求 React ≥ 18、Vite ≥ 7并且项目中已有tanstack/react-router如果应用使用 TanStack Start 的服务端函数还需要保留对应的 TanStack Start 包。安装 Storybook在 TanStack Router 或 TanStack Start 项目的根目录运行安装命令以 npm 为例npm create storybooklatest该命令会引导完成框架检测和安装安装完成后项目中会生成.storybook/配置目录并可以开始写 story、跑测试、写文档。如果需要更精细地控制安装过程参考 安装指南。配置框架与构建器Storybook for TanStack React 通过storybook/builder-vite使用 Vite 构建。在.storybook/main.ts中声明框架名并可通过options.builder传入 Vite 构建器选项import type { StorybookConfig } from storybook/tanstack-react; const config: StorybookConfig { framework: { name: storybook/tanstack-react, options: { builder: { // Vite builder options }, }, }, }; export default config;配置完成后运行开发服务npm run storybook如需构建静态版本运行npm run build-storybook产物位于配置的outputDir默认为storybook-static。此时 Storybook 已经为每个 story 提供了可用的 router context。它开箱支持渲染 TanStack Route 对象、按 story 设置初始路由 / 参数 / query、通过routeOverrides不改原路由对象而覆盖loader和beforeLoad、自动 mocktanstack/react-router导航尝试会被接入 Storybook spy、自动 stub TanStack Start 的服务端与运行时入口。让依赖路由的组件渲染为 story直接渲染 Route 对象通过parameters.tanstack.router.route提供 TanStack Route 对象Storybook 会从 route 中提取其 React 组件作为 story 组件。params、query与routeOverrides在route是类型化路由文件时为类型安全import type { Meta, StoryObj } from storybook/tanstack-react; import { Route } from ./Page; const meta { parameters: { layout: fullscreen, tanstack: { router: { route: Route, // Supply the Route here // Rest of these properties are type-safe params: { id: 42 }, query: { tab: details }, }, }, }, } satisfies Metatypeof Route; export default meta; type Story StoryObjtypeof meta; export const Default: Story {}; export const WithCustomLoader: Story { parameters: { tanstack: { router: { route: Route, params: { id: 42 }, routeOverrides: { /items/$id: { loader: async () ({ item: { id: 42, name: Loaded inside Storybook }, }), }, }, }, }, }, };params会插值到 URLquery追加 search params例如?tabdetailspage2path用于设置 URL fragment如#section-name。当 route 有调用真实 API 的loader或beforeLoad时用routeOverrides按 route ID 覆盖即可不需要修改原路由对象根路由用__root__作为 key。每条 override 可以覆盖loader、beforeLoad、validateSearch、loaderDeps和context。嵌套路由当route是挂在你应用路由树上的文件路由时Storybook 会自动包含父级 layout 路由使 story 按真实应用的嵌套层级渲染也可以直接传routeTree.gen.ts的routeTree导出。用path导航到具体路由用routeOverridesstub 祖先路由上的 guard 和 loader让 story 独立渲染。普通 React 组件 路由参数如果 story 渲染的是普通 React 组件而不是 route 对象仍可通过parameters.tanstack.router提供路由上下文。适合组件读取useRouterState、useSearch、useParams、useLoaderData等 hooks但你不希望以 route 本身作为 story 组件的场景。Mock 服务端函数如果组件导入了 TanStack Start 服务端函数Storybook 会把createServerFn().handler(...)的结果替换为 mock 函数你可以按 story 用标准 mock API 覆盖它从而在不改应用代码的情况下展示 loading、success、error 状态。tanstack/react-router的导入也会被自动重定向到 Storybook 兼容的 mock 层useNavigate()、useSearch()、useParams()等 hooks 在 story 中保持可用导航尝试会接入 Storybook spy可通过storybook/tanstack-react/react-router模块直接访问 mock API 做断言。常见问题排查Story 渲染报does not provide an export named default或AsyncLocalStorage is not defined这通常意味着一个 server-only 模块进入了浏览器。修复方式是 mock服务端模块本身而不是使用它的组件或路由例如Dashboard.tsx导入~/auth/session~/auth/session导入~/db/client~/db/client导入postgres—— 应 mock~/db/client。做法是从上到下读错误堆栈停在第一个你自己写的 import为它添加__mocks__文件在.storybook/preview.ts中注册 mock并在真实模块旁创建只含import type的 mock 文件避免拉入 Node.js 依赖。注意tanstack/*模块已由框架 preset 处理无需手动 mock确认已升级到最新storybook/tanstack-react仅导入createServerFn的模块也已被 mock报错来自同文件的其他 import。之所以用__mocks__文件而非 automocking是因为 automocking 仍会求值原模块及其导入对导入了postgres、pg等 Node.js-only 包的模块必须完全阻止原模块被求值__mocks__是唯一能做到这一点的方式。Storybook 中样式丢失在.storybook/preview.tsx中导入应用 CSS让它被打包进 previewimport ../src/styles/app.css;是否支持 React Server Components不支持。storybook/tanstack-react在浏览器中使用 memory-backed router 运行 story而 RSC 需要服务端运行时。如果组件是 Server Component文档建议把客户端部分拆到 Client Component 中为拆出的组件写 story。手动写了RouterProvider/createRouter装饰器storybook/tanstack-react已自动为每个 story 包裹 TanStack Router手动装饰器是冗余的应删除需要指定路由时改用parameters.tanstack.router。如果你是从storybook/react-vite迁移过来可运行npx storybook automigrate react-vite-to-tanstack-react自动完成包替换、main.ts框架属性和 story 导入路径的更新。继续深入安装和运行之后下一步是 写第一个 story、为 story 编写测试 和 编写组件文档。parameters.tanstack.router各字段的完整定义、context工厂与useRouterContext的区别、以及 TanStack Query 的QueryClient集成在 preview 中创建共享 client 并按 story seed 数据见 Storybook for TanStack React 文档。【免费下载链接】storybookStorybook is the industry standard workshop for building, documenting, and testing UI components in isolation项目地址: https://gitcode.com/GitHub_Trending/st/storybook创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考