Usage with Storybook?

[MerlinMason]

Hi there,

We're currently using React-Router and considering migrating to Tanstack Router...

We use Storybook a lot and we needed to use an add-on to enable React Router to work with Storybook.

Is this also the case with Tanstack Router? and if so does such an add-on exist yet?

Thanks!

[erickarnis-tb]

Currently with Storybook I get this error on most stories: ReferenceError: Cannot access 'Root' before initialization
I'm on @tanstack/react-router: "1.4.6",
Haven't been able to figure it out

[erickarnis-tb]

I figured it out. Importing anything from a router file leads to the execution of the router file which can lead to errors even in unrelated stories.

[dohomi]

I would like to know how to use Storybook as well. I think a plugin would be great, or simply a working solution how to create the router context for stories that you can display components which includes any API of the router

[Dixtir]

@dohomi have you found a solution for this?

[dohomi]

I use this:

const rootRoute = new RootRoute()
const indexRoute = new Route({ getParentRoute: () => rootRoute, path: "/" })
const memoryHistory = createMemoryHistory({ initialEntries: ["/"] })
const routeTree = rootRoute.addChildren([indexRoute])
const router = new Router({ routeTree, history: memoryHistory })

// @ts-ignore todo maybe soon a better solution for this?
export const withSbTanstackRouter: Preview["decorators"][0] = (Story, context) => {
  return <RouterProvider router={router} defaultComponent={() => <Story {...context} />} />
}

then wrap your most outer global decorator story like this:

export const SbDecorator: Decorator = (Story,args) => (
  <>{withSbTanstackRouter(Story,args))}</>
)

[Dixtir]

@dohomi thanks, much appreciated!

[alireza-mh]

I'm interested to know if there are any workaround/solutions to render the Link component inside a story. Some components might want to use router hooks even.

[Dixtir]

@alireza-mh have you found a solution for this?

[jaens]

Here's what I created: Storybook fake Tanstack router - Gist

[boonya]

Here is what I've done

import type {PartialStoryFn, StoryContext} from '@storybook/types';
import {createMemoryHistory, createRootRoute, createRoute, createRouter, RouterProvider} from '@tanstack/react-router';

export default function withRouter(Story: PartialStoryFn, {parameters}: StoryContext) {
	const {initialEntries = ['/'], initialIndex, routes = ['/']} = parameters?.router || {};

	const rootRoute = createRootRoute();

	const children = routes.map((path) =>
		createRoute({
			path,
			getParentRoute: () => rootRoute,
			component: Story,
		}),
	);

	rootRoute.addChildren(children);

	const router = createRouter({
		history: createMemoryHistory({initialEntries, initialIndex}),
		routeTree: rootRoute,
	});

	return <RouterProvider router={router} />;
}

declare module '@storybook/types' {
	interface Parameters {
		router?: {
			initialEntries?: string[];
			initialIndex?: number;
			routes?: string[];
		};
	}
}

You can add it as global decorator in preview.tsx file.

[boonya]

@wurmr , I have 1.32.3 and it still works fine

[d4vidsha]

@boonya Can you explain further how to achieve this for newbies? I am one of them.

[boonya]

@d4vidsha what do you mean by "achieve this"? I have it working if it doesn't? I don't know. It depends on many factors - set of dependencies, storybook setup, browser and many others.

[d4vidsha]

@boonya Ah I was just wondering where the above code snippet should be placed more generally, as I'm a little lost even after reading up on the docs for Storybook decorators. Just trying to link your comment and those docs together in my head to create a minimum reproducible example.

[boonya]

I would recommend you remove as many as you can and leave the only code related to router. Then check how it work. If does, add other feature one by one to catch the guilty one.

[bhaugeea]

Here's something simple that's been working fine with router v1.4 and storybook v7.6. You can see it has no business logic at all, but it's enough to provide the router context so things don't break.

// preview.tsx

import type { Preview } from '@storybook/react';
import { RouterProvider, createMemoryHistory, createRootRoute, createRouter } from '@tanstack/react-router';

const preview: Preview = {
  decorators: [
    (Story) => {
      return <RouterProvider router={createRouter({
        history: createMemoryHistory(),
        routeTree: createRootRoute({
          component: Story
        })
      })} />
    }
  ]
};

export default preview

[boonya]

Okay I see, but how about the situation you need to render your component by the specific route? How can I do that?

