tanstack-solid-router

用途

@tanstack/solid-router 是 TanStack Router 的 Solid 绑定，用于在 Solid 应用中实现类型安全的文件式路由。它构建在 router-core 之上，使用前应先了解 router-core 的基础概念。

主要能力

• 文件式路由：通过 Vite 插件自动生成路由树，支持自动代码分割。
• 类型安全：路由类型完全推断，Link、useNavigate、useSearch 等具备类型安全，无需手动标注或强制转换。
• 组件：RouterProvider、Link、Outlet、Navigate、Await、CatchBoundary、CatchNotFound、Block、ScrollRestoration、ClientOnly，以及 HeadContent、Scripts 用于头部管理。
• 钩子：useRouter、useRouterState、useNavigate、useSearch、useParams、useLoaderData、useMatch、useMatches、useParentMatches、useChildMatches、useRouteContext、useLoaderDeps、useBlocker、useCanGoBack、useLocation、useLinkProps、useMatchRoute、useHydrated。
• Solid 特有模式：createLink 创建自定义 Link 组件，结合 Solid 原语（createMemo、Show、For）使用路由状态，通过 createRootRouteWithContext 与 router context 实现鉴权。

使用方式

安装依赖：

npm install @tanstack/solid-router npm install -D @tanstack/router-plugin @tanstack/solid-router-devtools

配置 Vite 插件（必须位于 solid 插件之前）：

// vite.config.ts import { defineConfig } from 'vite' import solidPlugin from 'vite-plugin-solid' import { tanstackRouter } from '@tanstack/router-plugin/vite'

export default defineConfig({ plugins: [ tanstackRouter({ target: 'solid', autoCodeSplitting: true, }), solidPlugin(), ], })

创建根路由、路由文件，并在 main.tsx 中创建 router 实例、注册类型后渲染：

import { render } from 'solid-js/web' import { RouterProvider, createRouter } from '@tanstack/solid-router' import { routeTree } from './routeTree.gen'

const router = createRouter({ routeTree })

declare module '@tanstack/solid-router' { interface Register { router: typeof router } }

render( () => <RouterProvider router={router} />, document.getElementById('root')!, )

钩子使用要点：多数钩子返回 Accessor<T>，必须调用（如 value()）才能读取响应式值；useRouter 返回 TRouter，useNavigate 返回函数，二者不是 Accessor。useSearch、useParams、useLoaderData、useMatch 等需要传入 from 参数。

适用场景

• 使用 Solid 构建的单页应用，需要类型安全的路由、参数与搜索参数管理。
• 需要客户端数据加载（loader 默认在客户端运行）、导航拦截（未保存更改）、滚动恢复、延迟数据渲染（Await + Suspense）等场景。
• 需要基于路由上下文进行鉴权控制的场景。

限制与注意事项

• 类型完全推断：不要强制转换，也不要标注推断值。
• 客户端优先：loader 默认在客户端运行，而非服务端。
• 多数钩子返回 Accessor<T>，忘记调用是常见错误。
• 不要解构响应式值，会破坏 Solid 的响应式追踪。
• beforeLoad 和 loader 不是组件，是普通异步函数，不能在其中使用钩子，应通过 router context 传递状态。
• 插件配置必须设置 target: 'solid'，默认是 'react'。
• 不要将 @tanstack/solid-router 与 @solidjs/router 混淆，二者是完全不同的库，API 不同。
• ScrollRestoration 已废弃，应改用 createRouter 的 scrollRestoration: true 选项。
• 关于收费、价格、平台支持等具体信息，资料中暂未提供。