react-router

원본 Skill 문서

원본 저장소의 제목, 예시, 코드, 표, 링크, 이미지를 유지해 표시합니다.

React Router (`@tanstack/react-router`)

This skill builds on router-core. Read router-core first for foundational concepts.

CRITICAL: TanStack Router types are FULLY INFERRED. Never cast, never annotate inferred values. CRITICAL: TanStack Router is CLIENT-FIRST. Loaders run on the client by default, not on the server. CRITICAL: Do not confuse @tanstack/react-router with react-router-dom/react-router. They are completely different libraries with different APIs.

Full Setup: File-Based Routing with Vite

1. Install Dependencies

bash

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

2. Configure Vite 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: [
    // MUST come before react()
    tanstackRouter({
      target: 'react',
      autoCodeSplitting: true,
    }),
    react(),
  ],
})

3. Create Root Route

tsx

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

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

function RootLayout() {
  return (
    <>
      <nav>
        <Link to="/" className="[&.active]:font-bold">
          Home
        </Link>
        <Link to="/about" className="[&.active]:font-bold">
          About
        </Link>
      </nav>
      <hr />
      <Outlet />
      <TanStackRouterDevtools />
    </>
  )
}

4. Create Route Files

tsx

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

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

function HomePage() {
  return <h1>Welcome Home</h1>
}

tsx

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

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

function AboutPage() {
  return <h1>About</h1>
}

5. Create Router Instance and Register Types

tsx

// 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 })

// REQUIRED — without this, Link/useNavigate/useSearch have no type safety
declare module '@tanstack/react-router' {
  interface Register {
    router: typeof router
  }
}

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

Hooks Reference

All hooks are imported from @tanstack/react-router.

`useRouter()`

Access the router instance directly:

tsx

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

function InvalidateButton() {
  const router = useRouter()
  return <button onClick={() => router.invalidate()}>Refresh data</button>
}

`useRouterState()`

Subscribe to router state changes. Exposes the entire state and thus incurs a performance cost. For matches or location favor useMatches and useLocation.

tsx

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

function LoadingIndicator() {
  const isLoading = useRouterState({ select: (s) => s.isLoading })
  return isLoading ? <div>Loading...</div> : null
}

`useNavigate()`

Programmatic navigation (prefer <Link> for user-clickable elements):

tsx

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

function AfterSubmit() {
  const navigate = useNavigate()

  const handleSubmit = async () => {
    await saveData()
    navigate({ to: '/posts/$postId', params: { postId: '123' } })
  }

  return <button onClick={handleSubmit}>Save</button>
}

`useSearch({ from })`

Read validated search params:

tsx

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

function Pagination() {
  const { page } = useSearch({ from: '/products' })
  return <span>Page {page}</span>
}

`useParams({ from })`

Read path params:

tsx

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

function PostHeader() {
  const { postId } = useParams({ from: '/posts/$postId' })
  return <h2>Post {postId}</h2>
}

`useLoaderData({ from })`

Read data returned from the route loader:

tsx

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

function PostContent() {
  const { post } = useLoaderData({ from: '/posts/$postId' })
  return <article>{post.content}</article>
}

`useMatch({ from })`

Access the full route match (params, search, loader data, context):

tsx

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

function PostDetails() {
  const match = useMatch({ from: '/posts/$postId' })
  return <div>{match.loaderData.post.title}</div>
}

Other Hooks

All imported from @tanstack/react-router:

`useMatches()` — array of all active route matches (useful for breadcrumbs)
`useRouteContext({ from })` — read context from beforeLoad or parent routes
`useBlocker({ shouldBlockFn })` — block navigation for unsaved changes
`useCanGoBack()` — returns boolean, check if history has entries to go back to
`useLocation()` — current parsed location (pathname, search, hash)
`useLinkProps({ to, params?, search? })` — get <a> props for custom link elements
`useMatchRoute()` — returns a function: matchRoute({ to }) => match | false

Components Reference

