From 3275f8d71d598d570c0458fffee6e27316561dd5 Mon Sep 17 00:00:00 2001
From: jamcalli <48490664+jamcalli@users.noreply.github.com>
Date: Mon, 13 Apr 2026 16:53:07 -0700
Subject: [PATCH 1/5] Add @fastify/tanstack renderer for TanStack Router SSR
---
examples/tanstack-vanilla-ts/package.json | 30 +++
.../tanstack-vanilla-ts/src/client/create.tsx | 19 ++
.../tanstack-vanilla-ts/src/client/index.html | 12 +
.../tanstack-vanilla-ts/src/client/routes.ts | 79 +++++++
.../src/client/tsconfig.json | 16 ++
.../tanstack-vanilla-ts/src/server.test.ts | 12 +
examples/tanstack-vanilla-ts/src/server.ts | 44 ++++
examples/tanstack-vanilla-ts/tsconfig.json | 27 +++
examples/tanstack-vanilla-ts/vite.config.js | 11 +
packages/fastify-tanstack/package.json | 69 ++++++
packages/fastify-tanstack/src/index.ts | 7 +
packages/fastify-tanstack/src/plugin/index.ts | 93 ++++++++
.../fastify-tanstack/src/plugin/preload.ts | 102 +++++++++
.../fastify-tanstack/src/plugin/virtual.ts | 94 ++++++++
packages/fastify-tanstack/src/rendering.ts | 179 +++++++++++++++
packages/fastify-tanstack/src/routing.ts | 143 ++++++++++++
packages/fastify-tanstack/src/server.ts | 20 ++
packages/fastify-tanstack/tsconfig.json | 21 ++
packages/fastify-tanstack/virtual/context.ts | 3 +
packages/fastify-tanstack/virtual/create.tsx | 8 +
packages/fastify-tanstack/virtual/index.ts | 10 +
packages/fastify-tanstack/virtual/mount.ts | 8 +
packages/fastify-tanstack/virtual/root.tsx | 3 +
packages/fastify-tanstack/virtual/routes.ts | 21 ++
packages/fastify-vite/src/index.test-d.ts | 4 +-
packages/fastify-vite/src/types/renderer.ts | 21 +-
pnpm-lock.yaml | 205 +++++++++++++++++-
27 files changed, 1230 insertions(+), 31 deletions(-)
create mode 100644 examples/tanstack-vanilla-ts/package.json
create mode 100644 examples/tanstack-vanilla-ts/src/client/create.tsx
create mode 100644 examples/tanstack-vanilla-ts/src/client/index.html
create mode 100644 examples/tanstack-vanilla-ts/src/client/routes.ts
create mode 100644 examples/tanstack-vanilla-ts/src/client/tsconfig.json
create mode 100644 examples/tanstack-vanilla-ts/src/server.test.ts
create mode 100644 examples/tanstack-vanilla-ts/src/server.ts
create mode 100644 examples/tanstack-vanilla-ts/tsconfig.json
create mode 100644 examples/tanstack-vanilla-ts/vite.config.js
create mode 100644 packages/fastify-tanstack/package.json
create mode 100644 packages/fastify-tanstack/src/index.ts
create mode 100644 packages/fastify-tanstack/src/plugin/index.ts
create mode 100644 packages/fastify-tanstack/src/plugin/preload.ts
create mode 100644 packages/fastify-tanstack/src/plugin/virtual.ts
create mode 100644 packages/fastify-tanstack/src/rendering.ts
create mode 100644 packages/fastify-tanstack/src/routing.ts
create mode 100644 packages/fastify-tanstack/src/server.ts
create mode 100644 packages/fastify-tanstack/tsconfig.json
create mode 100644 packages/fastify-tanstack/virtual/context.ts
create mode 100644 packages/fastify-tanstack/virtual/create.tsx
create mode 100644 packages/fastify-tanstack/virtual/index.ts
create mode 100644 packages/fastify-tanstack/virtual/mount.ts
create mode 100644 packages/fastify-tanstack/virtual/root.tsx
create mode 100644 packages/fastify-tanstack/virtual/routes.ts
diff --git a/examples/tanstack-vanilla-ts/package.json b/examples/tanstack-vanilla-ts/package.json
new file mode 100644
index 00000000..48e3aadd
--- /dev/null
+++ b/examples/tanstack-vanilla-ts/package.json
@@ -0,0 +1,30 @@
+{
+ "name": "@fastify-vite/example-tanstack-vanilla-ts",
+ "private": true,
+ "type": "module",
+ "scripts": {
+ "dev": "tsx src/server.ts --dev",
+ "start": "NODE_ENV=production node build/server.js",
+ "build": "pnpm build:server && pnpm build:client",
+ "build:client": "vite build --app",
+ "build:server": "tsc",
+ "test": "tsx --test"
+ },
+ "dependencies": {
+ "@fastify/cookie": "^11.0.2",
+ "@fastify/tanstack": "workspace:^",
+ "@fastify/vite": "workspace:^",
+ "@tanstack/react-router": "^1.0.0",
+ "fastify": "catalog:",
+ "react": "catalog:react",
+ "react-dom": "catalog:react"
+ },
+ "devDependencies": {
+ "@types/node": "^24.12.2",
+ "@types/react": "^19.1.2",
+ "@types/react-dom": "^19.1.2",
+ "tsx": "catalog:",
+ "typescript": "catalog:",
+ "vite": "catalog:"
+ }
+}
diff --git a/examples/tanstack-vanilla-ts/src/client/create.tsx b/examples/tanstack-vanilla-ts/src/client/create.tsx
new file mode 100644
index 00000000..f4d32c56
--- /dev/null
+++ b/examples/tanstack-vanilla-ts/src/client/create.tsx
@@ -0,0 +1,19 @@
+import { createRouter } from '@tanstack/react-router'
+import { routeTree } from './routes.ts'
+
+interface User {
+ name: string
+}
+
+export interface RouterContext {
+ user: User | null
+}
+
+export function createAppRouter(req?: { user?: User | null }) {
+ return createRouter({
+ routeTree,
+ context: {
+ user: req?.user ?? null,
+ },
+ })
+}
diff --git a/examples/tanstack-vanilla-ts/src/client/index.html b/examples/tanstack-vanilla-ts/src/client/index.html
new file mode 100644
index 00000000..e289a82c
--- /dev/null
+++ b/examples/tanstack-vanilla-ts/src/client/index.html
@@ -0,0 +1,12 @@
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/examples/tanstack-vanilla-ts/src/client/routes.ts b/examples/tanstack-vanilla-ts/src/client/routes.ts
new file mode 100644
index 00000000..2ce1f01d
--- /dev/null
+++ b/examples/tanstack-vanilla-ts/src/client/routes.ts
@@ -0,0 +1,79 @@
+import { createElement, Fragment } from 'react'
+import {
+ createRootRouteWithContext,
+ createRoute,
+ Outlet,
+ Scripts,
+ redirect,
+ useLoaderData,
+} from '@tanstack/react-router'
+import type { RouterContext } from './create.tsx'
+
+const rootRoute = createRootRouteWithContext()({
+ component: function Root() {
+ return createElement(Fragment, null, createElement(Outlet), createElement(Scripts))
+ },
+})
+
+const indexRoute = createRoute({
+ getParentRoute: () => rootRoute,
+ path: '/',
+ beforeLoad: ({ context }) => {
+ if (!context.user) {
+ throw redirect({ to: '/login' })
+ }
+ },
+ loader: ({ context }) => {
+ return { user: context.user! }
+ },
+ component: function Index() {
+ const { user } = useLoaderData({ from: '/' })
+ return createElement(
+ 'div',
+ null,
+ createElement('h1', null, `Hello ${user.name} from TanStack Router SSR!`),
+ createElement(
+ 'form',
+ {
+ onSubmit: async (e: { preventDefault: () => void }) => {
+ e.preventDefault()
+ await fetch('/api/logout', { method: 'POST' })
+ window.location.href = '/login'
+ },
+ },
+ createElement('button', { type: 'submit' }, 'Logout'),
+ ),
+ )
+ },
+})
+
+const loginRoute = createRoute({
+ getParentRoute: () => rootRoute,
+ path: '/login',
+ component: function Login() {
+ return createElement(
+ 'div',
+ null,
+ createElement('h1', null, 'Login'),
+ createElement(
+ 'form',
+ {
+ onSubmit: async (e: { preventDefault: () => void; target: any }) => {
+ e.preventDefault()
+ const form = new FormData(e.target)
+ await fetch('/api/login', {
+ method: 'POST',
+ headers: { 'Content-Type': 'application/json' },
+ body: JSON.stringify({ username: form.get('username') }),
+ })
+ window.location.href = '/'
+ },
+ },
+ createElement('input', { name: 'username', placeholder: 'Username', required: true }),
+ createElement('button', { type: 'submit' }, 'Sign in'),
+ ),
+ )
+ },
+})
+
+export const routeTree = rootRoute.addChildren([indexRoute, loginRoute])
diff --git a/examples/tanstack-vanilla-ts/src/client/tsconfig.json b/examples/tanstack-vanilla-ts/src/client/tsconfig.json
new file mode 100644
index 00000000..b076d185
--- /dev/null
+++ b/examples/tanstack-vanilla-ts/src/client/tsconfig.json
@@ -0,0 +1,16 @@
+{
+ "extends": "../../tsconfig.json",
+ "compilerOptions": {
+ "allowImportingTsExtensions": true,
+ "allowJs": false,
+ "jsx": "react-jsx",
+ "lib": ["DOM", "DOM.Iterable", "ESNext"],
+ "module": "ESNext",
+ "moduleResolution": "bundler",
+ "noEmit": true,
+ "target": "ES2023",
+ "types": ["vite/client"]
+ },
+ "include": ["**/*"],
+ "exclude": []
+}
diff --git a/examples/tanstack-vanilla-ts/src/server.test.ts b/examples/tanstack-vanilla-ts/src/server.test.ts
new file mode 100644
index 00000000..fb2000f7
--- /dev/null
+++ b/examples/tanstack-vanilla-ts/src/server.test.ts
@@ -0,0 +1,12 @@
+import test from 'node:test'
+import { resolve } from 'node:path'
+import { makeBuildTest, makeIndexTest } from '../../test-factories.mjs'
+import { main } from './server.ts'
+
+const viteConfigLocation = resolve(import.meta.dirname, '..')
+
+test('tanstack-vanilla-ts', async (t) => {
+ await t.test('build production bundle', makeBuildTest({ cwd: viteConfigLocation }))
+ await t.test('render index page in production', makeIndexTest({ main, dev: false }))
+ await t.test('render index page in development', makeIndexTest({ main, dev: true }))
+})
diff --git a/examples/tanstack-vanilla-ts/src/server.ts b/examples/tanstack-vanilla-ts/src/server.ts
new file mode 100644
index 00000000..995783ab
--- /dev/null
+++ b/examples/tanstack-vanilla-ts/src/server.ts
@@ -0,0 +1,44 @@
+import { resolve } from 'node:path'
+import Fastify from 'fastify'
+import FastifyVite from '@fastify/vite'
+import FastifyCookie from '@fastify/cookie'
+import * as renderer from '@fastify/tanstack'
+
+export async function main(dev?: boolean) {
+ const server = Fastify()
+
+ await server.register(FastifyCookie)
+
+ // Simulate auth: parse the "user" cookie on every request
+ server.addHook('onRequest', async (req) => {
+ const username = req.cookies.user
+ ;(req as any).user = username ? { name: username } : null
+ })
+
+ // Login endpoint sets the cookie
+ server.post('/api/login', async (req, reply) => {
+ const { username } = req.body as { username: string }
+ reply.setCookie('user', username, { path: '/', httpOnly: true })
+ return { ok: true }
+ })
+
+ // Logout endpoint clears the cookie
+ server.post('/api/logout', async (req, reply) => {
+ reply.clearCookie('user', { path: '/' })
+ return { ok: true }
+ })
+
+ await server.register(FastifyVite, {
+ root: resolve(import.meta.dirname, '..'),
+ dev: dev || process.argv.includes('--dev'),
+ renderer,
+ })
+
+ await server.vite.ready()
+ return server
+}
+
+if (process.argv[1] === import.meta.filename) {
+ const server = await main()
+ await server.listen({ port: 3000 })
+}
diff --git a/examples/tanstack-vanilla-ts/tsconfig.json b/examples/tanstack-vanilla-ts/tsconfig.json
new file mode 100644
index 00000000..c431b0ca
--- /dev/null
+++ b/examples/tanstack-vanilla-ts/tsconfig.json
@@ -0,0 +1,27 @@
+{
+ "compilerOptions": {
+ "allowJs": true,
+ "allowSyntheticDefaultImports": true,
+ "checkJs": false,
+ "esModuleInterop": true,
+ "forceConsistentCasingInFileNames": true,
+ "incremental": true,
+ "isolatedModules": true,
+ "lib": ["ESNext"],
+ "module": "NodeNext",
+ "moduleResolution": "NodeNext",
+ "outDir": "build",
+ "noFallthroughCasesInSwitch": true,
+ "noUnusedLocals": true,
+ "removeComments": true,
+ "resolveJsonModule": true,
+ "rootDir": "src",
+ "skipLibCheck": true,
+ "sourceMap": true,
+ "strict": true,
+ "target": "ESNext",
+ "verbatimModuleSyntax": true
+ },
+ "include": ["src"],
+ "exclude": ["src/client/**/*", "src/**/*.test.ts"]
+}
diff --git a/examples/tanstack-vanilla-ts/vite.config.js b/examples/tanstack-vanilla-ts/vite.config.js
new file mode 100644
index 00000000..80c7c038
--- /dev/null
+++ b/examples/tanstack-vanilla-ts/vite.config.js
@@ -0,0 +1,11 @@
+import { resolve } from 'node:path'
+import viteFastifyTanstack from '@fastify/tanstack/plugin'
+
+export default {
+ root: resolve(import.meta.dirname, 'src', 'client'),
+ plugins: [viteFastifyTanstack()],
+ build: {
+ emptyOutDir: true,
+ outDir: resolve(import.meta.dirname, 'build'),
+ },
+}
diff --git a/packages/fastify-tanstack/package.json b/packages/fastify-tanstack/package.json
new file mode 100644
index 00000000..8ec150a4
--- /dev/null
+++ b/packages/fastify-tanstack/package.json
@@ -0,0 +1,69 @@
+{
+ "name": "@fastify/tanstack",
+ "version": "0.0.1",
+ "description": "@fastify/vite renderer for TanStack Router SSR",
+ "keywords": [
+ "fastify",
+ "ssr",
+ "tanstack",
+ "tanstack-router",
+ "vite"
+ ],
+ "homepage": "https://github.com/fastify/fastify-vite",
+ "bugs": {
+ "url": "https://github.com/fastify/fastify-vite/issues"
+ },
+ "license": "MIT",
+ "repository": {
+ "type": "git",
+ "url": "git+https://github.com/fastify/fastify-vite.git"
+ },
+ "files": [
+ "dist/**/*",
+ "!dist/**/*.test.*",
+ "virtual/**/*"
+ ],
+ "type": "module",
+ "main": "dist/index.js",
+ "types": "./dist/index.d.ts",
+ "exports": {
+ ".": {
+ "types": "./dist/index.d.ts",
+ "import": "./dist/index.js"
+ },
+ "./plugin": {
+ "types": "./dist/plugin/index.d.ts",
+ "import": "./dist/plugin/index.js"
+ },
+ "./server": {
+ "types": "./dist/server.d.ts",
+ "import": "./dist/server.js"
+ }
+ },
+ "publishConfig": {
+ "access": "public"
+ },
+ "scripts": {
+ "build": "tsc",
+ "prepublishOnly": "pnpm build"
+ },
+ "dependencies": {
+ "@fastify/vite": "workspace:^",
+ "@tanstack/history": "^1.0.0",
+ "@tanstack/react-router": "^1.0.0",
+ "@tanstack/router-core": "^1.0.0",
+ "mlly": "^1.7.4",
+ "react": "catalog:react",
+ "react-dom": "catalog:react",
+ "youch": "^3.3.4"
+ },
+ "devDependencies": {
+ "@types/node": "^24.12.2",
+ "@types/react": "^19.1.2",
+ "@types/react-dom": "^19.1.2",
+ "fastify": "catalog:",
+ "typescript": "catalog:",
+ "vite": "catalog:",
+ "vitest": "catalog:"
+ }
+}
diff --git a/packages/fastify-tanstack/src/index.ts b/packages/fastify-tanstack/src/index.ts
new file mode 100644
index 00000000..152bf56d
--- /dev/null
+++ b/packages/fastify-tanstack/src/index.ts
@@ -0,0 +1,7 @@
+export { prepareServer } from './server.ts'
+
+export { prepareClient, createRouteHandler, createErrorHandler, createRoute } from './routing.ts'
+
+export { createRenderFunction, createHtmlFunction } from './rendering.ts'
+
+export const clientModule = '$app/index.ts'
diff --git a/packages/fastify-tanstack/src/plugin/index.ts b/packages/fastify-tanstack/src/plugin/index.ts
new file mode 100644
index 00000000..446a4430
--- /dev/null
+++ b/packages/fastify-tanstack/src/plugin/index.ts
@@ -0,0 +1,93 @@
+import viteFastify from '@fastify/vite/plugin'
+import type { Plugin, ResolvedConfig } from 'vite'
+import {
+ prefix,
+ resolveId,
+ loadSource,
+ loadVirtualModule,
+ createPlaceholderExports,
+} from './virtual.ts'
+import { closeBundle as closeBundleImpl } from './preload.ts'
+
+interface PluginContext {
+ root: string
+ resolvedConfig: ResolvedConfig | null
+}
+
+export default function viteFastifyTanstackPlugin(): Plugin[] {
+ let resolvedBundle: Record | null = null
+
+ const context: PluginContext = {
+ root: '',
+ resolvedConfig: null,
+ }
+ return [
+ viteFastify({
+ clientModule: '$app/index.ts',
+ }),
+ {
+ name: 'vite-plugin-tanstack-fastify',
+ config: configHook,
+ configResolved: configResolved.bind(context),
+ resolveId: resolveId.bind(context),
+ async load(id) {
+ if (id.includes('?server') && !this.environment.config.build?.ssr) {
+ const source = loadSource(id)
+ return createPlaceholderExports(source)
+ }
+ if (id.includes('?client') && this.environment.config.build?.ssr) {
+ const source = loadSource(id)
+ return createPlaceholderExports(source)
+ }
+ if (prefix.test(id)) {
+ const [, virtual] = id.split(prefix)
+ if (virtual) {
+ return loadVirtualModule(virtual)
+ }
+ }
+ },
+ transformIndexHtml: {
+ order: 'post',
+ handler(_html, { bundle }) {
+ if (bundle) {
+ resolvedBundle = bundle
+ }
+ },
+ },
+ closeBundle() {
+ closeBundleImpl.call(this, resolvedBundle)
+ },
+ },
+ ]
+}
+
+function configResolved(this: PluginContext, config: ResolvedConfig) {
+ this.resolvedConfig = config
+ this.root = config.root
+}
+
+function configHook(config: Record, { command }: { command: string }) {
+ if (command === 'build') {
+ if (!config.build) {
+ config.build = {}
+ }
+ if (!config.build.rollupOptions) {
+ config.build.rollupOptions = {}
+ }
+ config.build.rollupOptions.onwarn = onwarn
+ }
+}
+
+function onwarn(
+ warning: { code?: string; message?: string },
+ rollupWarn: (warning: unknown) => void,
+) {
+ if (
+ !(
+ warning.code == 'PLUGIN_WARNING' &&
+ warning.message?.includes?.('dynamic import will not move module into another chunk')
+ )
+ ) {
+ rollupWarn(warning)
+ }
+}
diff --git a/packages/fastify-tanstack/src/plugin/preload.ts b/packages/fastify-tanstack/src/plugin/preload.ts
new file mode 100644
index 00000000..b9ab195d
--- /dev/null
+++ b/packages/fastify-tanstack/src/plugin/preload.ts
@@ -0,0 +1,102 @@
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs'
+import { join, isAbsolute, parse as parsePath } from 'node:path'
+
+const imageFileRE = /\.((png)|(jpg)|(svg)|(webp)|(gif))$/
+
+interface BundleChunk {
+ type: 'chunk'
+ isDynamicEntry?: boolean
+ name: string
+ fileName: string
+ imports?: string[]
+ moduleIds: string[]
+ modules: Record
+ viteMetadata?: {
+ importedCss?: string[]
+ }
+}
+
+function isDynamicChunk(meta: unknown): meta is BundleChunk {
+ return (
+ typeof meta === 'object' &&
+ meta !== null &&
+ (meta as Record).type === 'chunk' &&
+ !!(meta as Record).isDynamicEntry
+ )
+}
+
+export async function closeBundle(
+ this: {
+ environment: {
+ name: string
+ config: {
+ build: { assetsInlineLimit: number | Function; outDir: string }
+ root: string
+ base: string
+ }
+ }
+ },
+ resolvedBundle: Record | null,
+) {
+ if (this.environment.name !== 'client') {
+ return
+ }
+ const { assetsInlineLimit } = this.environment.config.build
+ const { root, base } = this.environment.config
+ let distDir: string
+ if (isAbsolute(this.environment.config.build.outDir)) {
+ distDir = this.environment.config.build.outDir
+ } else {
+ distDir = join(root, this.environment.config.build.outDir)
+ }
+
+ const indexHtml = readFileSync(join(distDir, 'index.html'), 'utf8')
+
+ const routeChunks = Object.values(resolvedBundle ?? {}).filter(isDynamicChunk)
+
+ if (routeChunks.length === 0) {
+ return
+ }
+
+ const limit = typeof assetsInlineLimit === 'number' ? assetsInlineLimit : 0
+
+ for (const chunk of routeChunks) {
+ const jsImports = chunk.imports ?? []
+ const cssImports = chunk.viteMetadata?.importedCss ?? []
+ const images = chunk.moduleIds.filter((img) => {
+ return chunk.modules[img].originalLength > limit && imageFileRE.test(img)
+ })
+
+ let imagePreloads = '\n'
+ for (let image of images) {
+ image = image.slice(root.length + 1)
+ imagePreloads += ` \n`
+ }
+ let cssPreloads = ''
+ for (const css of cssImports) {
+ cssPreloads += ` \n`
+ }
+ let jsPreloads = ''
+ for (const js of jsImports) {
+ jsPreloads += ` \n`
+ }
+
+ const pageHtml = appendHead(indexHtml, imagePreloads, cssPreloads, jsPreloads)
+ const htmlPath = `html/${chunk.name}.html`
+ writeHtml(htmlPath, pageHtml, distDir)
+ }
+}
+
+function appendHead(html: string, ...tags: string[]) {
+ const content = tags.join('\n ')
+ return html.replace(/]*)>/i, `\n ${content}`)
+}
+
+function writeHtml(htmlPath: string, pageHtml: string, distDir: string) {
+ const { dir, base } = parsePath(htmlPath)
+ const htmlDir = join(distDir, dir)
+ if (!existsSync(htmlDir)) {
+ mkdirSync(htmlDir, { recursive: true })
+ }
+ writeFileSync(join(htmlDir, base), pageHtml)
+}
diff --git a/packages/fastify-tanstack/src/plugin/virtual.ts b/packages/fastify-tanstack/src/plugin/virtual.ts
new file mode 100644
index 00000000..92ca49e6
--- /dev/null
+++ b/packages/fastify-tanstack/src/plugin/virtual.ts
@@ -0,0 +1,94 @@
+import { readFileSync, existsSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { findExports } from 'mlly'
+
+const virtualRoot = resolve(import.meta.dirname, '..', '..', 'virtual')
+
+const virtualModules = ['mount.ts', 'routes.ts', 'create.tsx', 'root.tsx', 'context.ts', 'index.ts']
+
+export const prefix = /^\/?\$app\//
+
+export async function resolveId(this: { root: string }, id: string) {
+ if (process.platform === 'win32' && /^\.\.\/[C-Z]:/.test(id)) {
+ return id.substring(3)
+ }
+
+ if (prefix.test(id)) {
+ const [, virtual] = id.split(prefix)
+ if (virtual) {
+ const override = loadVirtualModuleOverride(this.root, virtual)
+ if (override) {
+ return override
+ }
+ return id
+ }
+ }
+}
+
+export function loadVirtualModule(virtual: string): { code: string; map: null } | undefined {
+ if (!matchesVirtualModule(virtual)) {
+ return
+ }
+ const codePath = resolve(virtualRoot, virtual)
+ return {
+ code: readFileSync(codePath, 'utf8'),
+ map: null,
+ }
+}
+
+function matchesVirtualModule(virtual: string): boolean {
+ if (!virtual) {
+ return false
+ }
+ for (const entry of virtualModules) {
+ if (virtual.startsWith(entry)) {
+ return true
+ }
+ }
+ return false
+}
+
+function loadVirtualModuleOverride(viteProjectRoot: string, virtual: string): string | undefined {
+ if (!matchesVirtualModule(virtual)) {
+ return
+ }
+ const overridePath = resolve(viteProjectRoot, virtual)
+ if (existsSync(overridePath)) {
+ return overridePath
+ }
+ const base = overridePath.replace(/\.[^.]+$/, '')
+ for (const ext of ['.ts', '.tsx', '.js', '.jsx']) {
+ const candidate = base + ext
+ if (candidate !== overridePath && existsSync(candidate)) {
+ return candidate
+ }
+ }
+}
+
+export function loadSource(id: string): string {
+ const filePath = id.replace(/\?client$/, '').replace(/\?server$/, '')
+ return readFileSync(filePath, 'utf8')
+}
+
+export function createPlaceholderExports(source: string): string {
+ let pExports = ''
+ for (const exp of findExports(source)) {
+ switch (exp.type) {
+ case 'named':
+ for (const name of exp.names) {
+ pExports += `export const ${name} = {}\n`
+ }
+ break
+ case 'default':
+ pExports += `export default {}\n`
+ break
+ case 'declaration':
+ pExports += `export const ${exp.name} = {}\n`
+ break
+ case 'star':
+ pExports += `export ${exp.code}\n`
+ break
+ }
+ }
+ return pExports
+}
diff --git a/packages/fastify-tanstack/src/rendering.ts b/packages/fastify-tanstack/src/rendering.ts
new file mode 100644
index 00000000..1e4757ea
--- /dev/null
+++ b/packages/fastify-tanstack/src/rendering.ts
@@ -0,0 +1,179 @@
+import { PassThrough } from 'node:stream'
+import { createElement } from 'react'
+import { createRequire } from 'node:module'
+
+// Bun's react-dom/server shim only activates through require(), not ESM import.
+// Without this, renderToPipeableStream silently uses the wrong implementation.
+const _require = createRequire(import.meta.url)
+const { renderToPipeableStream } = _require(
+ 'react-dom/server.node',
+) as typeof import('react-dom/server')
+import { createMemoryHistory } from '@tanstack/history'
+import { RouterProvider } from '@tanstack/react-router'
+import type { AnyRouter, AnyRedirect } from '@tanstack/router-core'
+import {
+ attachRouterServerSsrUtils,
+ transformPipeableStreamWithRouter,
+} from '@tanstack/router-core/ssr/server'
+import { createHtmlTemplateFunction } from '@fastify/vite/utils'
+import type { RuntimeConfig } from '@fastify/vite'
+import type { FastifyInstance, FastifyReply, FastifyRequest } from 'fastify'
+
+interface RenderResult {
+ pipeable: NodeJS.ReadableStream | null
+ router: AnyRouter
+ redirect?: AnyRedirect
+}
+
+export async function createRenderFunction(client: Record) {
+ const createAppRouter = client.createAppRouter as (req?: FastifyRequest) => AnyRouter
+ // Registered as reply.render()
+ return async function (this: FastifyReply): Promise {
+ const url = this.request.url
+ const router = createAppRouter(this.request)
+
+ attachRouterServerSsrUtils({ router, manifest: undefined })
+
+ const history = createMemoryHistory({ initialEntries: [url] })
+ router.update({ history })
+
+ await router.load()
+
+ const pendingRedirect = router.stores.redirect.get()
+ if (pendingRedirect) {
+ return { pipeable: null, router, redirect: pendingRedirect }
+ }
+
+ await router.serverSsr?.dehydrate()
+
+ const app = createElement(RouterProvider, { router })
+
+ const pipeable = await new Promise((resolve, reject) => {
+ try {
+ const stream = renderToPipeableStream(app, {
+ onShellReady() {
+ resolve(stream as unknown as NodeJS.ReadableStream)
+ },
+ onShellError: reject,
+ onError(error: unknown) {
+ console.error('SSR streaming error:', error)
+ },
+ })
+ } catch (error) {
+ reject(error)
+ }
+ })
+
+ return { pipeable, router }
+ }
+}
+
+type HtmlFunction = (this: FastifyReply) => FastifyReply | Promise
+
+// The return value of this function gets registered as reply.html()
+export async function createHtmlFunction(
+ source: string,
+ _: FastifyInstance,
+ config: RuntimeConfig,
+): Promise {
+ if (config.spa) {
+ const template = createHtmlTemplateFunction(source)
+ return function (this: FastifyReply) {
+ this.type('text/html')
+ this.send(template({ element: '' }))
+ return this
+ }
+ }
+
+ const { beforeHtml, afterHtml } = splitHtmlTemplate(source)
+
+ return async function (this: FastifyReply) {
+ const {
+ pipeable,
+ router,
+ redirect: pendingRedirect,
+ } = (await (this as any).render()) as RenderResult
+
+ if (pendingRedirect) {
+ const resolved = router.resolveRedirect(pendingRedirect)
+ const href = resolved.headers.get('Location') ?? '/'
+ this.code(resolved.status)
+ this.redirect(href)
+ return this
+ }
+
+ const statusCode = router.stores.statusCode.get()
+ this.code(statusCode)
+ this.type('text/html')
+
+ if (!pipeable) {
+ this.send(beforeHtml + afterHtml)
+ return this
+ }
+
+ const assembled = assembleHtmlStream(beforeHtml, afterHtml, pipeable)
+ const transformed = transformPipeableStreamWithRouter(router, assembled)
+
+ if (config.dev) {
+ const checker = new PassThrough()
+ let sawBarrier = false
+ checker.on('data', (chunk: Buffer) => {
+ if (!sawBarrier && chunk.toString().includes('$tsr-stream-barrier')) {
+ sawBarrier = true
+ }
+ })
+ checker.on('end', () => {
+ if (!sawBarrier) {
+ console.warn(
+ '[@fastify/tanstack] not found in rendered output. ' +
+ 'Dehydration will fail. Ensure root route renders .',
+ )
+ }
+ })
+ transformed.pipe(checker)
+ }
+
+ this.send(transformed)
+ return this
+ }
+}
+
+function splitHtmlTemplate(source: string) {
+ const marker = ''
+ const idx = source.indexOf(marker)
+ if (idx !== -1) {
+ return {
+ beforeHtml: source.slice(0, idx),
+ afterHtml: source.slice(idx + marker.length),
+ }
+ }
+ const bodyIdx = source.indexOf(' ')
+ if (bodyIdx !== -1) {
+ return {
+ beforeHtml: source.slice(0, bodyIdx),
+ afterHtml: source.slice(bodyIdx),
+ }
+ }
+ return { beforeHtml: source, afterHtml: '' }
+}
+
+function assembleHtmlStream(
+ beforeHtml: string,
+ afterHtml: string,
+ pipeable: NodeJS.ReadableStream,
+) {
+ const stream = new PassThrough()
+
+ const reactOut = new PassThrough()
+ reactOut.on('data', (chunk: Buffer) => stream.write(chunk))
+ reactOut.on('end', () => {
+ stream.write(afterHtml)
+ stream.end()
+ })
+ reactOut.on('error', (err: Error) => stream.destroy(err))
+
+ stream.write(beforeHtml)
+ ;(pipeable as any).pipe(reactOut)
+
+ return stream
+}
diff --git a/packages/fastify-tanstack/src/routing.ts b/packages/fastify-tanstack/src/routing.ts
new file mode 100644
index 00000000..3a7d5622
--- /dev/null
+++ b/packages/fastify-tanstack/src/routing.ts
@@ -0,0 +1,143 @@
+import { readFileSync } from 'node:fs'
+import { join, isAbsolute } from 'node:path'
+import { createHtmlFunction } from './rendering.ts'
+import Youch from 'youch'
+import type { FastifyInstance, FastifyReply, FastifyRequest, RouteOptions } from 'fastify'
+import type { RuntimeConfig, RouteDefinition } from '@fastify/vite'
+
+interface ClientEntries {
+ ssr?: unknown
+ [key: string]: unknown
+}
+
+interface TanStackRoute {
+ path: string
+ name?: string
+ configure?: (scope: FastifyInstance) => void | Promise