ReactでTanStack Routerを使い、型の付いたルーティングを書く方法

const rootRoute = createRootRoute({
  component: () => (
    <>
      <nav>
        <Link to="/">トップ</Link>{' '}
        <Link to="/cats" search={{ sort: 'name' }}>猫の一覧</Link>
      </nav>
      <Outlet />
    </>
  ),
})

const indexRoute = createRoute({
  getParentRoute: () => rootRoute,
  path: '/',
  component: () => <h1>トップ</h1>,
})

type CatsSearch = { sort: 'name' | 'age' }

const catsRoute = createRoute({
  getParentRoute: () => rootRoute,
  path: 'cats',
  validateSearch: (search: Record<string, unknown>): CatsSearch => ({
    sort: search.sort === 'age' ? 'age' : 'name',
  }),
  component: CatsPage,
})

const catRoute = createRoute({
  getParentRoute: () => rootRoute,
  path: 'cats/$catId',
  params: {
    parse: ({ catId }) => ({ catId: Number(catId) }),
    stringify: ({ catId }) => ({ catId: String(catId) }),
  },
  component: CatPage,
})

const routeTree = rootRoute.addChildren([indexRoute, catsRoute, catRoute])

export const router = createRouter({ routeTree })

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

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

export function Mistakes() {
  const navigate = useNavigate()
  return (
    <>
      {/* 1. パスの書き間違い（cats を cat と書いた） */}
      <Link to="/cat">一覧</Link>
      {/* 2. パスパラメーターを渡し忘れた */}
      <Link to="/cats/$catId">たま</Link>
      {/* 3. catId に文字列を渡した（parse で number にしている） */}
      <Link to="/cats/$catId" params={{ catId: '1' }}>たま</Link>
      {/* 4. sort に決めていない値を渡した */}
      <Link to="/cats" search={{ sort: 'weight' }}>体重順</Link>
      {/* 5. search を渡し忘れた */}
      <Link to="/cats">一覧</Link>
      {/* 6. navigate でパラメーターの名前を間違えた */}
      <button onClick={() => navigate({ to: '/cats/$catId', params: { id: 1 } })}>
        移動
      </button>
    </>
  )
}

$ npx tsc -p tsconfig.mistakes.json --pretty false; echo "exit=$?"
mistakes/mistakes.tsx(8,13): error TS2820: Type '"/cat"' is not assignable to type '"." | ".." | "/" | "/cats" | "/cats/$catId"'. Did you mean '"/cats"'?
mistakes/mistakes.tsx(10,8): error TS2741: Property 'params' is missing in type '{ to: "/cats/$catId"; children: string; }' but required in type 'MakeRequiredPathParams<…'.
mistakes/mistakes.tsx(12,41): error TS2322: Type 'string' is not assignable to type 'number'.
mistakes/mistakes.tsx(14,34): error TS2322: Type '"weight"' is not assignable to type '"age" | "name"'.
mistakes/mistakes.tsx(16,8): error TS2741: Property 'search' is missing in type '{ to: "/cats"; children: string; }' but required in type 'MakeRequiredSearchParams<…'.
mistakes/mistakes.tsx(18,71): error TS2353: Object literal may only specify known properties, and 'id' does not exist in type 'ParamsReducerFn<…'.
exit=1

const rootRoute = createRootRoute()
const catsRoute = createRoute({
  getParentRoute: () => rootRoute,
  path: 'cats',
})
const routeTree = rootRoute.addChildren([catsRoute])
export const router = createRouter({ routeTree })

export function Nav() {
  // パスを書き間違えても、型チェックを通ってしまう
  return <Link to="/cat">一覧</Link>
}

$ npx tsc -p tsconfig.noreg.json --pretty false; echo "exit=$?"
exit=0

function CatPage() {
  const { catId } = catRoute.useParams() // catId の型は number
  const cat = cats.find((c) => c.id === catId)
  if (!cat) return <h1>見つかりません</h1>
  return (
    <>
      <h1>{cat.name}</h1>
      <p>{cat.age}歳（catId: {catId}、型: {typeof catId}）</p>
    </>
  )
}

function CatsPage() {
  const { sort } = catsRoute.useSearch() // sort の型は 'name' | 'age'
  const list = [...cats].sort((a, b) =>
    sort === 'age' ? a.age - b.age : a.name.localeCompare(b.name, 'ja'),
  )
  return (
    <>
      <h1>猫の一覧（{sort === 'age' ? '年齢順' : '名前順'}）</h1>
      <Link to="/cats" search={{ sort: 'name' }}>名前順</Link>{' '}
      <Link to="/cats" search={{ sort: 'age' }}>年齢順</Link>
      <ul>
        {list.map((cat) => (
          <li key={cat.id}>
            <Link to="/cats/$catId" params={{ catId: cat.id }}>
              {cat.name}
            </Link>
          </li>
        ))}
      </ul>
    </>
  )
}

type CatsSearch = { sort?: 'name' | 'age' }

const catsRoute = createRoute({
  getParentRoute: () => rootRoute,
  path: 'cats',
  validateSearch: (search: Record<string, unknown>): CatsSearch => ({
    sort: search.sort === 'age' ? 'age' : undefined,
  }),
})

$ npx tsc -p tsconfig.optional.json --pretty false; echo "exit=$?"
optional/router.tsx(27,34): error TS2322: Type '"weight"' is not assignable to type '"age" | "name" | undefined'.
exit=1

/cats?sort=weight を直接開く
  URL: /cats?sort=name
  h1: 猫の一覧（名前順）
  li: クロ, たま, ミケ
/cats を search なしで直接開く
  URL: /cats?sort=name
  h1: 猫の一覧（名前順）
  li: クロ, たま, ミケ