`RouterProvider`

Mount the router at the top of your React tree:

tsx

<RouterProvider router={router} />

`Link`

Type-safe navigation link with <a> semantics:

tsx

<Link to="/posts/$postId" params={{ postId: '42' }}>
  View Post
</Link>

`Outlet`

Renders the matched child route component:

tsx

function Layout() {
  return (
    <div>
      <Sidebar />
      <main>
        <Outlet />
      </main>
    </div>
  )
}

`Navigate`

Declarative redirect component:

tsx

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

function OldPage() {
  return <Navigate to="/new-page" />
}

`Await`

Renders deferred data from unawaited loader promises with Suspense:

tsx

import { Await } from '@tanstack/react-router'
import { Suspense } from 'react'

function PostWithComments() {
  const { deferredComments } = Route.useLoaderData()
  return (
    <div>
      <h1>Post</h1>
      <Suspense fallback={<div>Loading comments...</div>}>
        <Await promise={deferredComments}>
          {(comments) => (
            <ul>
              {comments.map((c) => (
                <li key={c.id}>{c.text}</li>
              ))}
            </ul>
          )}
        </Await>
      </Suspense>
    </div>
  )
}

`CatchBoundary`

Error boundary for component-level error handling (route-level errors use errorComponent route option):

tsx

import { CatchBoundary } from '@tanstack/react-router'
;<CatchBoundary
  getResetKey={() => 'widget'}
  onCatch={(error) => console.error(error)}
  errorComponent={({ error }) => <div>{String(error)}</div>}
>
  <RiskyWidget />
</CatchBoundary>

React-Specific Patterns

Custom Link Component with `createLink`

Wrap Link in a custom component while preserving type safety:

tsx

import { createLink } from '@tanstack/react-router'
import { forwardRef, type ComponentPropsWithoutRef } from 'react'

const StyledLinkComponent = forwardRef<
  HTMLAnchorElement,
  ComponentPropsWithoutRef<'a'>
>((props, ref) => (
  <a ref={ref} {...props} className={`styled-link ${props.className ?? ''}`} />
))

const StyledLink = createLink(StyledLinkComponent)

// Usage — same type-safe props as Link
function Nav() {
  return (
    <StyledLink to="/posts/$postId" params={{ postId: '42' }}>
      Post
    </StyledLink>
  )
}

Reusable Components with Router Hooks

To create a component that uses router hooks across multiple routes, pass a union of route paths as the from prop:

tsx

function PostIdDisplay({ from }: { from: '/posts/$id' | '/drafts/$id' }) {
  const { id } = useParams({ from })
  return <span>ID: {id}</span>
}

// Usage in different route components
<PostIdDisplay from="/posts/$id" />
<PostIdDisplay from="/drafts/$id" />

This pattern avoids strict: false (which returns an imprecise union) while keeping the component reusable across specific known routes.

Auth Provider Must Wrap RouterProvider

If routes use auth context (via createRootRouteWithContext), the auth provider must be an ancestor of RouterProvider:

tsx

// CORRECT — AuthProvider wraps RouterProvider
function App() {
  return (
    <AuthProvider>
      <RouterProvider router={router} />
    </AuthProvider>
  )
}

// WRONG — RouterProvider outside auth provider
function App() {
  return (
    <RouterProvider router={router}>
      <AuthProvider>{/* ... */}</AuthProvider>
    </RouterProvider>
  )
}

Or use the Wrap router option to provide context without wrapping externally:

tsx

const router = createRouter({
  routeTree,
  Wrap: ({ children }) => (
    <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>
  ),
})

Common Mistakes

1. HIGH: Using React hooks in `beforeLoad` or `loader`

beforeLoad and loader are NOT React components — they are plain async functions. React hooks cannot be called in them. Pass auth state via router context instead.

tsx

// WRONG — useAuth is a React hook, cannot be called here
beforeLoad: () => {
  const auth = useAuth()
  if (!auth.user) throw redirect({ to: '/login' })
}

