Tanstack: Add `@storybook/tanstack-react` package by huang-julien · Pull Request #34403 · storybookjs/storybook

huang-julien · 2026-03-30T16:08:53Z

What I did

This PR introduces first-class support for TanStack apps in Storybook via a new @storybook/tanstack-react framework integration, including router-aware story rendering, TanStack start and router compatible mocks.

Build

Tanstack start plugins removal in the preset file

Tanstack start mostly provide server features and SSR capabilities to tanstack router. Since storybook is client-only, we strip out any tanstack start plugins

Server code elimination

Added server-side code elimination/plugin behavior to prevent server-only modules from breaking browser Storybook runtime.

It is similar to https://github.com/TanStack/router/blob/main/packages/start-plugin-core/src/start-compiler/compiler.ts#L965 but without needing a server environement.

Runtime

createFileRoute

Most tanstack router users uses createFileRoute to create a file based tanstack route.
However, the path is ignored when calling createFileRoute(route)(options), the implementation will provide it's own createFileRoute to force the path being set in the returned route object.

Page extraction from route

The implementation provides loader and decorator to extract a page component from a route if the user did not provide a component through the meta or story object.
In most cases, tanstack router page files doesn't export the page component. Only the route itself.
This is a DX improvement and to avoid storybook impacting users project.

Server functions

All server functions are mocked by default, the build-time storybook server code elimination plugins strips out any server code dependency/imports

Types

The framework ships a typed parameter layer that threads route inference through stories end-to-end:

parameters.tanstack.router can be passed to Meta<> to propagate route typing across a story file without repeating the route generic.
This means incorrect route params, unknown override paths, or wrong search shapes are caught at compile time rather than at runtime in the browser.

Checklist for Contributors

Testing

test the tanstack integration with a transtack react router project
test with tanstack start
verify things are not breaking in a monorepo
test on windows

The changes in this PR are covered in the following automated tests:

stories
unit tests
integration tests
end-to-end tests

Manual testing

react router + start

npx @tanstack/cli create --router-only
npm create storybook@10.4.0-alpha.17
verify stories works
- Without a router (empty storybook)
- With a route createFileRoute to parameters.tanstack.router.route
- With the whole app tree routeTree to parameters.tanstack.router.route
  - Verify type constraints works on
    - routeOverrides
    - path
    - params

start additionnal tests

verify stories works
- Add some server handlers in the project with server only code (test server code elimination)
  - Without a router (empty storybook)
  - With a route createFileRoute to parameters.tanstack.router.route
  - With the whole app tree routeTree to parameters.tanstack.router.route
    - Verify type constraints works on
      - routeOverrides
      - path
      - params

Caution

This section is mandatory for all contributions. If you believe no manual test is necessary, please state so explicitly. Thanks!

Run a sandbox for template, e.g. yarn task --task sandbox --start-from auto --template tanstack-react/default-ts
Open Storybook in your browser
Access and view all sotries

Documentation

Add or update documentation reflecting your changes
If you are deprecating/removing a feature, make sure to update
MIGRATION.MD

Checklist for Maintainers

When this PR is ready for testing, make sure to add ci:normal, ci:merged or ci:daily GH label to it to run a specific set of sandboxes. The particular set of sandboxes can be found in code/lib/cli-storybook/src/sandbox-templates.ts
Make sure this PR contains one of the labels below:
Available labels
- bug: Internal changes that fixes incorrect behavior.
- maintenance: User-facing maintenance tasks.
- dependencies: Upgrading (sometimes downgrading) dependencies.
- build: Internal-facing build tooling & test updates. Will not show up in release changelog.
- cleanup: Minor cleanup style change. Will not show up in release changelog.
- documentation: Documentation only changes. Will not show up in release changelog.
- feature request: Introducing a new feature.
- BREAKING CHANGE: Changes that break compatibility in some way with current major version.
- other: Changes that don't fit in the above categories.

🦋 Canary release

This pull request has been released as version 0.0.0-pr-34403-sha-14169208. Try it out in a new sandbox by running npx storybook@0.0.0-pr-34403-sha-14169208 sandbox or in an existing project with npx storybook@0.0.0-pr-34403-sha-14169208 upgrade.

