Support for Nested __root.tsx Files for Route Wrapping and Data Preloading

[scefali]

Description
It would be extremely beneficial to support a nested __root.tsx file in Tanstack router. The idea is to allow developers to wrap all components within a specific route segment (e.g. /organizations/) in a common root component. This would let us load necessary data (such as organization details) and delay rendering until that data is available, as well as set up a shared context.

Motivation
Currently, there isn’t a straightforward way to define a nested root for routes. As a result, if I want to ensure that no route under /organizations/ renders until the organization has been successfully loaded—and, for instance, guarantee that a hook like useOrganization always returns a valid organization—I need to wrap each individual route manually. This approach increases boilerplate and reduces clarity.
The ability to place a __root.tsx file (or similar mechanism) in the file structure would allow:

• Preloading Data: Delay rendering of child components until the organization data (or any other required data) is loaded.
• Guarding Routes: Redirect or block access if prerequisites (like being signed in or having an organization) are not met.
• Context Setup: Provide a centralized context for all nested routes, enabling more robust type guarantees and easier state management.

Proposed Implementation
Introduce a convention in the router that automatically detects and uses a nested root file (e.g. __root.tsx) within a route directory. When present, the router should:

• Wrap all child routes under that directory with the exported component from __root.tsx.
• Allow for logic such as data preloading, guarding routes, or providing shared contexts before any child route is rendered.

Example
Below is an example of what I’d like to achieve using this new feature:

import { useEffect } from 'react'
import { createRootRoute, Outlet, useNavigate } from '@tanstack/react-router'
import { useOrganization, useUser } from '@clerk/clerk-react'
import { Spinner } from '@radix-ui/themes'


export const Route = createRootRoute('/organizations/__root')({
  component: OrganizationRootComponent,
})

function OrganizationRootComponent() {
  const { isLoaded, isSignedIn } = useUser()
  const { organization, isLoaded: isOrgLoaded } = useOrganization()
  const navigate = useNavigate()

  useEffect(() => {
    if (isLoaded && isOrgLoaded) {
      if (!isSignedIn || !organization) {
        navigate({ to: '/' })
      }
    }
  }, [isLoaded, isOrgLoaded, isSignedIn, organization, navigate])

  // if no org, render a spinner
  if (!isLoaded || !isOrgLoaded) {
    return (
      <div className="flex items-center justify-center min-h-screen bg-gray-900">
        <Spinner />
      </div>
    )
  }

  // org is loaded at this point, we can render children that require an organization
  return <Outlet />
}

Currently, my workaround for organization-specific routes looks like this:

const route = "/organizations/$organizationId/";

export const Route = createFileRoute(route)({
  component: () => (
    <OneOrganizationRouteWrapper route={route}>
      <OrganizationIndexPage />
    </OneOrganizationRouteWrapper>
  ),
});

This workaround is less ideal because it requires manually wrapping each route. By using a nested __root.tsx file, all routes under /organizations/ could be automatically wrapped in the desired logic.

Expected Behavior
With this feature, the router should:

• Detect a nested __root.tsx (or similarly named file) in a directory.
• Use the exported component from this file as a wrapper for all child routes.
• Allow developers to perform data preloading, enforce route guards, and set up shared contexts before any nested route renders.

Benefits

• Cleaner Route Files: Reduce repetitive boilerplate by having a single wrapper component for a whole segment of routes.
• Consistent Preloading & Guarding: Ensure that required data and authentication state is always available for nested routes.
• Improved Developer Experience: Enhance type safety and streamline route configuration, particularly for nested routes that share common dependencies.

[mawallace]

You can already achieve this using something like

routes/
|- __root.tsx
|- organizations.tsx  <-- this is the wrapper you're looking for
|- organizations/
   |- $organizationId.tsx

This is documented here: https://tanstack.com/router/latest/docs/framework/react/routing/file-based-routing.

For what it's worth, I would also prefer nested __root.tsx files for this (in my opinion, everything related to /some/path should be in the routes/some/path directory).