TanStack Router 入门：文件路由、类型安全导航、Loader 与 Search Params

npx @tanstack/cli create --router-only

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

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

export default defineConfig({
  plugins: [
    // '@tanstack/router-plugin' 必须放在 '@vitejs/plugin-react' 之前
    tanstackRouter({
      target: 'react',
      autoCodeSplitting: true,
    }),
    react(),
  ],
})

// src/routes/__root.tsx
import { createRootRoute, Link, Outlet } from '@tanstack/react-router'
import { TanStackRouterDevtools } from '@tanstack/react-router-devtools'

function RootLayout() {
  return (
    <>
      <nav style={{ display: 'flex', gap: 8, padding: 8 }}>
        <Link to="/">Home</Link>
        <Link to="/posts">Posts</Link>
      </nav>
      <hr />
      <Outlet />
      <TanStackRouterDevtools />
    </>
  )
}

export const Route = createRootRoute({ component: RootLayout })

// src/routes/index.tsx
import { createFileRoute } from '@tanstack/react-router'

export const Route = createFileRoute('/')({
  component: Index,
})

function Index() {
  return <h3>Welcome Home!</h3>
}

// src/main.tsx
import { StrictMode } from 'react'
import ReactDOM from 'react-dom/client'
import { RouterProvider, createRouter } from '@tanstack/react-router'
import { routeTree } from './routeTree.gen'

const router = createRouter({ routeTree })

// 关键：把 router 的类型注册给全局，Link / useSearch / useParams 才有精确类型
declare module '@tanstack/react-router' {
  interface Register {
    router: typeof router
  }
}

const rootElement = document.getElementById('root')!
if (!rootElement.innerHTML) {
  ReactDOM.createRoot(rootElement).render(
    <StrictMode>
      <RouterProvider router={router} />
    </StrictMode>,
  )
}

import { Link } from '@tanstack/react-router'

// 静态路由
<Link to="/about">About</Link>

// 动态参数：漏传或写错 params key 会是 TypeScript 错误
<Link to="/posts/$postId" params={{ postId: post.id }}>
  {post.title}
</Link>

// 激活态样式
<Link
  to="/posts"
  activeProps={{ className: 'font-bold' }}
  activeOptions={{ exact: true }}
>
  Posts
</Link>

// 预加载：鼠标悬停/聚焦意图触发
<Link to="/posts" preload="intent">Posts</Link>

import { useNavigate } from '@tanstack/react-router'

function CreatePostButton() {
  const navigate = useNavigate()
  return (
    <button onClick={() => navigate({ to: '/posts/$postId', params: { postId: 'new' } })}>
      新建
    </button>
  )
}

import { redirect } from '@tanstack/react-router'

throw redirect({ to: '/login', search: { redirect: location.href } })

// src/routes/posts.index.tsx
import { createFileRoute } from '@tanstack/react-router'
import { z } from 'zod'

const postSearchSchema = z.object({
  page: z.number().default(1),
  filter: z.string().default(''),
  sort: z.enum(['newest', 'oldest']).default('newest'),
})

export const Route = createFileRoute('/posts/')({
  validateSearch: postSearchSchema,
  component: PostList,
})

type ProductSearch = { page: number; filter: string }

export const Route = createFileRoute('/shop/products')({
  validateSearch: (search: Record<string, unknown>): ProductSearch => ({
    page: Number(search?.page ?? 1),
    filter: (search.filter as string) || '',
  }),
})

function PostList() {
  const { page, filter, sort } = Route.useSearch() // 已校验、已带默认值、有精确类型
  // ...
}

import { getRouteApi, useSearch } from '@tanstack/react-router'

const routeApi = getRouteApi('/posts/')

function Pagination() {
  const { page } = routeApi.useSearch()
  // 等价写法：useSearch({ from: '/posts/' })
}

// 用 Link
<Link to="." search={(prev) => ({ ...prev, page: prev.page + 1 })}>
  下一页
</Link>

// 用 navigate
const navigate = useNavigate({ from: Route.fullPath })
navigate({ search: (prev) => ({ ...prev, page: prev.page + 1 }) })

// src/routes/posts.index.tsx
export const Route = createFileRoute('/posts/')({
  validateSearch: postSearchSchema,
  // 只声明 loader 真正用到的依赖
  loaderDeps: ({ search: { page, filter } }) => ({ page, filter }),
  loader: ({ deps: { page, filter } }) => fetchPosts({ page, filter }),
  component: PostList,
})

function PostList() {
  const { items, total } = Route.useLoaderData()
  // ...
}

const router = createRouter({
  routeTree,
  defaultPreload: 'intent',
  defaultStaleTime: 0,
  defaultPreloadStaleTime: 30_000,
  defaultGcTime: 5 * 60 * 1000,
})

export const Route = createFileRoute('/dashboard')({
  loader: async () => {
    const fastData = await fetchFast()
    const deferredSlowData = fetchSlow() // 注意：不 await
    return { fastData, deferredSlowData }
  },
})

function Dashboard() {
  const { fastData, deferredSlowData } = Route.useLoaderData()
  return (
    <>
      <Fast data={fastData} />
      <Await promise={deferredSlowData} fallback={<div>Loading...</div>}>
        {(data) => <Slow data={data} />}
      </Await>
    </>
  )
}

import { createFileRoute, notFound } from '@tanstack/react-router'

export const Route = createFileRoute('/posts/$postId')({
  loader: async ({ params }) => {
    const post = await fetchPost(params.postId)
    if (!post) throw notFound()
    return post
  },
  pendingComponent: () => <div>加载中…</div>,
  errorComponent: ({ error }) => <div>出错了：{String(error)}</div>,
  notFoundComponent: () => <div>这篇文章不存在</div>,
  component: PostDetail,
})

// src/routes/__root.tsx
import { createRootRouteWithContext } from '@tanstack/react-router'
import type { QueryClient } from '@tanstack/react-query'

interface MyRouterContext {
  queryClient: QueryClient
  auth: AuthState
}

export const Route = createRootRouteWithContext<MyRouterContext>()({
  component: RootLayout,
})

// src/main.tsx
const router = createRouter({
  routeTree,
  context: { queryClient, auth: undefined! }, // auth 在 RouterProvider 处补齐
})

function App() {
  const auth = useAuth()
  return <RouterProvider router={router} context={{ auth }} />
}

// src/routes/_authenticated.tsx
import { createFileRoute, redirect } from '@tanstack/react-router'

export const Route = createFileRoute('/_authenticated')({
  beforeLoad: ({ context, location }) => {
    if (!context.auth.isAuthenticated) {
      throw redirect({ to: '/login', search: { redirect: location.href } })
    }
  },
})

const router = createRouter({
  routeTree,
  defaultPreload: 'intent', // 'intent' | 'viewport' | 'render' | false
})

<Link to="/posts" preload="intent" preloadDelay={100}>Posts</Link>

import { queryOptions, useSuspenseQuery } from '@tanstack/react-query'

const postsQueryOptions = (page: number) =>
  queryOptions({
    queryKey: ['posts', page],
    queryFn: () => fetchPosts({ page }),
  })

export const Route = createFileRoute('/posts/')({
  validateSearch: postSearchSchema,
  loaderDeps: ({ search: { page } }) => ({ page }),
  loader: ({ context: { queryClient }, deps: { page } }) =>
    queryClient.ensureQueryData(postsQueryOptions(page)),
  component: PostList,
})

function PostList() {
  const { page } = Route.useSearch()
  const { data } = useSuspenseQuery(postsQueryOptions(page)) // 命中 loader 预热的缓存
  return <List items={data.items} />
}