fix(router-plugin): isolate route metadata per plugin instance

.changeset/clean-router-plugin-context.md

@@ -0,0 +1,6 @@
+---
+'@tanstack/router-plugin': patch
+'@tanstack/start-plugin-core': patch
+---
+
+Replace global route metadata with explicit router plugin contexts so multiple router plugin instances cannot cross-transform route files.

packages/router-plugin/package.json

@@ -63,6 +63,16 @@
         "default": "./dist/cjs/vite.cjs"
       }
     },
+    "./context": {
+      "import": {
+        "types": "./dist/esm/context.d.ts",
+        "default": "./dist/esm/context.js"
+      },
+      "require": {
+        "types": "./dist/cjs/context.d.cts",
+        "default": "./dist/cjs/context.cjs"
+      }
+    },
     "./rspack": {
       "import": {
         "types": "./dist/esm/rspack.d.ts",

packages/router-plugin/src/context.ts

@@ -0,0 +1,2 @@
+export { createRouterPluginContext } from './core/router-plugin-context'
+export type { RouterPluginContext } from './core/router-plugin-context'

packages/router-plugin/src/core/router-code-splitter-plugin.ts

@@ -22,9 +22,11 @@ import {
 } from './constants'
 import { decodeIdentifier } from './code-splitter/path-ids'
 import { debug, normalizePath } from './utils'
+import { createRouterPluginContext } from './router-plugin-context'
 import type { CodeSplitGroupings, SplitRouteIdentNodes } from './constants'
 import type { GetRoutesByFileMapResultValue } from '@tanstack/router-generator'
 import type { Config } from './config'
+import type { RouterPluginContext } from './router-plugin-context'
 import type {
   UnpluginFactory,
   TransformResult as UnpluginTransformResult,
@@ -76,9 +78,10 @@ const TRANSFORMATION_PLUGINS_BY_FRAMEWORK: Record<
   ],
 }
 
-export const unpluginRouterCodeSplitterFactory: UnpluginFactory<
-  Partial<Config | (() => Config)> | undefined
-> = (options = {}, { framework: _framework }) => {
+export function createRouterCodeSplitterPlugin(
+  options: Partial<Config | (() => Config)> | undefined = {},
+  routerPluginContext: RouterPluginContext,
+): ReturnType<UnpluginFactory<Partial<Config | (() => Config)> | undefined>> {
   let ROOT: string = process.cwd()
   let userConfig: Config
 
@@ -259,7 +262,7 @@ export const unpluginRouterCodeSplitterFactory: UnpluginFactory<
         handler(code, id) {
           const normalizedId = normalizePath(id)
           const generatorFileInfo =
-            globalThis.TSR_ROUTES_BY_ID_MAP?.get(normalizedId)
+            routerPluginContext.routesByFile.get(normalizedId)
           if (
             generatorFileInfo &&
             includedCode.some((included) => code.includes(included))
@@ -402,3 +405,9 @@ export const unpluginRouterCodeSplitterFactory: UnpluginFactory<
     },
   ]
 }
+
+export const unpluginRouterCodeSplitterFactory: UnpluginFactory<
+  Partial<Config | (() => Config)> | undefined
+> = (options = {}) => {
+  return createRouterCodeSplitterPlugin(options, createRouterPluginContext())
+}

packages/router-plugin/src/core/router-composed-plugin.ts

@@ -1,7 +1,8 @@
 import { getConfig } from '@tanstack/router-generator'
-import { unpluginRouterGeneratorFactory } from './router-generator-plugin'
-import { unpluginRouterCodeSplitterFactory } from './router-code-splitter-plugin'
-import { unpluginRouterHmrFactory } from './router-hmr-plugin'
+import { createRouterGeneratorPlugin } from './router-generator-plugin'
+import { createRouterCodeSplitterPlugin } from './router-code-splitter-plugin'
+import { createRouterHmrPlugin } from './router-hmr-plugin'
+import { createRouterPluginContext } from './router-plugin-context'
 import type { Config } from './config'
 import type {
   RspackCompiler,
@@ -29,25 +30,27 @@ function applyRspackInlineCssDefaultDefinePlugin(compiler: RspackCompiler) {
 
 export const unpluginRouterComposedFactory: UnpluginFactory<
   Partial<Config | (() => Config)> | undefined
-> = (options = {}, meta) => {
+> = (options = {}, _meta) => {
   const ROOT: string = process.cwd()
   const userConfig = getConfig(
     (typeof options === 'function' ? options() : options) as Partial<Config>,
     ROOT,
   )
+  const routerPluginContext = createRouterPluginContext()
 
-  const getPlugin = (
-    pluginFactory: UnpluginFactory<Partial<Config | (() => Config)>>,
-  ) => {
-    const plugin = pluginFactory(options, meta)
+  const getPlugin = (plugin: ReturnType<UnpluginFactory<any>>) => {
     if (!Array.isArray(plugin)) {
       return [plugin]
     }
     return plugin
   }
 
-  const routerGenerator = getPlugin(unpluginRouterGeneratorFactory)
-  const routerCodeSplitter = getPlugin(unpluginRouterCodeSplitterFactory)
+  const routerGenerator = getPlugin(
+    createRouterGeneratorPlugin(options, routerPluginContext),
+  )
+  const routerCodeSplitter = getPlugin(
+    createRouterCodeSplitterPlugin(options, routerPluginContext),
+  )
 
   const result = [
     {
@@ -85,7 +88,9 @@ export const unpluginRouterComposedFactory: UnpluginFactory<
   const isProduction = process.env.NODE_ENV === 'production'
 
   if (!isProduction && !userConfig.autoCodeSplitting) {
-    const routerHmr = getPlugin(unpluginRouterHmrFactory)
+    const routerHmr = getPlugin(
+      createRouterHmrPlugin(options, routerPluginContext),
+    )
     result.push(...routerHmr)
   }
   return result

packages/router-plugin/src/core/router-generator-plugin.ts

@@ -1,17 +1,20 @@
 import { isAbsolute, join, normalize } from 'node:path'
 import { Generator, resolveConfigPath } from '@tanstack/router-generator'
 import { getConfig } from './config'
+import { createRouterPluginContext } from './router-plugin-context'
 
 import type { GeneratorEvent } from '@tanstack/router-generator'
 import type { FSWatcher } from 'chokidar'
 import type { UnpluginFactory } from 'unplugin'
 import type { Config } from './config'
+import type { RouterPluginContext } from './router-plugin-context'
 
 const PLUGIN_NAME = 'unplugin:router-generator'
 
-export const unpluginRouterGeneratorFactory: UnpluginFactory<
-  Partial<Config | (() => Config)> | undefined
-> = (options = {}) => {
+export function createRouterGeneratorPlugin(
+  options: Partial<Config | (() => Config)> | undefined = {},
+  routerPluginContext: RouterPluginContext,
+): ReturnType<UnpluginFactory<Partial<Config | (() => Config)> | undefined>> {
   let ROOT: string = process.cwd()
   let userConfig: Config
   let generator: Generator
@@ -58,7 +61,7 @@ export const unpluginRouterGeneratorFactory: UnpluginFactory<
 
     try {
       await generator.run(generatorEvent)
-      globalThis.TSR_ROUTES_BY_ID_MAP = generator.getRoutesByFileMap()
+      routerPluginContext.routesByFile = generator.getRoutesByFileMap()
     } catch (e) {
       console.error(e)
     }
@@ -146,3 +149,9 @@ export const unpluginRouterGeneratorFactory: UnpluginFactory<
     },
   }
 }
+
+export const unpluginRouterGeneratorFactory: UnpluginFactory<
+  Partial<Config | (() => Config)> | undefined
+> = (options = {}) => {
+  return createRouterGeneratorPlugin(options, createRouterPluginContext())
+}

packages/router-plugin/src/core/router-hmr-plugin.ts

@@ -4,8 +4,10 @@ import { getReferenceRouteCompilerPlugins } from './code-splitter/plugins/framew
 import { createRouteHmrStatement } from './hmr'
 import { debug, normalizePath } from './utils'
 import { getConfig } from './config'
+import { createRouterPluginContext } from './router-plugin-context'
 import type { UnpluginFactory } from 'unplugin'
 import type { Config } from './config'
+import type { RouterPluginContext } from './router-plugin-context'
 
 /**
  * This plugin adds HMR support for file routes.
@@ -18,11 +20,18 @@ const includeCode = [
   'createRootRoute(',
   'createRootRouteWithContext(',
 ]
-export const unpluginRouterHmrFactory: UnpluginFactory<
-  Partial<Config> | undefined
-> = (options = {}) => {
+
+export function createRouterHmrPlugin(
+  options: Partial<Config | (() => Config)> | undefined = {},
+  routerPluginContext: RouterPluginContext,
+): ReturnType<UnpluginFactory<Partial<Config> | undefined>> {
   let ROOT: string = process.cwd()
-  let userConfig = options as Config
+
+  const resolveUserConfig = () => {
+    return getConfig(typeof options === 'function' ? options() : options, ROOT)
+  }
+
+  let userConfig = resolveUserConfig()
 
   return {
     name: 'tanstack-router:hmr',
@@ -37,7 +46,7 @@ export const unpluginRouterHmrFactory: UnpluginFactory<
       },
       handler(code, id) {
         const normalizedId = normalizePath(id)
-        const routeEntry = globalThis.TSR_ROUTES_BY_ID_MAP?.get(normalizedId)
+        const routeEntry = routerPluginContext.routesByFile.get(normalizedId)
         if (!routeEntry) {
           return null
         }
@@ -97,7 +106,7 @@ export const unpluginRouterHmrFactory: UnpluginFactory<
     vite: {
       configResolved(config) {
         ROOT = config.root
-        userConfig = getConfig(options, ROOT)
+        userConfig = resolveUserConfig()
       },
       applyToEnvironment(environment) {
         if (userConfig.plugin?.vite?.environmentName) {
@@ -108,3 +117,9 @@ export const unpluginRouterHmrFactory: UnpluginFactory<
     },
   }
 }
+
+export const unpluginRouterHmrFactory: UnpluginFactory<
+  Partial<Config> | undefined
+> = (options = {}) => {
+  return createRouterHmrPlugin(options, createRouterPluginContext())
+}

packages/router-plugin/src/core/router-plugin-context.ts

@@ -0,0 +1,11 @@
+import type { GetRoutesByFileMapResult } from '@tanstack/router-generator'
+
+export type RouterPluginContext = {
+  routesByFile: GetRoutesByFileMapResult
+}
+
+export function createRouterPluginContext(): RouterPluginContext {
+  return {
+    routesByFile: new Map(),
+  }
+}

packages/router-plugin/src/esbuild.ts

@@ -1,11 +1,15 @@
 import { createEsbuildPlugin } from 'unplugin'
 
 import { configSchema } from './core/config'
-import { unpluginRouterCodeSplitterFactory } from './core/router-code-splitter-plugin'
-import { unpluginRouterGeneratorFactory } from './core/router-generator-plugin'
+import { createRouterCodeSplitterPlugin } from './core/router-code-splitter-plugin'
+import { createRouterGeneratorPlugin } from './core/router-generator-plugin'
 import { unpluginRouterComposedFactory } from './core/router-composed-plugin'
+import { createRouterPluginContext } from './core/router-plugin-context'
 
 import type { CodeSplittingOptions, Config } from './core/config'
+import type { RouterPluginContext } from './core/router-plugin-context'
+
+type RouterPluginOptions = Partial<Config | (() => Config)> | undefined
 
 /**
  * @example
@@ -16,9 +20,15 @@ import type { CodeSplittingOptions, Config } from './core/config'
  * }
  * ```
  */
-const TanStackRouterGeneratorEsbuild = createEsbuildPlugin(
-  unpluginRouterGeneratorFactory,
-)
+const TanStackRouterGeneratorEsbuild = (
+  options?: RouterPluginOptions,
+  routerPluginContext?: RouterPluginContext,
+) => {
+  const pluginContext = routerPluginContext ?? createRouterPluginContext()
+  return createEsbuildPlugin((pluginOptions: RouterPluginOptions) =>
+    createRouterGeneratorPlugin(pluginOptions, pluginContext),
+  )(options)
+}
 
 /**
  * @example
@@ -29,9 +39,15 @@ const TanStackRouterGeneratorEsbuild = createEsbuildPlugin(
  * }
  * ```
  */
-const TanStackRouterCodeSplitterEsbuild = createEsbuildPlugin(
-  unpluginRouterCodeSplitterFactory,
-)
+const TanStackRouterCodeSplitterEsbuild = (
+  options?: RouterPluginOptions,
+  routerPluginContext?: RouterPluginContext,
+) => {
+  const pluginContext = routerPluginContext ?? createRouterPluginContext()
+  return createEsbuildPlugin((pluginOptions: RouterPluginOptions) =>
+    createRouterCodeSplitterPlugin(pluginOptions, pluginContext),
+  )(options)
+}
 
 /**
  * @example
@@ -54,4 +70,4 @@ export {
   tanstackRouter,
 }
 
-export type { Config, CodeSplittingOptions }
+export type { Config, CodeSplittingOptions, RouterPluginContext }

packages/router-plugin/src/index.ts

@@ -1,6 +1,7 @@
 export { configSchema, getConfig } from './core/config'
 export { unpluginRouterCodeSplitterFactory } from './core/router-code-splitter-plugin'
 export { unpluginRouterGeneratorFactory } from './core/router-generator-plugin'
+export { createRouterPluginContext } from './core/router-plugin-context'
 export type {
   Config,
   ConfigInput,
@@ -9,6 +10,7 @@ export type {
   DeletableNodes,
   HmrOptions,
 } from './core/config'
+export type { RouterPluginContext } from './core/router-plugin-context'
 export {
   tsrSplit,
   splitRouteIdentNodes,