Directory-Based Routing Basics

Lesson 1 — Folders, route files, and nesting

TanStack Router supports directory-based routing just like Next.js. A folder is a path segment, and route.tsx defines the route component. The mental model carries over — you just need to know which files do what.

From Next.js to TanStack Router

In Next.js App Router:

In TanStack Router (directory-based):

Route Files: What Goes Where

Layout Routes vs Index Routes

Layout route (route.tsx): Renders children via <Outlet />

// routes/settings/route.tsx
import { Outlet, createFileRoute } from '@tanstack/react-router'

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

function SettingsLayout() {
  return (
    <div>
      <h1>Settings</h1>
      <Outlet />  {/* child routes render here */}
    </div>
  )
}

Index route (index.tsx): Renders at the parent path, no children

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

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

function SettingsHome() {
  return <div>Choose a setting from the sidebar</div>
}

The <Outlet> = Where Children Render

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

When you visit /settings/account:

TanStack Router renders both components, plugging the child into the outlet:

Building a Mobile-Like App

Let's model a typical mobile social app: tabs at the bottom, detail screens, and settings.

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.

Quick Quiz