Capstone: A Mobile Route Tree

Lesson 4 — combining pathless layouts, groups, and dynamic segments into one tree

You've learned every routing primitive in isolation. Now we compose them into the structure the whole mission has been building toward: a 3-level nested mobile app — app shell → bottom tabs → detail screen. This is the last open mission item. Get this right and TanStack routing clicks into place.

The Mission, Revisited

From MISSION.md: build a 3-level deeply nested layout (app → tabs → detail) without trial-and-error.

Concretely, a mobile feed app needs:

1. An app shell — status bar, safe-area, providers — present on every screen, but not part of any URL.
2. A bottom tab bar — Home, Feed, Profile — persistent across those screens, also invisible in the URL.
3. Detail screens — /feed/42 — that open on top of the tab bar, captured via $param.

Three layers, two of them URL-invisible. This is exactly what pathless layouts and groups were invented for.

Decompose the Screens

Before touching files, classify each screen by which primitive it needs:

Level 1: The App Shell (_app)

Start with the outermost pathless layer — the shell that wraps everything. A folder prefixed with _ is a pathless layout: its route.tsx renders, but the folder name never enters the URL.

// routes/_app/route.tsx
export const Route = createFileRoute('/_app')({
  component: AppShell,
})
function AppShell() {
  return (
    <div className="phone-frame">
      <StatusBar />
      <Outlet />   {/* everything inside _app renders here */}
    </div>
  )
}

Because _app is pathless, <Outlet/> here renders whatever route is matched underneath it — without /app ever appearing in the URL.

Level 2: The Tab Bar ((tabs) Group)

Inside _app, nest a pathless group. A group is a pathless folder whose name is wrapped in parentheses — purely organizational, but its route.tsx still renders as a layout. Perfect for a tab bar that wraps the tab screens:

// routes/_app/(tabs)/route.tsx
export const Route = createFileRoute('/_app/(tabs)')({
  component: TabLayout,
})
function TabLayout() {
  return (
    <>
      <Outlet />        {/* the active tab screen */}
      <BottomNav />     {/* persistent tab bar */}
    </>
  )
}

Level 3: Detail Screen ($postId)

Now drop the actual tab screens inside the group. The Feed tab is special — it has both a list and a detail. The list is an index.tsx (exact match on /feed); the detail uses a $postId dynamic segment:

Visiting /feed/42 resolves $postId to "42" — read it with Route.useParams(), exactly like Lesson 3. No new concept; just nesting.

The Full Tree

Notice search/ sits next to _app, not inside it — a full-screen route with no tab bar. That's the payoff of pathless layers: routes outside the group escape the chrome for free.

Component nesting (what renders)

Four components nest like Russian dolls. Each <Outlet/> hands off to the next layer down, until the leaf route renders your actual UI.

URL → Components Walkthrough

This is the moment of truth — read a URL and predict the rendered component stack:

Practice Exercise

Extend the app with a new requirement: a Profile detail screen at /profile/u/ana (note the literal /u/ segment), still inside the tab bar. Plus a full-screen settings page with no tabs.

Answer mentally first: which folders go inside (tabs)? Which sit next to _app? Where does the literal u segment live? Then reveal.

Quick Quiz

Primary source: TanStack Router — Route Trees (how the flat file tree builds the nested route tree). Read it to see the matching algorithm that powers the walkthrough table above.