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.

[schiller-manuel]

@tomredman what exactly should work out of the box? sorry I lost track here

[tomredman]

Sorry @schiller-manuel - I could have been more helpful. It was a little frustrating to navigate this issue, as this and some other tickets signal.

However, I believe this is just a documentation issue more than anything else. Once I got the above working, I'm quite happy with it.

I will submit a PR with some updates to the docs that will hopefully clarify most confusion about pathless paths and using routes.tsx (which isn't documented at all AFAICT).

[tomredman]

There are a few naming convention changes that could help as well, but I haven't fully thought through them nor do I have all the context on the current naming conventions:

• route.tsx could be named layout.tsx or even root.tsx
  • However, these are still "hittable pages" as route.tsx acts like a index.tsx file
• I'm aiming to setup my routes like this:
  • campaigns/layout.tsx (this is truly pathless and cannot be served by itself)
  • campaigns/index.tsx (optional, whatever I want, wrapped in layout.tsx)
  • campaigns/create.tsx (...whatever I want, wrapped in layout.tsx)

[schiller-manuel]

@tomredman contributions to the docs are always welcome, so please help us out to clear things up

[SoloReverse]

TIL that route.tsx can wrap the directory, thank you @angelsvirkov. I like the implementation. The fine grained opt-in ability to utilize either the route.tsx which has the ability to take over every subdirectory/subroute or _pathless.tsx which can wrap a couple of pages within. Honestly the multiple ways to do one things is a sights for sore eyes.

@tomredman I disagree on route.tsx being called layout, but I do see it as root. Route is every file I create, thus the name loses its definition when given to file, and Layout feels restricted to UI. When I first starting using the router I kept searching on how to create multiple roots, if that ability existed. Root feels more natural to encompass the functionality / scope of everything in the directory.

Also just moved from Next.js and I am loving this router.