Skip to content
Source
Sign inSign up
TanStack/router

docs(start): explain that layout routes must render <Outlet> #7852

Opendeeferentleeg(GitHub profile, opens in a new tab)wants to merge 1 commit intomain fromrefs/pull/7852/headopened

Summary

Closes #5351 — new users following the "build from scratch" getting-started flow get stuck because the guide never connects the layout route concept to the <Outlet /> component.

The "Creating File Routes" table lists posts.tsx as a "Layout" route, and the "Nested Routing" section shows the component tree <Root><Posts><Post /></Posts></Root> — but the route generator creates a placeholder component for posts.tsx that does not include <Outlet />. So when a user follows the guide and navigates to /posts/123, only the posts.tsx component renders and the child route never appears. The <Outlet /> component is documented elsewhere in the same guide but isn't bridged to the layout-route concept in the flow new users actually follow.

The fix

Two small additions to docs/start/framework/react/guide/routing.md:

  1. A > [!NOTE] callout after the "Creating File Routes" table explaining that a layout route's component must render <Outlet />, with a runnable posts.tsx example.
  2. A line under "Nested Routing" stating that the posts.tsx layout component must render <Outlet /> for <Post /> to display.

Both link to the existing #defining-routes anchor where <Outlet /> is shown.

Note

I see there's a draft PR (#7831) touching this area — happy to coordinate or withdraw if that one progresses; this PR is an independent, self-contained docs addition.

AI usage

An AI assistant was used to help locate the relevant code and draft this change. I have reviewed and understand every line of the diff, and I am the sole author of this contribution.

Closes #5351

Summary by CodeRabbit

  • Documentation
    • Clarified nested routing behavior and the requirement to render an <Outlet /> for child routes to appear.
    • Added guidance explaining layout routes and route generator behavior.
    • Included a practical example of using <Outlet /> in a layout route.
    1. Review Change Stack

      📝 Walkthrough

      Walkthrough

      The React routing guide now explains that posts.tsx is a layout route and must render <Outlet /> for matching child routes to appear. It also documents the generated placeholder behavior and provides a corrected layout example.

      Changes

      Nested routing guide

      Layer / File(s)Summary
      Document layout route rendering
      docs/start/framework/react/guide/routing.md
      Clarifies that child routes require <Outlet /> in posts.tsx, explains the generator-created placeholder, and adds a complete layout example.

      Estimated code review effort: 1 (Trivial) | ~2 minutes

      Suggested labels: package: router-generator

      🚥 Pre-merge checks | ✅ 5
      ✅ Passed checks (5 passed)
      Check nameStatusExplanation
      Description Check✅ PassedCheck skipped - CodeRabbit’s high-level summary is enabled.
      Title check✅ PassedThe title clearly summarizes the documentation update about layout routes needing .
      Linked Issues check✅ PassedThe guide now tells users to add to layout routes and shows a matching example, which addresses #5351.
      Out of Scope Changes check✅ PassedThe PR only changes the React routing guide and stays focused on the documented Outlet clarification.
      Docstring Coverage✅ PassedNo functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
      ✨ Finishing Touches
      🧪 Generate unit tests (beta)
      • Create PR with unit tests

      Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

      ❤️ Share
      Comment `@coderabbitai help` to get the list of available commands.
    2. Actionable comments posted: 1

      🤖 Prompt for all review comments with AI agents
      Verify each finding against current code. Fix only still-valid issues, skip the
      rest with a brief reason, keep changes minimal, and validate.
      
      Inline comments:
      In `@docs/start/framework/react/guide/routing.md`:
      - Line 175: Update both Outlet documentation links in
      docs/start/framework/react/guide/routing.md at lines 175-175 and 207-208 to use
      the existing “The Outlet Component” section anchor instead of `#defining-routes`,
      preserving the relative documentation-link convention at the sibling site.
      🪄 Autofix (Beta)

      Fix all unresolved CodeRabbit comments on this PR:

      • Push a commit to this branch (recommended)
      • Create a new PR with the fixes

      ℹ️ Review info
      ⚙️ Run configuration

      Configuration used: defaults

      Review profile: CHILL

      Plan: Pro

      Run ID: da2d612a-3079-43fb-9e19-8fa454c8c6b6

      📥 Commits

      Reviewing files that changed from the base of the PR and between 31a634d84ecf393dfb95adcf713fd5f1a13ab347 and b9d177787b1aef8bebd2007b34d2b1f9ef5e245c.

      📒 Files selected for processing (1)
      • docs/start/framework/react/guide/routing.md
      docs/start/framework/react/guide/routing.md line 175
      @@ -172,3 +172,4 @@
      172172 </Root>
      173173 ```
      174174
      175+For this tree to render, the `posts.tsx` layout route's component must render an [`<Outlet />`](#defining-routes) — that's where the matching child route (`<Post />`) is displayed. Without `<Outlet />`, only the `<Posts>` component renders and the child route will not appear.

      🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

      Fix both links to the Outlet documentation. Both additions use #defining-routes, which points to the “Defining Routes” section rather than the existing “The Outlet Component” section.

      • docs/start/framework/react/guide/routing.md#L175-L175: replace the anchor with the correct Outlet-section link.
      • docs/start/framework/react/guide/routing.md#L207-L208: replace the repeated incorrect anchor and follow the relative documentation-link convention.
      📍 Affects 1 file
      • docs/start/framework/react/guide/routing.md#L175-L175 (this comment)
      • docs/start/framework/react/guide/routing.md#L207-L208
      🤖 Prompt for AI Agents
      Verify each finding against current code. Fix only still-valid issues, skip the
      rest with a brief reason, keep changes minimal, and validate.
      
      In `@docs/start/framework/react/guide/routing.md` at line 175, Update both Outlet
      documentation links in docs/start/framework/react/guide/routing.md at lines
      175-175 and 207-208 to use the existing “The Outlet Component” section anchor
      instead of `#defining-routes`, preserving the relative documentation-link
      convention at the sibling site.

      Source: Coding guidelines

Sign in to join this conversation.