Storybook TanStack Router integration: Nested file routes throw Duplicate routes found with id: __root__ unless routeTree.gen is imported via side-effect

[timofei-iatsenko]

Summary

Hello! I'm running into an issue using the official Storybook TanStack Router integration in a pure client-side SPA setup with file-based routing.

I want to verify whether I am misinterpreting the recommended usage pattern for nested routes or if we have hit a bug/edge case in the addon's tree resolution logic. Given that our setup is a standard TanStack Router SPA using file-based routes (with an autogenerated routeTree.gen.ts), this feels like a primary use case that should work cleanly out of the box.

According to the Storybook documentation for rendering nested file routes:

"When route is a file route connected to your app's route tree, Storybook automatically includes parent layout routes so the story renders inside the same nested hierarchy as the real app."

We attempted to import our nested page route directly into the story:

import { Route } from './route'

const meta = preview.meta({
  title: 'Pages/Access Controls/Take a Break Confirmation',
  parameters: {
    tanstack: {
      router: {
        route: Route,
      },
    },
  },
})

Where Route is a simple TanStack route definition:

export const Route = createFileRoute('/take-a-break-confirmation')({
  component: RouteComponent,
  validateSearch: zodValidator(searchSchema),
})

With this setup, the story fails at runtime with:

Invariant failed: Duplicate routes found with id: __root__

I investigated what's going on under the hood and didn't find any code that attempts to load ancestors for the passed route.

The issue seems to happen because Storybook creates a synthetic root and then attaches the passed route to it. The passed route doesn't have an id yet (because it is assigned as a side effect inside routeTree.gen.ts, which isn't imported in this story). As a result, two routes without an id are treated as duplicate __root__ routes.

The docs mention as an alternative:

You can also pass the routeTree export from routeTree.gen.ts directly.

However, while the docs mention this, they don't provide an example showing how to pass routeTree properly. I attempted the following:

import { routeTree } from '@/routeTree.gen'

const meta = preview.meta({
  title: 'Pages/Access Controls/Take a Break Confirmation',
  parameters: {
    tanstack: {
      router: {
        route: routeTree, // <-- pass the entire tree
        path: '/take-a-break-confirmation', // <-- render this path
      },
    },
  },
})

The invariant error disappears, but the story still fails to render the target path correctly. Instead of rendering the route associated with the /take-a-break-confirmation path within the tree, the addon injects the story component at the resolved leaf route, resulting in the root route rendering twice.

The only working approach I have found is forcing a side-effectful import of routeTree.gen.ts to assemble the route tree first:

import '@/routeTree.gen' // <-- side-effectful import to inject parent pointers into the route definition
import { Route } from './route' // <-- import the actual route

const meta = preview.meta({
  parameters: {
    tanstack: {
      router: {
        route: Route,
      },
    },
  },
})

This works because in TanStack Router's file-based approach, route definitions don't contain links to parents or children until routeTree.gen.ts is loaded.

The typical content of routeTree.gen.ts looks like this:

import { Route as Level1Level2Level3RouteImport } from './level-3'
import { Route as Level1Level2RouteRouteImport } from './route'
import { Route as Level1RouteRouteImport } from '../route'
import { Route as rootRouteBlaBla } from '../../__root'

const Level1Level2Level3Route = Level1Level2Level3RouteImport.update({
  id: '/level-3',
  path: '/level-3',
  getParentRoute: () => Level1Level2RouteRoute,
})

const Level1Level2RouteRoute = Level1Level2RouteRouteImport.update({
  id: '/level-2',
  path: '/level-2',
  getParentRoute: () => Level1RouteRoute,
})

const Level1RouteRoute = Level1RouteRouteImport.update({
  id: '/level-1',
  path: '/level-1',
  getParentRoute: () => rootRouteBlaBla,
})

const Level1Level2RouteRouteWithChildren = Level1Level2RouteRoute._addFileChildren({
  Level1Level2Level3Route,
})

