Start: user router.plugins never reach the route generator (start-plugin-core overwrites them) #7768
Send to my agentWhich 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:
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#
- Add the probe generator plugin above to any TanStack Start app's
vite.config.ts - Run
vite devorvite build - Neither
[probe]line is printed; with the plaintanstackRouter()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.
schiller-manuel(GitHub profile, opens in a new tab) added labelsinformation needed
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.seocarries the route's policy (module-augmented, so it's typed); ahead()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:
- 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. createFileRouteProps— which options each route file actually declared. That's what makes "this page declares neitherstaticDatanorhead" checkable.routeTree.gen.tsdoesn'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:
pluginsis currently in the exportedconfigSchemaand works under plaintanstackRouter(), 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.- The parsed route nodes — so the derived config comes from the same tree that produces
Sheraff(GitHub profile, opens in a new tab) closed this
Sign in to join this conversation.
plugins are not a public API. what would you need this for?