More information


Published version	`0.0.0-pr-34403-sha-14169208`
Triggered by	@huang-julien
Repository	storybookjs/storybook
Branch	`julien/tanstack`
Commit	`14169208`
Datetime	Mon May 4 09:03:09 UTC 2026 (`1777885389`)
Workflow run	25310407446

To request a new release of this pull request, mention the @storybookjs/core team.

core team members can create a new canary release here or locally with gh workflow run --repo storybookjs/storybook publish.yml --field pr=34403

Summary by CodeRabbit

New Features
- First-class TanStack React integration: router + query support, typed Storybook APIs, Vite-based preset, preview decorators/loaders, runtime mocks for Start/Router, and CLI generator + project templates.
Documentation
- Added framework README and example templates demonstrating TanStack React + Storybook usage.

…t compatibility in preset configuration

…amework with support for story, routeTree, and instance modes. Introduce helper functions for creating memory routers and update documentation with routing examples.

…y removing unnecessary server type definition and enhancing context and createRouter types for better type safety.

…streamline the Vite setup for the TanStack React framework.

- Added `createServerFnStub` and `resetAllServerFnStubs` for mocking server functions. - Introduced integration tests for server function stubs demonstrating various scenarios. - Updated `preset.ts` to include a Vite plugin for handling server function stubs. - Enhanced `preview.tsx` to reset server function stubs between stories. - Created new story examples showcasing loaders and pathless layouts with mocked data. - Removed outdated router example stories and components.

JReinhold

Awesome job 🎉 Only very small comments, the most important ones being about the Babel dependency.

Co-authored-by: Copilot <copilot@github.com>

…tion.ts Co-authored-by: Jeppe Reinhold <jeppe@chromatic.com>

Co-authored-by: Jeppe Reinhold <jeppe@reinhold.is>

Co-authored-by: Copilot <copilot@github.com>

JReinhold

LGTM™

JReinhold · 2026-05-05T08:21:20Z

+  const isTanStackStartPlugin = (p: unknown): boolean => {
+    if (Array.isArray(p)) {
+      return p.some(isTanStackStartPlugin);
+    }
+    const pluginRecord = p as Record<string, unknown>;
+    return (
+      typeof p === 'object' &&
+      p !== null &&
+      'name' in pluginRecord &&
+      typeof pluginRecord.name === 'string' &&
+      (pluginRecord.name.startsWith('tanstack-start') || pluginRecord.name.includes('rsc:'))
+    );
+  };


SGTM. I'm sure the utility function can be modified to support startsWith/includes

valentinpalkovic and others added 30 commits February 3, 2026 09:38

Feature: Add @storybook/tanstack-react framework

054c0cc

Enhancement: Implement custom Vite plugin filtering for TanStack Star…

433af94

…t compatibility in preset configuration

Enhancement: Add routing capabilities to @storybook/tanstack-react fr…

a920a3c

…amework with support for story, routeTree, and instance modes. Introduce helper functions for creating memory routers and update documentation with routing examples.

Refactor: Simplify FrameworkOptions and TanStackRouterOptions types b…

c7c5e37

…y removing unnecessary server type definition and enhancing context and createRouter types for better type safety.

Fix types

1e1b71a

Refactor: Remove server configuration from viteFinal in preset.ts to …

13bbb6d

…streamline the Vite setup for the TanStack React framework.

Fix types

096b0db

T1: Framework Core (preview.tsx, types.ts)

4945a18

T2: Helpers & Exports (4 files)

48c7203

T3: Template Stories (6 files)

91f1243

Linting

4ea368e

Fix TypeScript formatter to use ESLint instead of Prettier

b33f415

Add basic stories

24f5a02

Remove router experiments

faf8abb

Remove tanstack template stories

640d43f

Cleanup Readme

f7a79aa

Merge remote-tracking branch 'origin/next' into julien/tanstack

2f4955f

Merge branch 'next' into julien/tanstack

0570f3e

Merge branch 'next' into julien/tanstack

0f9d59a

Merge branch 'next' into julien/tanstack

