Skip to content
Source
Sign inSign up
TanStack/router
Open History to see the last commit

plugin.ts

272 lines9.5 KB

1import { isRunnableDevEnvironment } from 'vite'
2import { NodeRequest, sendNodeResponse } from 'srvx/node'
3import { ENTRY_POINTS, VITE_ENVIRONMENT_NAMES } from '../../constants'
4import {
5 CSS_MODULES_REGEX,
6 collectDevStyles,
7 normalizeCssModuleCacheKey,
8} from './dev-styles'
9import type { Connect, DevEnvironment, PluginOption } from 'vite'
10import type { GetConfigFn } from '../../types'
11​
12export function devServerPlugin({
13 getConfig: _getConfig,
14 devSsrStylesEnabled,
15 installDevServerMiddleware,
16}: {
17 getConfig: GetConfigFn
18 devSsrStylesEnabled: boolean
19 installDevServerMiddleware: boolean | undefined
20}): PluginOption {
21 let isTest = false
22​
23 // Cache CSS modules content during transform hook.
24 // For CSS modules, the transform hook receives the raw CSS content before
25 // Vite wraps it in JS. We capture this to use during SSR style collection.
26 const cssModulesCache: Record<string, string> = {}
27​
28 return [
29 {
30 name: 'tanstack-start-core:dev-server',
31 config(_userConfig, { mode }) {
32 isTest = isTest ? isTest : mode === 'test'
33 },
34 // Capture CSS modules content during transform
35 transform: {
36 filter: {
37 id: CSS_MODULES_REGEX,
38 },
39 handler(code, id) {
40 cssModulesCache[normalizeCssModuleCacheKey(id)] = code
41 },
42 },
43 configureServer(viteDevServer) {
44 if (isTest) {
45 return
46 }
47​
48 // CSS middleware registered in PRE-PHASE (before Vite's internal middlewares)
49 // This ensures it handles /@tanstack-start/styles.css before any catch-all middleware
50 // from other plugins (like nitro) that may be registered in the post-phase.
51 // This makes the CSS endpoint work regardless of plugin order in the Vite config.
52 // We check pathname.endsWith() to handle basepaths (e.g., /my-app/@tanstack-start/styles.css)
53 // since pre-phase runs before Vite's base middleware strips the basepath.
54 if (devSsrStylesEnabled) {
55 viteDevServer.middlewares.use(async (req, res, next) => {
56 const url = req.url ?? ''
57 const pathname = url.split('?')[0]
58 if (!pathname?.endsWith('/@tanstack-start/styles.css')) {
59 return next()
60 }
61​
62 try {
63 // Parse route IDs from query param
64 const urlObj = new URL(url, 'http://localhost')
65 const routesParam = urlObj.searchParams.get('routes')
66 const ids = routesParam ? routesParam.split(',') : []
67​
68 // Build entries list from route file paths
69 const entries: Array<string> = []
70​
71 // Look up route file paths from manifest
72 // Only routes registered in the manifest are used - this prevents path injection
73 const routesManifest = (globalThis as any).TSS_ROUTES_MANIFEST as
74 | Record<string, { filePath: string; children?: Array<string> }>
75 | undefined
76​
77 if (routesManifest && ids.length > 0) {
78 for (const routeId of ids) {
79 const route = routesManifest[routeId]
80 if (route?.filePath) {
81 entries.push(route.filePath)
82 }
83 }
84 }
85​
86 const css =
87 entries.length > 0
88 ? await collectDevStyles({
89 viteDevServer,
90 entries,
91 cssModulesCache,
92 })
93 : undefined
94​
95 res.setHeader('Content-Type', 'text/css')
96 res.setHeader('Cache-Control', 'no-store')
97 res.end(css ?? '')
98 } catch (e) {
99 // Log error but still return valid CSS response to avoid MIME type issues
100 console.error('[tanstack-start] Error collecting dev styles:', e)
101 res.setHeader('Content-Type', 'text/css')
102 res.setHeader('Cache-Control', 'no-store')
103 res.end(
104 `/* Error collecting styles: ${e instanceof Error ? e.message : String(e)} */`,
105 )
106 }
107 })
108 }
109​
110 if (viteDevServer.config.experimental.bundledDev) {
111 // Vite's bundled dev client watches sources separately, but Start still
112 // needs the SSR environment's module graph to see route/server edits.
113 viteDevServer.watcher.add(viteDevServer.config.root)
114 }
115​
116 return () => {
117 const serverEnv = viteDevServer.environments[
118 VITE_ENVIRONMENT_NAMES.server
119 ] as DevEnvironment | undefined
120​
121 if (!serverEnv) {
122 throw new Error(
123 `Server environment ${VITE_ENVIRONMENT_NAMES.server} not found`,
124 )
125 }
126 const clientEnv = viteDevServer.environments[
127 VITE_ENVIRONMENT_NAMES.client
128 ] as
129 | {
130 devEngine?: {
131 ensureLatestBuildOutput?: () => Promise<void>
132 }
133 }
134 | undefined
135​
136 const installMiddleware = installDevServerMiddleware
137 if (installMiddleware === false) {
138 return
139 }
140 if (installMiddleware == undefined) {
141 // do not install middleware in middlewareMode by default
142 if (viteDevServer.config.server.middlewareMode) {
143 return
144 }
145​
146 // do not install middleware if SSR env in case another plugin already did
147 if (
148 !isRunnableDevEnvironment(serverEnv) ||
149 // do not check via `isFetchableDevEnvironment` since nitro does implement the `FetchableDevEnvironment` interface but not via inheritance (which this helper checks)
150 'dispatchFetch' in serverEnv
151 ) {
152 return
153 }
154 }
155​
156 if (!isRunnableDevEnvironment(serverEnv)) {
157 throw new Error(
158 'cannot install vite dev server middleware for TanStack Start since the SSR environment is not a RunnableDevEnvironment',
159 )
160 }
161 viteDevServer.middlewares.use(async (req, res) => {
162 // fix the request URL to match the original URL
163 // otherwise, the request URL will '/index.html'
164 if (req.originalUrl) {
165 req.url = req.originalUrl
166 }
167 const webReq = new NodeRequest({ req, res })
168​
169 try {
170 const serverRunner = serverEnv.runner
171​
172 // Import and resolve the request by running the server request entry point
173 // this request entry point must implement the `fetch` API as follows:
174 /**
175 * export default {
176 * fetch(req: Request): Promise<Response>
177 * }
178 */
179 if (viteDevServer.config.experimental.bundledDev) {
180 await clientEnv?.devEngine?.ensureLatestBuildOutput?.()
181 serverEnv.moduleGraph.invalidateAll()
182 serverRunner.clearCache()
183 }
184​
185 const serverEntry = await serverRunner.import(ENTRY_POINTS.server)
186 const webRes = await serverEntry['default'].fetch(webReq)
187​
188 return sendNodeResponse(res, webRes)
189 } catch (e) {
190 console.error(e)
191 try {
192 viteDevServer.ssrFixStacktrace(e as Error)
193 } catch {}
194​
195 if (
196 webReq.headers.get('content-type')?.includes('application/json')
197 ) {
198 return sendNodeResponse(
199 res,
200 new Response(
201 JSON.stringify(
202 {
203 status: 500,
204 error: 'Internal Server Error',
205 message:
206 'An unexpected error occurred. Please try again later.',
207 timestamp: new Date().toISOString(),
208 },
209 null,
210 2,
211 ),
212 {
213 status: 500,
214 headers: {
215 'Content-Type': 'application/json',
216 },
217 },
218 ),
219 )
220 }
221​
222 return sendNodeResponse(
223 res,
224 new Response(
225 `
226 <!DOCTYPE html>
227 <html lang="en">
228 <head>
229 <meta charset="UTF-8" />
230 <title>Error</title>
231 <script type="module">
232 import { ErrorOverlay } from '/@vite/client'
233 document.body.appendChild(new ErrorOverlay(${JSON.stringify(
234 prepareError(req, e),
235 ).replace(/</g, '\\u003c')}))
236 </script>
237 </head>
238 <body>
239 </body>
240 </html>
241 `,
242 {
243 status: 500,
244 headers: {
245 'Content-Type': 'text/html',
246 },
247 },
248 ),
249 )
250 }
251 })
252 }
253 },
254 },
255 ]
257​
258/**
259 * Formats error for SSR message in error overlay
260 * @param req
261 * @param error
262 * @returns
263 */
264function prepareError(req: Connect.IncomingMessage, error: unknown) {
265 const e = error as Error
266 return {
267 message: `An error occurred while server rendering ${req.url}:\n\n\t${
268 typeof e === 'string' ? e : e.message
269 } `,
270 stack: typeof e === 'string' ? '' : e.stack,
271 }