Skip to content
Source
Sign inSign up
TanStack/router

Start: user router.plugins never reach the route generator (start-plugin-core overwrites them) #7768

Send to my agent
Closedaryasaatvik(GitHub profile, opens in a new tab) opened this issue 2 comments

Which project does this relate to?

Start

Describe the bug

Generator plugins passed as tanstackStart({ router: { plugins: [...] } }) never reach the route generator — no hook (init, onRouteTreeChanged, afterTransform) is ever invoked, in dev or build, with no error or warning.

Cause: tanStackStartRouter builds its internal generator-plugin list and places it after ...routerConfig in the config it hands to tanstackRouterGenerator, so the user's plugins key is overwritten:

https://github.com/TanStack/router/blob/4eed408f12e0dee55708b1e2b53fefb3441c414d/packages/start-plugin-core/src/vite/start-router-plugin/plugin.ts#L147-L159

tanstackRouterGenerator(() => {
  const routerConfig = getConfig().startConfig.router
  const plugins = [clientTreeGeneratorPlugin, routesManifestPlugin()]
  if (startPluginOpts.prerender?.enabled === true) {
    plugins.push(prerenderRoutesPlugin())
  }
  return {
    ...routerConfig,          // includes the user's routerConfig.plugins…
    target: corePluginOpts.framework,
    routeTreeFileFooter: getRouteTreeFileFooter,
    plugins,                  // …which is clobbered here
  }
}, routerPluginContext)

The same options work correctly with the plain tanstackRouter Vite plugin (no Start), where user config flows through getConfig untouched — so this is Start-specific.

Suggested fix (verified locally via a patched package):

if (routerConfig.plugins) plugins.push(...routerConfig.plugins)

Your Example Website or App

// vite.config.ts — minimal repro
import { defineConfig } from 'vite'
import { tanstackStart } from '@tanstack/react-start/plugin/vite'

export default defineConfig({
  plugins: [
    tanstackStart({
      router: {
        plugins: [
          {
            name: 'probe',
            init: () => console.error('[probe] init'),
            onRouteTreeChanged: () => console.error('[probe] onRouteTreeChanged'),
          },
        ],
      },
    }),
  ],
})

Steps to Reproduce the Bug or Issue

  1. Add the probe generator plugin above to any TanStack Start app's vite.config.ts
  2. Run vite dev or vite build
  3. Neither [probe] line is printed; with the plain tanstackRouter() plugin (non-Start), both print

Expected behavior

User-supplied router.plugins are merged with Start's internal generator plugins and their hooks fire on generator runs — or, if generator plugins are intentionally unsupported under Start, a loud error instead of silent acceptance.

Platform

  • @tanstack/react-start: 1.168.27 (start-plugin-core 1.171.19; bug still present on main)
  • OS: macOS

Additional context

Footnote once plugins do run: createRouterGeneratorPlugin wraps generator.run() in catch (e) { console.error(e) }, so a generator plugin that throws (e.g. to enforce a project invariant) can log but never fail the build. May be intentional, but it compounds the silence here.

  1. plugins are not a public API. what would you need this for?

  2. schiller-manuel(GitHub profile, opens in a new tab) added labelsinformation needed

  3. Fair enough — happy to live with it not being public. Here's what I'm using it for, in case the use case is interesting.

    Problem. SEO metadata was scattered: each page hand-wrote its own head tags, JSON-LD and breadcrumb trail, while a separate fs scanner re-derived the route list for sitemap/robots/config — and drifted from the router's own route-group/param/layout conventions. Worst part: a page could ship with no metadata at all and I wouldn't notice until it was already indexed.

    Solution. One declaration per route; everything else is a projection of the route tree. Head tags, JSON-LD, breadcrumbs, sitemap, robots, and internal cross-links all derive from it. And a page that declares nothing fails the build.

    Shape. staticData.seo carries the route's policy (module-augmented, so it's typed); a head() composer turns declaration + page content into tags. A generator plugin walks the parsed route nodes to (a) emit the derived config and (b) enforce that every marketing/docs page leaf declares something.

    export const Route = createFileRoute('/guides/email-webhooks')({
      staticData: {
        seo: {
          kind: 'article',
          crumb: 'Email webhooks',                                  // breadcrumb chain from parent layouts
          sitemap: { priority: 0.7, changeFrequency: 'monthly' },
          related: ['/guides/email-authentication'],                // typed — a dead path is a type error
        },
      },
      head: (ctx) => seoHead(ctx, { title: '…', description: '…' }),
    })

    Why I reached for the plugin. Two things only the generator has:

    1. The parsed route nodes — so the derived config comes from the same tree that produces routeTree.gen.ts, instead of a second scanner that drifts.
    2. createFileRouteProps — which options each route file actually declared. That's what makes "this page declares neither staticData nor head" checkable. routeTree.gen.ts doesn't record it, so the alternative is re-AST-parsing every route file myself.

    So really just one question: is there a supported way to hook generation and read the parsed nodes under Start? If there isn't, no problem — I'll keep it on my side (I'm patching it locally today) and I won't rely on it.

    One small thing worth flagging regardless of the answer: plugins is currently in the exported configSchema and works under plain tanstackRouter(), so passing it to Start type-checks and validates, then silently does nothing. A loud failure there — or dropping it from the exported schema/types — would have saved me a fair bit of debugging.

Sign in to join this conversation.