Clarification needed for child routes and layout routes

[abecks]

I am confused how child routes and layout routes work with TanStack Router. The docs show examples for "layout routes" but then calls the syntax that enables them (_ prefix) "pathless routes".

Child Routes

How is the parent route determined? There is inconsistent behavior when using file based routing and directories:

I have two components, one Parent and one Child. The Child should be rendered through the Paren't Outlet as a "child route".

Dot notation file structure works as expected:

routes/parent.tsx - Works as /parent, essentially an index route
routes/parent.active.tsx - Works as /parent/active
In the generated routeTree, the "parent.active" route's parent route is correctly define as parent.tsx

But if you switch to directories, the behavior is not consistent:

routes/parent/index.tsx - Works as /parent
routes/parent/active.tsx - Works as /parent/active BUT is missing the layout from index.tsx
In the generated routeTree, the "active" route's parent route is NOT defined as index.tsx, but rather the rootRoute

UPDATE: This is intentional, the fix is to have this structure:

routes/parent.tsx
routes/parent/active.tsx - Will correctly associate parent.tsx as it's parent route
routes/parent/index.tsx - Also allows you to provide an index route, so you can just use parent.tsx as a layout component.

Layout Routes

They aren't really "layout routes" as they cannot be nested. They are "pathless routes" which I find to be extremely confusing.

Given this file structure:

_layout.tsx
_layout/someroute.tsx - Works as expected, renders `someroute` wrapped by `_layout`
_layout/someDir/_someLayout.tsx
_layout/someDir/_someLayout/someOtherRoute.tsx - Only renders "someLayout" not the actual child route being visited.

[imSamiul]

@tannerlinsley

[schiller-manuel]

@imSamiul any concrete question from your side?

[imSamiul]

do the layout section should start with name layout? because I have a component folder which is auhtentication . In that folder i have two component login.tsx and signup.tsx. Now I have another component in outside named auhthentication.tsx (same name as folder). So this auntentication.tsx need to work as a layout component of both signup.tsx and login.tsx. but this is not working. whenever I rename the folder as _layout-authentication and component as _laout-authentication.tsx, then it is working fine. So, is it conventional rules in tanstack router to start the layout as _layout?

import { createFileRoute, Outlet } from "@tanstack/react-router";
import authenticationPageImage from "../assets/authentication-page-image.jpg";

export const Route = createFileRoute("/_layout-authentication")({
  component: AuthenticationLayout,
});

function AuthenticationLayout() {
  return (
    <div className="flex">
      <div className="flex-1 flex flex-col items-center justify-center">
        <Outlet />
      </div>
      <div className="flex-1 h-screen">
        <img
          src={authenticationPageImage}
          alt="authentication page image"
          className="h-full"
        />
      </div>
    </div>
  );
}

import { createFileRoute } from '@tanstack/react-router'

export const Route = createFileRoute('/_layout-authentication/signup')({
  component: () => <div>Hello /_layout-authentication/signup!</div>,
})

I do this because I want to render the login component as first when the _layout-authentcation.tsx run. So, do you have any better suggesntion on this?

[schiller-manuel]

no, those layout / pathless routes just have to start with an underscore.

[gex]

i also find the name pathless confusing becuase it's misleading. it is pathless only when there is a matching index so the url of the index route can overwrite the pathless route's url. in a case when there is no index route the pathless route is not pathless anymore.

example with pathless route

in this example i don't want to have an index route, so i create a pathless wrapper and two named routes only. it is true that i don't see the content of the wrapper component on the /sub/dir path, but it's not a not found error either.

problems:

• the error page is swallowed for the directory route and there is a blank page what i never created and i don't need
• the to prop of the Link component is not fully type safe anymore. it auto-completes and accepts the /sub/dir path and on that url there is a blank page.

generated src/routes/sub/dir/_wrapper.tsx

import { createFileRoute } from '@tanstack/react-router'

export const Route = createFileRoute('/sub/dir/_wrapper')({
  component: () => <div>Hello /sub/dir/_wrapper!</div>,
})

generated src/routes/sub/dir/_wrapper.a.tsx

import { createFileRoute } from '@tanstack/react-router'

export const Route = createFileRoute('/sub/dir/_wrapper/a')({
  component: () => <div>Hello /sub/dir/_wrapper/a!</div>,
})

generated src/routes/sub/dir/_wrapper.b.tsx

import { createFileRoute } from '@tanstack/react-router'

export const Route = createFileRoute('/sub/dir/_wrapper/b')({
  component: () => <div>Hello /sub/dir/_wrapper/b!</div>,
})

generated routeTree.gen.ts

import { Route as SubDirWrapperImport } from './routes/sub/dir/_wrapper'
import { Route as SubDirWrapperBImport } from './routes/sub/dir/_wrapper.b'
import { Route as SubDirWrapperAImport } from './routes/sub/dir/_wrapper.a'

const SubDirImport = createFileRoute('/sub/dir')()

const SubDirRoute = SubDirImport.update({
  path: '/sub/dir',
  getParentRoute: () => rootRoute,
} as any)

const SubDirWrapperBRoute = SubDirWrapperBImport.update({
  path: '/b',
  getParentRoute: () => SubDirWrapperRoute,
} as any)

const SubDirWrapperARoute = SubDirWrapperAImport.update({
  path: '/a',
  getParentRoute: () => SubDirWrapperRoute,
} as any)

