The Route Tree Mental Model

Lesson 1 — How flat filenames build nested routing

You know Next.js: a folder is a path segment, and layout.tsx wraps its children. TanStack Router flips this: filenames are the path, and dots create nesting. The trick is learning to read a flat file tree and see the route tree in your head.

From Folders to Filenames

In Next.js:

In TanStack Router, the same idea is encoded in flat filenames with dots:

The <Outlet> = Where Children Render

In Next.js, layouts get {children} automatically. In TanStack Router, you explicitly choose where child routes render using <Outlet />.

// routes/home.tsx — a layout route
import { Outlet, createFileRoute } from '@tanstack/react-router'

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

function HomeLayout() {
  return (
    <div className="feed-layout">
      <nav>Feed • Explore • Profile</nav>
      <Outlet />  {/* ← child route renders here */}
    </div>
  )
}

When you visit /home/42, TanStack Router finds both home.tsx and home.$postId.tsx, renders the layout, and plugs the child into the outlet:

Building a Mobile-Like App

Let's model a typical mobile social app: tabs at the bottom, detail screens that slide in, and settings tucked behind a layout.

How it composes

Notice how /posts/42 renders <PostDetail /> inside the app layout. But /posts/42/comments renders <Comments /> inside <PostDetail /> — which is itself inside <AppLayout />. Three levels of nesting, entirely from filenames.

Quick Quiz