4bc05e8

feat: initial tanstack router mock

57c6c53

fix: block navigation in memoryHistory

4f31ee9

feat: expose router via decorator file

b8b9b69

build: export getRouter from index and add missing decorator

a70afac

feat: mock tanstack query

cdd0672

refactor: partial router cleanup

0d58ae8

feat: add additionnal mocks and fix router implementation

8fdc056

Build: update build config

6eb8692

fix: types

c491732

huang-julien added 6 commits April 30, 2026 18:41

Merge remote-tracking branch 'origin/next' into julien/tanstack

1416920

chore: code cleaning and add comments

b3023c4

fix: add devtools deps to optimize deps

c381a10

chore: clean types

caf2e9d

Merge remote-tracking branch 'origin/next' into julien/tanstack

03a176c

chore: rename plugin

d268a96

JReinhold requested changes May 4, 2026

View reviewed changes

huang-julien and others added 11 commits May 4, 2026 15:54

refactor: simplify mocks

8c9eb9f

Co-authored-by: Copilot <copilot@github.com>

chore: move stub plugin into dedicated file

5cbc922

Co-authored-by: Copilot <copilot@github.com>

Update code/frameworks/tanstack-react/src/plugins/server-code-elimina…

8b7c863

…tion.ts Co-authored-by: Jeppe Reinhold <jeppe@chromatic.com>

Apply suggestions from code review

2d58254

Co-authored-by: Jeppe Reinhold <jeppe@reinhold.is>

fix: babel changes

40f8bbd

fix: type

b0b5af5

chore: cleanup package.json

fa6e73f

chore: use type augmentation

5b44054

fix: coderabbitai fedddback

989a95f

Co-authored-by: Copilot <copilot@github.com>

refactor: use template string

c92bd95

Co-authored-by: Copilot <copilot@github.com>

chore: regen lockfile

ec79572

kylegach reviewed May 4, 2026

View reviewed changes

Comment thread code/frameworks/tanstack-react/template/cli/ts/Page.stories.ts Outdated

huang-julien and others added 5 commits May 4, 2026 17:27

docs: update comment to guide users on documentation

8edbea5

fix: make tanstack template similar to nextjs ones

ed7615b

Co-authored-by: Copilot <copilot@github.com>

Merge branch 'next' into julien/tanstack

cea37cc

refactor: remove start-server mock

976b1a7

Co-authored-by: Copilot <copilot@github.com>

Merge remote-tracking branch 'origin/next' into julien/tanstack

5909e3e

JReinhold approved these changes May 5, 2026

View reviewed changes

huang-julien merged commit 53e094a into next May 5, 2026
138 of 140 checks passed

huang-julien deleted the julien/tanstack branch May 5, 2026 08:53

github-actions Bot mentioned this pull request May 5, 2026

Release: Prerelease 10.4.0-alpha.17 #34713

Merged

10 tasks

JReinhold changed the title ~~Feat: Storybook/tanstack-react~~ Tanstack: Add @storybook/tanstack-react package May 5, 2026

github-actions Bot mentioned this pull request May 5, 2026

Release: Prerelease 10.4.0-alpha.17 #34716

Closed

14 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Tanstack: Add `@storybook/tanstack-react` package#34403

Tanstack: Add `@storybook/tanstack-react` package#34403
huang-julien merged 154 commits into
nextfrom
julien/tanstack

huang-julien commented Mar 30, 2026 •

edited

Loading

Uh oh!

JReinhold left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

JReinhold left a comment

Uh oh!

Uh oh!

JReinhold May 5, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

Uh oh!

Conversation

huang-julien commented Mar 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What I did

Build

Tanstack start plugins removal in the preset file

Server code elimination

Runtime

createFileRoute

Page extraction from route

Server functions

Types

Checklist for Contributors

Testing

The changes in this PR are covered in the following automated tests:

Manual testing

Documentation

Checklist for Maintainers

🦋 Canary release

Summary by CodeRabbit

Uh oh!

JReinhold left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

JReinhold left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

JReinhold May 5, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

huang-julien commented Mar 30, 2026 •

edited

Loading