declare module '@tanstack/react-router' {
  interface FileRoutesByPath {
    // ...
    '/sub/dir': {
      id: '/sub/dir'
      path: '/sub/dir'
      fullPath: '/sub/dir'
      preLoaderRoute: typeof SubDirImport
      parentRoute: typeof rootRoute
    }
    '/sub/dir/_wrapper': {
      id: '/sub/dir/_wrapper'
      path: '/sub/dir'
      fullPath: '/sub/dir'
      preLoaderRoute: typeof SubDirWrapperImport
      parentRoute: typeof SubDirRoute
    }
    '/sub/dir/_wrapper/a': {
      id: '/sub/dir/_wrapper/a'
      path: '/a'
      fullPath: '/sub/dir/a'
      preLoaderRoute: typeof SubDirWrapperAImport
      parentRoute: typeof SubDirWrapperImport
    }
    '/sub/dir/_wrapper/b': {
      id: '/sub/dir/_wrapper/b'
      path: '/b'
      fullPath: '/sub/dir/b'
      preLoaderRoute: typeof SubDirWrapperBImport
      parentRoute: typeof SubDirWrapperImport
    }
  }
}

when i create an index route the FileRoutesByPath interface will have two very similar entries so the empty page is still generated but the presence of the index route kinda swallows it as they have the same url at the end:

    '/sub/dir/_wrapper': {
      id: '/sub/dir/_wrapper'
      path: '/sub/dir'
      fullPath: '/sub/dir'
      preLoaderRoute: typeof SubDirWrapperImport
      parentRoute: typeof SubDirRoute
    },
    '/sub/dir/_wrapper/': {
      id: '/sub/dir/_wrapper/'
      path: '/'
      fullPath: '/sub/dir/'
      preLoaderRoute: typeof SubDirWrapperIndexImport
      parentRoute: typeof SubDirWrapperImport
    }

example without pathless route

just to show you what is that i'd expect from a pathless route is similar to this scenario: i create two named routes in a folder and i see the not found error page on the /sub/dir path.

generated src/routes/sub/dir/a.tsx

import { createFileRoute } from '@tanstack/react-router'

export const Route = createFileRoute('/sub/dir/a')({
  component: () => <div>Hello /sub/dir/a!</div>,
})

generated src/routes/sub/dir/b.tsx

import { createFileRoute } from '@tanstack/react-router'

export const Route = createFileRoute('/sub/dir/b')({
  component: () => <div>Hello /sub/dir/b!</div>,
})

generated routeTree.gen.ts

import { Route as SubDirBImport } from './routes/sub/dir/b'
import { Route as SubDirAImport } from './routes/sub/dir/a'

const SubDirBRoute = SubDirBImport.update({
  path: '/sub/dir/b',
  getParentRoute: () => rootRoute,
} as any)

const SubDirARoute = SubDirAImport.update({
  path: '/sub/dir/a',
  getParentRoute: () => rootRoute,
} as any)

declare module '@tanstack/react-router' {
  interface FileRoutesByPath {
    // ...
    '/sub/dir/a': {
      id: '/sub/dir/a'
      path: '/sub/dir/a'
      fullPath: '/sub/dir/a'
      preLoaderRoute: typeof SubDirAImport
      parentRoute: typeof rootRoute
    }
    '/sub/dir/b': {
      id: '/sub/dir/b'
      path: '/sub/dir/b'
      fullPath: '/sub/dir/b'
      preLoaderRoute: typeof SubDirBImport
      parentRoute: typeof rootRoute
    }
  }
}

i understand that this is a limitation but the name pathless is misleading because it's pathless in one very specific scenario only.

[schiller-manuel]

this might just be a bug in the router-generator., not a conceptual issue. please create a new github issue including a complete minimal example.

[imSamiul]

@gex why you neeed to create an index route component if you are already created a wrapper route compnent? you can do the same thing what you do in index component to the wrapper component.

[gex]

i don't need an index route component, it was for demonstrating purposes. what i actually need is a wrapper component for two subpaths without an index route component (what is not a not found component). and i think this is not possible with the current version.

[imSamiul]

it is possible. In my current project i am doing it.

here projectManager.tsx is the wrapper of all component that is inside projectManager folder. Here projectManager.tsx is working as wrapper component for addClient, addProject, managerOverview, overview.

[gex]

your projectManager.tsx is not a pathless route (no prefix), it's not the same setup so you obviously don't have the problem i described above.

[imSamiul]

it was pathless before. It was still working then. Dosen't matter.

[angelsvirkov]

@gex Here is how I solved the case for "pathless" wrapper component without using _ but using route.tsx. I am not 100% sure if your case is similar.

I didn't want to use _ prefixing with _pathless or _layout because then I need to specify for all of my sub-routers the pattern _layout.pageA, _layout.pageB and so on 30 times in my case. Therefore, I used the nested route but with the name of route.tsx so I can use the folder name example-wrapper with my children files /example-wrapper/pageA.tsx, /example-wrapper/pageB.tsx. Then I simulated a pathless index by matching the current url to the Route.id of the /example-wrapper index route. Now subs of example-wrapper have the layout, whereas if one goes directly to a url /example-wrapper it behaves as a not found route.

// routes/.../example-wrapper/route.tsx
export const Route = createFileRoute('/example-wrapper')({
  component: RouteComponent,
  // This is used for not found children of /example-wrapper -> e.g. /example-wrapper/unknown or /example-wrapper/sub/unknown
  notFoundComponent: NotFoundComponent,
})

function RouteComponent() {
  const location = useLocation()

  const isCurrentLocationExampleWrapper = location.pathname === Route.id

  if(isCurrentLocationExampleWrapper) {
    // this is used for exact `.../example-wrapper` match
    return <NotFoundComponent />
  } else {
    return (
      <>
        <nav>Nav</nav>
        <Outlet />
      </>
    )
  }
}