const Level1RouteRouteWithChildren = Level1RouteRoute._addFileChildren({
  Level1Level2RouteRouteWithChildren,
})

const rootRouteBlaBlaWithChildren = rootRouteBlaBla._addFileChildren({
  Level1RouteRouteWithChildren,
})

export const routeTree = rootRouteBlaBlaWithChildren

This file mutates the route definitions and assembles the tree. Once loaded, the Storybook integration can traverse ancestors starting from the passed leaf route and locate the root route correctly.

Questions / Feedback:

1. Is forcing routeTree.gen.ts to load intended to be the standard usage pattern? If so, could this be explicitly stated in the documentation? If not, what is the intended way to render a route alongside all its ancestors in Storybook?
2. How should routeTree be passed alongside a specific Route? The routeTree exported from routeTree.gen.ts is essentially the root route, so passing it into parameters.tanstack.router.route causes the story to render the root route instead of the target page route.

Thanks for the clarification and for your great work on Storybook!

Additional information

No response

Create a reproduction

No response

[ghengeveld]

What Storybook framework is configured in .storybook/main.ts, and which Storybook version are you on? The specific error you're seeing (Duplicate routes found with id: __root__) suggests you may be on @storybook/react-vite rather than @storybook/tanstack-react.

The reason that matters: @storybook/tanstack-react intercepts @tanstack/react-router and replaces createFileRoute with a version that stamps an id and path onto the route at definition time so that a route file imported on its own still carries its identity. With that in place, a route imported without routeTree.gen.ts mounts standalone (without its parent layouts, which still require the generated tree) instead of colliding with the synthetic root. If you're on plain @storybook/react-vite, you get TanStack's real createFileRoute, the route has no id until the generated tree assigns one, and you end up with the collision you described. If that's the case, use npx storybook automigrate to migrate to the Storybook TanStack framework.

Now to answer the above questions (assuming @storybook/tanstack-react):

1. Is importing routeTree.gen.ts the intended pattern?

For rendering a route inside its parent layouts, yes, and you're right that we don't say so. A file route holds no reference to its parent until routeTree.gen.ts has been evaluated, so there is nothing for us to walk up. Your workaround is the correct approach, but it doesn't need to be per story. A single side-effect import in your preview file covers every story:

// .storybook/preview.ts
import '@/routeTree.gen';

After that, route: Route on an individual story works as documented, and parent layouts render.

2. How do you pass routeTree alongside a specific route?

The shape in the reply above isn't right: there is no routeTree parameter and no initialEntries parameter. The supported keys under parameters.tanstack.router are route, path, params, query, routeOverrides, context, and useRouterContext.

The full-tree form is to pass the tree as route and the target URL as path:

import { routeTree } from '@/routeTree.gen';

const meta = preview.meta({
  parameters: {
    tanstack: {
      router: {
        route: routeTree,
        path: '/take-a-break-confirmation',
      },
    },
  },
});

That said, if you're on 10.5.x this will misbehave exactly as you observed. Leaf selection compared fullPath before the cloned routes were initialized, so path was effectively ignored and the story got injected on the wrong route. That's fixed in #35498, released in 10.6.0. On 10.6 or later the route + path combination selects the route you asked for.

Since your route uses validateSearch, you'll likely also want query to supply search params that satisfy the schema, and routeOverrides to stub any beforeLoad guards on ancestor routes so the story renders standalone.

If you can share your Storybook version and framework, I'm happy to confirm which of the above applies to your setup.

[ghengeveld]

So the real solution for TurboSnap to keep working, though awkward, is to import routeTree.gen.ts from the story files that need it rather than from .storybook/preview.ts. Those stories then recapture whenever anything in the route tree changes, but the rest of the suite does not. This is also what somuai was hinting at in their 1st option (though it was otherwise wrong).

Using untraced on routeTree.gen.ts does sort-of fix TurboSnap. A page story that imports its own route still recaptures when that page changes. Changes to parent layouts do not, because only the generated file imports them, and TurboSnap will not warn you. That is acceptable when those layouts have their own stories and a full build on main is the backstop. It does not help hot reload, since preview.ts still imports the whole tree.

