feat: external directories in physical() virtual route mounts

.changeset/virtual-route-external-physical.md

@@ -0,0 +1,6 @@
+---
+'@tanstack/router-generator': minor
+'@tanstack/router-plugin': minor
+---
+
+feat: external directories in `physical()` virtual route mounts

packages/router-generator/src/generator.ts

@@ -275,6 +275,10 @@ export class Generator {
     )
   }
 
+  public getPhysicalDirectories(): Array<string> {
+    return [...this.physicalDirectories]
+  }
+
   public async run(event?: GeneratorEvent): Promise<void> {
     if (
       event &&

packages/router-generator/tests/generator.test.ts

@@ -388,6 +388,39 @@ describe('generator works', async () => {
     })
   })
 
+  it('physical() accepts a path outside routesDirectory', async () => {
+    const folderName = 'virtual-physical-external-abs'
+    const dir = makeFolderDir(folderName)
+    const externalDir = path.join(dir, 'external-target')
+    const config = await setupConfig(folderName, {
+      virtualRouteConfig: rootRoute('__root.tsx', [
+        index('index.tsx'),
+        physical('/external', externalDir),
+      ]),
+    })
+
+    const { routeNodes, physicalDirectories } = await virtualGetRouteNodes(
+      config,
+      dir,
+      {
+        indexTokenSegmentRegex: /^(?:index)$/,
+        routeTokenSegmentRegex: /^(?:route)$/,
+      },
+    )
+
+    expect(physicalDirectories).toContain(externalDir)
+    expect(routeNodes.map((n) => n.routePath).sort()).toEqual([
+      '/',
+      '/external/bar',
+      '/external/foo',
+    ])
+
+    const externalFoo = routeNodes.find((n) => n.routePath === '/external/foo')!
+    expect(path.resolve(config.routesDirectory, externalFoo.filePath)).toBe(
+      path.join(externalDir, 'foo.tsx'),
+    )
+  })
+
   it.each(folderNames)(
     'should create directory for routeTree if it does not exist',
     async () => {

packages/router-generator/tests/generator/virtual-physical-external-abs/external-target/bar.tsx

@@ -0,0 +1,4 @@
+import { createFileRoute } from '@tanstack/react-router'
+export const Route = createFileRoute('/external/bar')({
+  component: () => 'bar',
+})

packages/router-generator/tests/generator/virtual-physical-external-abs/external-target/foo.tsx

@@ -0,0 +1,4 @@
+import { createFileRoute } from '@tanstack/react-router'
+export const Route = createFileRoute('/external/foo')({
+  component: () => 'foo',
+})

packages/router-generator/tests/generator/virtual-physical-external-abs/routeTree.snapshot.ts

@@ -0,0 +1,59 @@
+/* eslint-disable */
+
+// @ts-nocheck
+
+// noinspection JSUnusedGlobalSymbols
+
+// This file was automatically generated by TanStack Router.
+// You should NOT make any changes in this file as it will be overwritten.
+// Additionally, you should also exclude this file from your linter and/or formatter to prevent it from being checked or modified.
+
+import { Route as rootRouteImport } from './routes/__root'
+import { Route as IndexRouteImport } from './routes/index'
+
+const IndexRoute = IndexRouteImport.update({
+  id: '/',
+  path: '/',
+  getParentRoute: () => rootRouteImport,
+} as any)
+
+export interface FileRoutesByFullPath {
+  '/': typeof IndexRoute
+}
+export interface FileRoutesByTo {
+  '/': typeof IndexRoute
+}
+export interface FileRoutesById {
+  __root__: typeof rootRouteImport
+  '/': typeof IndexRoute
+}
+export interface FileRouteTypes {
+  fileRoutesByFullPath: FileRoutesByFullPath
+  fullPaths: '/'
+  fileRoutesByTo: FileRoutesByTo
+  to: '/'
+  id: '__root__' | '/'
+  fileRoutesById: FileRoutesById
+}
+export interface RootRouteChildren {
+  IndexRoute: typeof IndexRoute
+}
+
+declare module '@tanstack/react-router' {
+  interface FileRoutesByPath {
+    '/': {
+      id: '/'
+      path: '/'
+      fullPath: '/'
+      preLoaderRoute: typeof IndexRouteImport
+      parentRoute: typeof rootRouteImport
+    }
+  }
+}
+
+const rootRouteChildren: RootRouteChildren = {
+  IndexRoute: IndexRoute,
+}
+export const routeTree = rootRouteImport
+  ._addFileChildren(rootRouteChildren)
+  ._addFileTypes<FileRouteTypes>()

packages/router-generator/tests/generator/virtual-physical-external-abs/routes/__root.tsx

@@ -0,0 +1,5 @@
+import { createRootRoute, Outlet } from '@tanstack/react-router'
+
+export const Route = createRootRoute({
+  component: () => <Outlet />,
+})

packages/router-generator/tests/generator/virtual-physical-external-abs/routes/index.tsx

@@ -0,0 +1,2 @@
+import { createFileRoute } from '@tanstack/react-router'
+export const Route = createFileRoute('/')({ component: () => 'home' })

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

@@ -9,6 +9,17 @@ import type { Config } from './config'
 
 const PLUGIN_NAME = 'unplugin:router-generator'
 
+// Physical mounts that point outside `routesDirectory` — their files aren't
+// covered by the bundler's own watcher.
+function getExternalPhysicalDirs(
+  generator: Generator,
+  routesDirectoryPath: string,
+): Array<string> {
+  return generator
+    .getPhysicalDirectories()
+    .filter((dir) => !dir.startsWith(routesDirectoryPath))
+}
+
 export const unpluginRouterGeneratorFactory: UnpluginFactory<
   Partial<Config | (() => Config)> | undefined
 > = (options = {}) => {
@@ -78,11 +89,30 @@ export const unpluginRouterGeneratorFactory: UnpluginFactory<
         initConfigAndGenerator({ root: config.root })
         await generate()
       },
+      configureServer(server) {
+        const external = getExternalPhysicalDirs(
+          generator,
+          getRoutesDirectoryPath(),
+        )
+        if (external.length === 0) return
+        for (const dir of external) {
+          server.watcher.add(dir)
+        }
+        const onEvent =
+          (event: 'create' | 'update' | 'delete') => (file: string) => {
+            if (!external.some((dir) => file.startsWith(dir))) return
+            void generate({ file, event })
+          }
+        server.watcher.on('add', onEvent('create'))
+        server.watcher.on('change', onEvent('update'))
+        server.watcher.on('unlink', onEvent('delete'))
+      },
     },
     rspack(compiler) {
       initConfigAndGenerator()
 
       let handle: FSWatcher | null = null
+      let externalHandle: FSWatcher | null = null
 
       compiler.hooks.beforeRun.tapPromise(PLUGIN_NAME, () => generate())
 
@@ -98,19 +128,29 @@ export const unpluginRouterGeneratorFactory: UnpluginFactory<
           .watch(routesDirectoryPath, { ignoreInitial: true })
           .on('add', (file) => generate({ file, event: 'create' }))
 
+        // External physical() mounts are outside rspack's file graph.
+        const external = getExternalPhysicalDirs(generator, routesDirectoryPath)
+        if (external.length > 0) {
+          externalHandle = chokidar
+            .watch(external, { ignoreInitial: true })
+            .on('add', (file) => generate({ file, event: 'create' }))
+            .on('change', (file) => generate({ file, event: 'update' }))
+            .on('unlink', (file) => generate({ file, event: 'delete' }))
+        }
+
         await generate()
       })
 
       compiler.hooks.watchClose.tap(PLUGIN_NAME, async () => {
-        if (handle) {
-          await handle.close()
-        }
+        if (handle) await handle.close()
+        if (externalHandle) await externalHandle.close()
       })
     },
     webpack(compiler) {
       initConfigAndGenerator()
 
       let handle: FSWatcher | null = null
+      let externalHandle: FSWatcher | null = null
 
       compiler.hooks.beforeRun.tapPromise(PLUGIN_NAME, () => generate())
 
@@ -126,13 +166,22 @@ export const unpluginRouterGeneratorFactory: UnpluginFactory<
           .watch(routesDirectoryPath, { ignoreInitial: true })
           .on('add', (file) => generate({ file, event: 'create' }))
 
+        // External physical() mounts are outside webpack's file graph.
+        const external = getExternalPhysicalDirs(generator, routesDirectoryPath)
+        if (external.length > 0) {
+          externalHandle = chokidar
+            .watch(external, { ignoreInitial: true })
+            .on('add', (file) => generate({ file, event: 'create' }))
+            .on('change', (file) => generate({ file, event: 'update' }))
+            .on('unlink', (file) => generate({ file, event: 'delete' }))
+        }
+
         await generate()
       })
 
       compiler.hooks.watchClose.tap(PLUGIN_NAME, async () => {
-        if (handle) {
-          await handle.close()
-        }
+        if (handle) await handle.close()
+        if (externalHandle) await externalHandle.close()
       })
 
       compiler.hooks.done.tap(PLUGIN_NAME, () => {

packages/router-plugin/tests/router-generator-plugin-watcher.test.ts

@@ -0,0 +1,106 @@
+import { mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import path from 'node:path'
+import chokidar from 'chokidar'
+import { afterEach, beforeEach, describe, it } from 'vitest'
+
+import { physical, rootRoute } from '@tanstack/virtual-file-routes'
+import { unpluginRouterGeneratorFactory } from '../src/core/router-generator-plugin'
+
+const ROOT_ROUTE = `import { createRootRoute, Outlet } from '@tanstack/react-router'
+export const Route = createRootRoute({ component: () => null })
+`
+
+const makeRouteFile = (routePath: string) =>
+  `import { createFileRoute } from '@tanstack/react-router'
+export const Route = createFileRoute('${routePath}')({ component: () => null })
+`
+
+async function waitUntil(
+  condition: () => boolean | Promise<boolean>,
+  { timeoutMs = 2000, intervalMs = 25 } = {},
+) {
+  const start = Date.now()
+  while (Date.now() - start < timeoutMs) {
+    if (await condition()) return
+    await new Promise((r) => setTimeout(r, intervalMs))
+  }
+  throw new Error(`Timed out after ${timeoutMs}ms`)
+}
+
+async function routeTreeIncludes(generatedRouteTree: string, match: string) {
+  try {
+    const text = await readFile(generatedRouteTree, 'utf-8')
+    return text.includes(match)
+  } catch {
+    return false
+  }
+}
+
+describe('router-generator-plugin vite watcher', () => {
+  let fixtureDir = ''
+  let externalDir = ''
+  let routesDir = ''
+  let generatedRouteTree = ''
+  let watcher: chokidar.FSWatcher | undefined
+
+  beforeEach(async () => {
+    fixtureDir = await mkdtemp(path.join(tmpdir(), 'tsr-plugin-watcher-'))
+    routesDir = path.join(fixtureDir, 'routes')
+    externalDir = path.join(fixtureDir, 'external')
+    generatedRouteTree = path.join(fixtureDir, 'routeTree.gen.ts')
+
+    await mkdir(routesDir, { recursive: true })
+    await mkdir(externalDir, { recursive: true })
+    await writeFile(path.join(routesDir, '__root.tsx'), ROOT_ROUTE)
+    await writeFile(
+      path.join(externalDir, 'alpha.tsx'),
+      makeRouteFile('/ext/alpha'),
+    )
+  })
+
+  afterEach(async () => {
+    if (watcher) {
+      await watcher.close()
+      watcher = undefined
+    }
+    await rm(fixtureDir, { recursive: true, force: true })
+  })
+
+  it('regenerates routeTree when a file is added to an external physical mount', async () => {
+    const plugin = unpluginRouterGeneratorFactory({
+      routesDirectory: routesDir,
+      generatedRouteTree,
+      virtualRouteConfig: rootRoute('__root.tsx', [
+        physical('/ext', externalDir),
+      ]),
+      disableLogging: true,
+    })
+
+    const viteHooks = plugin.vite as {
+      configResolved: (config: { root: string }) => Promise<void>
+      configureServer: (server: {
+        watcher: chokidar.FSWatcher
+      }) => void | Promise<void>
+    }
+
+    await viteHooks.configResolved({ root: fixtureDir })
+    await waitUntil(() => routeTreeIncludes(generatedRouteTree, "'/ext/alpha'"))
+
+    watcher = chokidar.watch(routesDir, { ignoreInitial: true })
+    await new Promise((resolve) => watcher!.once('ready', resolve))
+    await viteHooks.configureServer({ watcher })
+
+    // Add a new route file in the external mount.
+    const betaPath = path.join(externalDir, 'beta.tsx')
+    await writeFile(betaPath, makeRouteFile('/ext/beta'))
+
+    await waitUntil(() => routeTreeIncludes(generatedRouteTree, "'/ext/beta'"))
+
+    // Removing the file should likewise trigger regeneration.
+    await rm(betaPath)
+    await waitUntil(
+      async () => !(await routeTreeIncludes(generatedRouteTree, "'/ext/beta'")),
+    )
+  })
+})