Loaders & Data

Lesson 7 — type-safe data fetching tied to your route tree

Routes need data. A post detail screen needs the post; a feed list needs the posts. TanStack's loader co-locates data fetching with the route, runs it before the component mounts, and exposes the result through a typed hook. Combined with params and search params from earlier lessons, you get end-to-end type safety from URL to fetch to JSX.

What a Loader Is

A function declared on the route that runs before the component renders. Its return value is cached and handed to the component via a typed hook. Loaders run in parallel for matched routes — the parent and child fetch concurrently, not serially.

• Runs on route entry, before mount
• Re-runs when its inputs change (params, search deps)
• Return value is typed end-to-end
• Can be preloaded on link hover (separate topic)

A Basic Loader

// routes/_app/(tabs)/feed/$postId/index.tsx
import { createFileRoute } from '@tanstack/react-router'

export const Route = createFileRoute('/_app/(tabs)/feed/$postId')({
  // 1. Declare the loader — async function, returns anything
  loader: async ({ params }) => {
    const res = await fetch(`/api/posts/${params.postId}`)
    return res.json()  // typed as Post via inference or generic
  },
  component: PostScreen,
})

function PostScreen() {
  // 2. Read the result — typed, no loading state to manage
  const post = Route.useLoaderData()
  //    ^? Post
  return <article>{post.title}</article>
}

Reading the Result

Two ways:

// 1. On the route itself (preferred inside this route's tree)
const post = Route.useLoaderData()

// 2. Anywhere else — getRouteApi (avoids circular deps in code-split trees)
import { getRouteApi } from '@tanstack/react-router'
const routeApi = getRouteApi('/_app/(tabs)/feed/$postId')
const post = routeApi.useLoaderData()

For type inference, either annotate the loader's return type explicitly or let TypeScript infer it from your fetch wrapper.

Loader Parameters

The loader receives a single object with everything you need:

// params comes from the route path — typed as { postId: string }
loader: async ({ params, signal }) => {
  const res = await fetch(`/api/posts/${params.postId}`, { signal })
  return res.json()
}

loaderDeps — Pipe Search Params In

By default, a loader re-runs only on param changes. If it depends on search params (like pagination offset), declare those deps explicitly. loaderDeps extracts a stable subset of search that triggers re-fetches:

import { z } from 'zod'

export const Route = createFileRoute('/_app/(tabs)/feed')({
  // 1. Validate search params
  validateSearch: z.object({
    offset: z.number().int().nonnegative().catch(0),
  }),

  // 2. Extract what the loader needs
  loaderDeps: ({ search: { offset } }) => ({ offset }),

  // 3. Use deps, not search directly
  loader: async ({ deps: { offset } }) => {
    const res = await fetch(`/api/posts?offset=${offset}`)
    return res.json()
  },
})

Stale & GC Defaults

TanStack caches loader results. Know the defaults:

Override per-route via staleTime and gcTime options. router.invalidate() force-reloads all active loaders.

Error Handling

A thrown error in the loader bubbles to the route's errorComponent. Provide one per route that can fail, and fall back to the default for safety:

export const Route = createFileRoute('/_app/(tabs)/feed/$postId')({
  loader: () => fetchPost(),  // may throw
  errorComponent: ({ error }) => {
    if (error instanceof NotFoundError) {
      return <div>Post not found</div>
    }
    return <ErrorComponent error={error} />  // default fallback
  },
})

Errors render at the route boundary they're thrown from — a child loader failure won't unmount the parent's shell.

Next.js → TanStack Quick Map

The mental shift: in Next.js App Router, the component is the loader (async server component). In TanStack, loader and component are separate — the loader is a side-channel that runs first, the component reads its result synchronously.

Practice Exercise

The Feed list screen needs paginated posts driven by URL search params. Build:

1. A validateSearch schema with offset (number, fallback 0) and limit (number, fallback 10)
2. A loaderDeps extracting both
3. A loader that fetches with signal and returns the posts
4. A component reading both the posts and the search params

Sketch mentally, then reveal.

import { z } from 'zod'
import { createFileRoute } from '@tanstack/react-router'

export const Route = createFileRoute('/_app/(tabs)/feed')({
  validateSearch: z.object({
    offset: z.number().int().nonnegative().catch(0),
    limit: z.number().int().positive().catch(10),
  }),

  loaderDeps: ({ search: { offset, limit } }) => ({ offset, limit }),

  loader: async ({ deps: { offset, limit }, signal }) => {
    const res = await fetch(
      `/api/posts?offset=${offset}&limit=${limit}`,
      { signal }
    )
    return res.json() as Promise<Post[]>
  },

  component: FeedList,
})

function FeedList() {
  const posts = Route.useLoaderData()      // typed as Post[]
  const { offset, limit } = Route.useSearch()
  return (
    <ul>
      {posts.map(p => <li key={p.id}>{p.title}</li>)}
      <li>Showing {offset}–{offset + posts.length} (limit {limit})</li>
    </ul>
  )
}

Quick Quiz

Primary source: TanStack Router — Data Loading (Defining Loaders, loaderDeps, and Consuming Data sections). Read after the quiz.