This is not the right place to be discussing TurboSnap specifics though. I suggest you get back in touch with our support team for a tailored solution. Happy to assist there!

[ghengeveld]

By the way, we have been working on an update to TurboSnap. It likely won't fix this particular issue, but we may have appetite to improve this sort of situation. It's related to barrel file handling, which Storybook does but TurboSnap doesn't yet.

[timofei-iatsenko]

Actually, we have a solution on our side for this, and i wanted to propose this solution for the storybook integration.

We implemented a Vite plugin which is "treeshaking" a routeTree.gen.ts leaving only the requested route and it's ancestors. This way each story depends exactly on the components/routes it used, no less no more.

I believe the Storybook itself could benefit from this solution even outside of the context of a turbosnap. Adding routeTree.gen.ts to preview.ts would force every story loading the entire codebase making Storybook development sluggish.

Here the snippet how our tanstack router integration looks like now:

import preview from '#.storybook/preview'
import { WithProviders } from '@/test/storybook-setup'
import { RouterProvider } from '@tanstack/react-router'
import { Route } from './take-a-break'
import { routeTree } from './take-a-break?tree' // <-- this is a virtual module, when requested Vite plugin resolve ancestors and build route tree for the `./take-a-break` route only. 
import { createRouterForSb } from '@/storybook/router/render-route'

const router = createRouterForSb(routeTree) // render all ancestor routes of Take A Break route

const meta = preview.meta({
  title: 'Pages/Account Locked/Take A Break',
  beforeEach: () => {
    router.navigate({ to: Route.fullPath })
  },
  decorators: [
    () => {
      return (
        <WithProviders>
          <RouterProvider router={router} />
        </WithProviders>
      )
    },
  ],
})

export const Default = meta.story()

The smart thing here, is the fact that this plugin is not trying to re-create Tanstack Router routeTree.gen.ts generator behavior. Instead it just take existing routeTree.gen.ts and trace current route up to the root dropping the rest.

I think for the Storybook official integration this plugin could be a slightly modified. Instead of relying on ?tree suffix, plugin could hijack imports to routes if they are issued from the story file and return route already enhanced by it's ancestors:

import preview from '#.storybook/preview'
import { WithProviders } from '@/test/storybook-setup'
import { RouterProvider } from '@tanstack/react-router'
import { Route } from './take-a-break' // <-- resolved by a plugin and redirects to a virtual module which will build an ancestor tree and return a Route
import { createRouterForSb } from '@/storybook/router/render-route'


const meta = preview.meta({
  title: 'Pages/Account Locked/Take A Break',
  parameters: {
    tanstack: {
      router: {
         // magically renders route and it's ancestors
        route: Route, 
      },
    },
  },
})

export const Default = meta.story()

Though could be a bit too much of magic and more explicit api might be more appreciated.

Let me know what you think about this approach?

[timofei-iatsenko]

Things to consider with plugin DX, query params added to the import ditch all typescript typings from that import, so you need to provide an ambient type declarations for this type import:

declare module "*?tree" {
  import { Route } from "@tanstack/react-router";
  export const routeTree: Route;
}

And, unfortunately there is no way to infer original type of the import if it augmented with query params:

import { Route } from './take-a-break?tree'  // <-- no way to infer a real type of a `take-a-break` route. So further Router type safety is compromised.

The optimal solution, could be an import attributes:

import { Route } from './take-a-break'  with { ancestors: 'full' } // if user wants to render a full ancestors tree
import { Route } from './take-a-break'  // if user wants to render a leaf only

This way typescript will get proper type and it gives a proper DX and flexibility for a user without implicit magic. However "import attributes" feature is not yet supported in the Rolldown/Vite (although it supported in Rollup) vitejs/vite#18534

[huang-julien]

That's pretty neat, I'll try it out but I love this approach. Although i'm not sure about the import attribute as a solution.