[bhaugeea]

Not sure, but in my opinion a component like that doesn't belong in storybook. I use storybook for things that are supposed to be generically composable. Buttons, modals, dropdowns, cards, etc. The only story I currently have that relies on router is a reusable implementation of tanstack table that puts its pagination, sorting, and filtering state in the URL. Doesn't care what route it's on, it just adds its own state.

If you need to recreate some non-trivial route tree, data fetching, and other stuff to make your stories work, then either: (a) you're trying to take storybook too far or (b) your components manage state badly and need to be written cleaner to be truly reusable.

[boonya]

"Too far" is too abstract statemnt. If you work with components library, you are correct. But what if you want to implement some component of real application which is dependent on router context as well as some data API. Does that mean I should not do so? But why? Storybook is amazing tool which gives me such ability throught it's decorators API and parameters.
So, what is "too far" to you may be "not enough" to someone other.
With that toolset storybook helps me implement frontend far ahead of backend in my projects. It save us a tone of time and make my team free of redundant headache.

[jaens]

Just FYI, there's quite a bit of subtlety involved with the Storybook (8) integration, the simple solution I and others have pasted above does not always work properly when switching between stories:

• it will keep a stale component (not re-rendered)
• once you navigate away from the default route, it will not navigate back

[levidrain]

I bypassed the RouterProvider and used the RouterContextProvider and so far it works well. Can't promise it wouldn't break in a future version or that it works in all cases.
In the preview.ts file add a decorator, like:

  const router = createRouter({ routeTree });
  ...
  decorators: [story => <RouterContextProvider router={router}>{story()}</RouterContextProvider>]

[jaens]

This will not work when the story actually navigates anywhere (eg. in more "system-level" stories / form submits).

(note that changing eg. hash parameters due to eg. radio group selection is also considered a navigation, but depending on the exact state management setup it might still work)

[dohomi]

I tried all the above ways but it all looses either strong typings on useSearch or useParams and the user is forced to relax the typings with strict: false which is not really ideal. I would like to display landing pages of tanstack router pages and if there is any business logic involved which is strongly typed I receive error messages.

Invariant failed: Could not find a nearest match!
Invariant failed: Could not find an active match from "/_dashboard/team/$teamId/players"

I start to provide my own useSearch which basically keeps the same typings but replaces the options with {strict:false}

import {
  type AnyRoute,
  type FullSearchSchema,
  type RegisteredRouter,
  type RouteById,
  type RouteIds,
  useSearch
} from "@tanstack/react-router"
import { isStorybook } from "../lib/generalConfig"

type StringLiteral<T> = T extends string ? (string extends T ? string : T) : never

type StrictOrFrom<TFrom, TStrict extends boolean = true> = TStrict extends false
  ? {
      from?: never
      strict: TStrict
    }
  : {
      from: StringLiteral<TFrom> | TFrom
      strict?: TStrict
    }

type UseSearchOptions<TFrom, TStrict extends boolean, TSearch, TSelected> = StrictOrFrom<
  TFrom,
  TStrict
> & {
  select?: (search: TSearch) => TSelected
}
type Expand<T> = T extends object
  ? T extends infer O
    ? O extends Function
      ? O
      : { [K in keyof O]: O[K] }
    : never
  : T

/**
 * Enhanced useSearch hook that optionally disables strict mode if running in Storybook.
 */
export function usePtSearch<
  TRouteTree extends AnyRoute = RegisteredRouter["routeTree"],
  TFrom extends RouteIds<TRouteTree> = RouteIds<TRouteTree>,
  TStrict extends boolean = true,
  TSearch = TStrict extends false
    ? FullSearchSchema<TRouteTree>
    : Expand<RouteById<TRouteTree, TFrom>["types"]["fullSearchSchema"]>,
  TSelected = TSearch
>(opts: UseSearchOptions<TFrom, TStrict, TSearch, TSelected>): TSelected {
  // Create a modified options object if in Storybook mode

  // Call the useSearch hook with the appropriate options
  return useSearch(isStorybook ? { strict: false } : opts)
}

[hiima]

@dohomi
How is ../lib/generalConfig implemented? I couldn't figure out how to detect if Storybook is running.

[dohomi]

its simply a process.env.STORYBOOK lookup. I set this to truthy

[hiima]

Got it, thanks!