// CORRECT — read auth from router context
beforeLoad: ({ context }) => {
  if (!context.auth.isAuthenticated) {
    throw redirect({ to: '/login' })
  }
}

2. HIGH: Wrapping RouterProvider inside an auth provider incorrectly

Create the router once with an undefined! placeholder, then inject live auth via RouterProvider's context prop. Do NOT recreate the router on auth changes — this resets caches and rebuilds the tree.

tsx

// CORRECT — create router once, inject live auth via context prop
const router = createRouter({
  routeTree,
  context: { auth: undefined! }, // placeholder, filled by RouterProvider
})

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

function App() {
  return (
    <AuthProvider>
      <InnerApp />
    </AuthProvider>
  )
}

3. MEDIUM: Missing Suspense boundary for `Await`/deferred data

Await requires a <Suspense> ancestor. Without it, the deferred promise has no fallback UI and throws.

tsx

// WRONG — no Suspense boundary
<Await promise={deferredData}>{(data) => <div>{data}</div>}</Await>

// CORRECT — wrap in Suspense
<Suspense fallback={<div>Loading...</div>}>
  <Await promise={deferredData}>{(data) => <div>{data}</div>}</Await>
</Suspense>

Cross-References

router-core/SKILL.md — all sub-skills for domain-specific patterns (search params, data loading, navigation, auth, SSR, etc.)

React Router (`@tanstack/react-router`)

Full Setup: File-Based Routing with Vite

1. Install Dependencies

2. Configure Vite Plugin

3. Create Root Route

4. Create Route Files

5. Create Router Instance and Register Types

Hooks Reference

`useRouter()`

`useRouterState()`

`useNavigate()`

`useSearch({ from })`

`useParams({ from })`

`useLoaderData({ from })`

`useMatch({ from })`

Other Hooks

Components Reference

`RouterProvider`

`Link`

`Outlet`

`Navigate`

`Await`

`CatchBoundary`

React-Specific Patterns

Custom Link Component with `createLink`

Reusable Components with Router Hooks

Auth Provider Must Wrap RouterProvider

Common Mistakes

1. HIGH: Using React hooks in `beforeLoad` or `loader`

2. HIGH: Wrapping RouterProvider inside an auth provider incorrectly

3. MEDIUM: Missing Suspense boundary for `Await`/deferred data

Cross-References

더 많은 Skills

react-start

auth-and-guards

auth-server-primitives

code-splitting

react-router

React Router (@tanstack/react-router)

Full Setup: File-Based Routing with Vite

1. Install Dependencies

2. Configure Vite Plugin

3. Create Root Route

4. Create Route Files

5. Create Router Instance and Register Types

Hooks Reference

useRouter()

useRouterState()

useNavigate()

useSearch({ from })

useParams({ from })

useLoaderData({ from })

useMatch({ from })

Other Hooks

Components Reference

RouterProvider

Link

Outlet

Navigate

Await

CatchBoundary

React-Specific Patterns

Custom Link Component with createLink

Reusable Components with Router Hooks

Auth Provider Must Wrap RouterProvider

Common Mistakes

1. HIGH: Using React hooks in beforeLoad or loader

2. HIGH: Wrapping RouterProvider inside an auth provider incorrectly

3. MEDIUM: Missing Suspense boundary for Await/deferred data

Cross-References

더 많은 Skills

react-start

auth-and-guards

auth-server-primitives

code-splitting

React Router (`@tanstack/react-router`)

`useRouter()`

`useRouterState()`

`useNavigate()`

`useSearch({ from })`

`useParams({ from })`

`useLoaderData({ from })`

`useMatch({ from })`

`RouterProvider`

`Link`

`Outlet`

`Navigate`

`Await`

`CatchBoundary`

Custom Link Component with `createLink`

1. HIGH: Using React hooks in `beforeLoad` or `loader`

3. MEDIUM: Missing Suspense boundary for `Await`/deferred data