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

server.ts

556 lines16.9 KB

1/**
2 * TanStack Start Production Server with Bun
3 *
4 * A high-performance production server for TanStack Start applications that
5 * implements intelligent static asset loading with configurable memory management.
6 *
7 * Features:
8 * - Hybrid loading strategy (preload small files, serve large files on-demand)
9 * - Configurable file filtering with include/exclude patterns
10 * - Memory-efficient response generation
11 * - Production-ready caching headers
12 *
13 * Environment Variables:
14 *
15 * PORT (number)
16 * - Server port number
17 * - Default: 3000
18 *
19 * ASSET_PRELOAD_MAX_SIZE (number)
20 * - Maximum file size in bytes to preload into memory
21 * - Files larger than this will be served on-demand from disk
22 * - Default: 5242880 (5MB)
23 * - Example: ASSET_PRELOAD_MAX_SIZE=5242880 (5MB)
24 *
25 * ASSET_PRELOAD_INCLUDE_PATTERNS (string)
26 * - Comma-separated list of glob patterns for files to include
27 * - If specified, only matching files are eligible for preloading
28 * - Patterns are matched against filenames only, not full paths
29 * - Example: ASSET_PRELOAD_INCLUDE_PATTERNS="*.js,*.css,*.woff2"
30 *
31 * ASSET_PRELOAD_EXCLUDE_PATTERNS (string)
32 * - Comma-separated list of glob patterns for files to exclude
33 * - Applied after include patterns
34 * - Patterns are matched against filenames only, not full paths
35 * - Example: ASSET_PRELOAD_EXCLUDE_PATTERNS="*.map,*.txt"
36 *
37 * ASSET_PRELOAD_VERBOSE_LOGGING (boolean)
38 * - Enable detailed logging of loaded and skipped files
39 * - Default: false
40 * - Set to "true" to enable verbose output
41 *
42 * ASSET_PRELOAD_ENABLE_ETAG (boolean)
43 * - Enable ETag generation for preloaded assets
44 * - Default: true
45 * - Set to "false" to disable ETag support
46 *
47 * ASSET_PRELOAD_ENABLE_GZIP (boolean)
48 * - Enable Gzip compression for eligible assets
49 * - Default: true
50 * - Set to "false" to disable Gzip compression
51 *
52 * ASSET_PRELOAD_GZIP_MIN_SIZE (number)
53 * - Minimum file size in bytes required for Gzip compression
54 * - Files smaller than this will not be compressed
55 * - Default: 1024 (1KB)
56 *
57 * ASSET_PRELOAD_GZIP_MIME_TYPES (string)
58 * - Comma-separated list of MIME types eligible for Gzip compression
59 * - Supports partial matching for types ending with "/"
60 * - Default: text/,application/javascript,application/json,application/xml,image/svg+xml
61 *
62 * Usage:
63 * bun run server.ts
64 */
65​
66import path from 'node:path'
67​
68// Configuration
69const SERVER_PORT = Number(process.env.PORT ?? 3000)
70const CLIENT_DIRECTORY = './dist/client'
71const SERVER_ENTRY_POINT = './dist/server/server.js'
72​
73// Logging utilities for professional output
74const log = {
75 info: (message: string) => {
76 console.log(`[INFO] ${message}`)
77 },
78 success: (message: string) => {
79 console.log(`[SUCCESS] ${message}`)
80 },
81 warning: (message: string) => {
82 console.log(`[WARNING] ${message}`)
83 },
84 error: (message: string) => {
85 console.log(`[ERROR] ${message}`)
86 },
87 header: (message: string) => {
88 console.log(`\n${message}\n`)
89 },
91​
92// Preloading configuration from environment variables
93const MAX_PRELOAD_BYTES = Number(
94 process.env.ASSET_PRELOAD_MAX_SIZE ?? 5 * 1024 * 1024, // 5MB default
96​
97// Parse comma-separated include patterns (no defaults)
98const INCLUDE_PATTERNS = (process.env.ASSET_PRELOAD_INCLUDE_PATTERNS ?? '')
99 .split(',')
100 .map((s) => s.trim())
101 .filter(Boolean)
102 .map((pattern: string) => convertGlobToRegExp(pattern))
103​
104// Parse comma-separated exclude patterns (no defaults)
105const EXCLUDE_PATTERNS = (process.env.ASSET_PRELOAD_EXCLUDE_PATTERNS ?? '')
106 .split(',')
107 .map((s) => s.trim())
108 .filter(Boolean)
109 .map((pattern: string) => convertGlobToRegExp(pattern))
110​
111// Verbose logging flag
112const VERBOSE = process.env.ASSET_PRELOAD_VERBOSE_LOGGING === 'true'
113​
114// Optional ETag feature
115const ENABLE_ETAG = (process.env.ASSET_PRELOAD_ENABLE_ETAG ?? 'true') === 'true'
116​
117// Optional Gzip feature
118const ENABLE_GZIP = (process.env.ASSET_PRELOAD_ENABLE_GZIP ?? 'true') === 'true'
119const GZIP_MIN_BYTES = Number(process.env.ASSET_PRELOAD_GZIP_MIN_SIZE ?? 1024) // 1KB
120const GZIP_TYPES = (
121 process.env.ASSET_PRELOAD_GZIP_MIME_TYPES ??
122 'text/,application/javascript,application/json,application/xml,image/svg+xml'
124 .split(',')
125 .map((v) => v.trim())
126 .filter(Boolean)
127​
128/**
129 * Convert a simple glob pattern to a regular expression
130 * Supports * wildcard for matching any characters
131 */
132function convertGlobToRegExp(globPattern: string): RegExp {
133 // Escape regex special chars except *, then replace * with .*
134 const escapedPattern = globPattern
135 .replace(/[-/\\^$+?.()|[\]{}]/g, '\\$&')
136 .replace(/\*/g, '.*')
137 return new RegExp(`^${escapedPattern}$`, 'i')
139​
140/**
141 * Compute ETag for a given data buffer
142 */
143function computeEtag(data: Uint8Array): string {
144 const hash = Bun.hash(data)
145 return `W/"${hash.toString(16)}-${data.byteLength.toString()}"`
147​
148/**
149 * Metadata for preloaded static assets
150 */
151interface AssetMetadata {
152 route: string
153 size: number
154 type: string
156​
157/**
158 * In-memory asset with ETag and Gzip support
159 */
160interface InMemoryAsset {
161 raw: Uint8Array
162 gz?: Uint8Array
163 etag?: string
164 type: string
165 immutable: boolean
166 size: number
168​
169/**
170 * Result of static asset preloading process
171 */
172interface PreloadResult {
173 routes: Record<string, (req: Request) => Response | Promise<Response>>
174 loaded: AssetMetadata[]
175 skipped: AssetMetadata[]
177​
178/**
179 * Check if a file is eligible for preloading based on configured patterns
180 */
181function isFileEligibleForPreloading(relativePath: string): boolean {
182 const fileName = relativePath.split(/[/\\]/).pop() ?? relativePath
183​
184 // If include patterns are specified, file must match at least one
185 if (INCLUDE_PATTERNS.length > 0) {
186 if (!INCLUDE_PATTERNS.some((pattern) => pattern.test(fileName))) {
187 return false
188 }
189 }
190​
191 // If exclude patterns are specified, file must not match any
192 if (EXCLUDE_PATTERNS.some((pattern) => pattern.test(fileName))) {
193 return false
194 }
195​
196 return true
198​
199/**
200 * Check if a MIME type is compressible
201 */
202function isMimeTypeCompressible(mimeType: string): boolean {
203 return GZIP_TYPES.some((type) =>
204 type.endsWith('/') ? mimeType.startsWith(type) : mimeType === type,
205 )
207​
208/**
209 * Conditionally compress data based on size and MIME type
210 */
211function compressDataIfAppropriate(
212 data: Uint8Array,
213 mimeType: string,
214): Uint8Array | undefined {
215 if (!ENABLE_GZIP) return undefined
216 if (data.byteLength < GZIP_MIN_BYTES) return undefined
217 if (!isMimeTypeCompressible(mimeType)) return undefined
218 try {
219 return Bun.gzipSync(data.buffer as ArrayBuffer)
220 } catch {
221 return undefined
222 }
224​
225/**
226 * Create response handler function with ETag and Gzip support
227 */
228function createResponseHandler(
229 asset: InMemoryAsset,
230): (req: Request) => Response {
231 return (req: Request) => {
232 const headers: Record<string, string> = {
233 'Content-Type': asset.type,
234 'Cache-Control': asset.immutable
235 ? 'public, max-age=31536000, immutable'
236 : 'public, max-age=3600',
237 }
238​
239 if (ENABLE_ETAG && asset.etag) {
240 const ifNone = req.headers.get('if-none-match')
241 if (ifNone && ifNone === asset.etag) {
242 return new Response(null, {
243 status: 304,
244 headers: { ETag: asset.etag },
245 })
246 }
247 headers.ETag = asset.etag
248 }
249​
250 if (
251 ENABLE_GZIP &&
252 asset.gz &&
253 req.headers.get('accept-encoding')?.includes('gzip')
254 ) {
255 headers['Content-Encoding'] = 'gzip'
256 headers['Content-Length'] = String(asset.gz.byteLength)
257 const gzCopy = new Uint8Array(asset.gz)
258 return new Response(gzCopy, { status: 200, headers })
259 }
260​
261 headers['Content-Length'] = String(asset.raw.byteLength)
262 const rawCopy = new Uint8Array(asset.raw)
263 return new Response(rawCopy, { status: 200, headers })
264 }
266​
267/**
268 * Create composite glob pattern from include patterns
269 */
270function createCompositeGlobPattern(): Bun.Glob {
271 const raw = (process.env.ASSET_PRELOAD_INCLUDE_PATTERNS ?? '')
272 .split(',')
273 .map((s) => s.trim())
274 .filter(Boolean)
275 if (raw.length === 0) return new Bun.Glob('**/*')
276 if (raw.length === 1) return new Bun.Glob(raw[0])
277 return new Bun.Glob(`{${raw.join(',')}}`)
279​
280/**
281 * Initialize static routes with intelligent preloading strategy
282 * Small files are loaded into memory, large files are served on-demand
283 */
284async function initializeStaticRoutes(
285 clientDirectory: string,
286): Promise<PreloadResult> {
287 const routes: Record<string, (req: Request) => Response | Promise<Response>> =
288 {}
289 const loaded: AssetMetadata[] = []
290 const skipped: AssetMetadata[] = []
291​
292 log.info(`Loading static assets from ${clientDirectory}...`)
293 if (VERBOSE) {
294 console.log(
295 `Max preload size: ${(MAX_PRELOAD_BYTES / 1024 / 1024).toFixed(2)} MB`,
296 )
297 if (INCLUDE_PATTERNS.length > 0) {
298 console.log(
299 `Include patterns: ${process.env.ASSET_PRELOAD_INCLUDE_PATTERNS ?? ''}`,
300 )
301 }
302 if (EXCLUDE_PATTERNS.length > 0) {
303 console.log(
304 `Exclude patterns: ${process.env.ASSET_PRELOAD_EXCLUDE_PATTERNS ?? ''}`,
305 )
306 }
307 }
308​
309 let totalPreloadedBytes = 0
310​
311 try {
312 const glob = createCompositeGlobPattern()
313 for await (const relativePath of glob.scan({ cwd: clientDirectory })) {
314 const filepath = path.join(clientDirectory, relativePath)
315 const route = `/${relativePath.split(path.sep).join(path.posix.sep)}`
316​
317 try {
318 // Get file metadata
319 const file = Bun.file(filepath)
320​
321 // Skip if file doesn't exist or is empty
322 if (!(await file.exists()) || file.size === 0) {
323 continue
324 }
325​
326 const metadata: AssetMetadata = {
327 route,
328 size: file.size,
329 type: file.type || 'application/octet-stream',
330 }
331​
332 // Determine if file should be preloaded
333 const matchesPattern = isFileEligibleForPreloading(relativePath)
334 const withinSizeLimit = file.size <= MAX_PRELOAD_BYTES
335​
336 if (matchesPattern && withinSizeLimit) {
337 // Preload small files into memory with ETag and Gzip support
338 const bytes = new Uint8Array(await file.arrayBuffer())
339 const gz = compressDataIfAppropriate(bytes, metadata.type)
340 const etag = ENABLE_ETAG ? computeEtag(bytes) : undefined
341 const asset: InMemoryAsset = {
342 raw: bytes,
343 gz,
344 etag,
345 type: metadata.type,
346 immutable: true,
347 size: bytes.byteLength,
348 }
349 routes[route] = createResponseHandler(asset)
350​
351 loaded.push({ ...metadata, size: bytes.byteLength })
352 totalPreloadedBytes += bytes.byteLength
353 } else {
354 // Serve large or filtered files on-demand
355 routes[route] = () => {
356 const fileOnDemand = Bun.file(filepath)
357 return new Response(fileOnDemand, {
358 headers: {
359 'Content-Type': metadata.type,
360 'Cache-Control': 'public, max-age=3600',
361 },
362 })
363 }
364​
365 skipped.push(metadata)
366 }
367 } catch (error: unknown) {
368 if (error instanceof Error && error.name !== 'EISDIR') {
369 log.error(`Failed to load ${filepath}: ${error.message}`)
370 }
371 }
372 }
373​
374 // Show detailed file overview only when verbose mode is enabled
375 if (VERBOSE && (loaded.length > 0 || skipped.length > 0)) {
376 const allFiles = [...loaded, ...skipped].sort((a, b) =>
377 a.route.localeCompare(b.route),
378 )
379​
380 // Calculate max path length for alignment
381 const maxPathLength = Math.min(
382 Math.max(...allFiles.map((f) => f.route.length)),
383 60,
384 )
385​
386 // Format file size with KB and actual gzip size
387 const formatFileSize = (bytes: number, gzBytes?: number) => {
388 const kb = bytes / 1024
389 const sizeStr = kb < 100 ? kb.toFixed(2) : kb.toFixed(1)
390​
391 if (gzBytes !== undefined) {
392 const gzKb = gzBytes / 1024
393 const gzStr = gzKb < 100 ? gzKb.toFixed(2) : gzKb.toFixed(1)
394 return {
395 size: sizeStr,
396 gzip: gzStr,
397 }
398 }
399​
400 // Rough gzip estimation (typically 30-70% compression) if no actual gzip data
401 const gzipKb = kb * 0.35
402 return {
403 size: sizeStr,
404 gzip: gzipKb < 100 ? gzipKb.toFixed(2) : gzipKb.toFixed(1),
405 }
406 }
407​
408 if (loaded.length > 0) {
409 console.log('\nπŸ“ Preloaded into memory:')
410 console.log(
411 'Path β”‚ Size β”‚ Gzip Size',
412 )
413 loaded
414 .sort((a, b) => a.route.localeCompare(b.route))
415 .forEach((file) => {
416 const { size, gzip } = formatFileSize(file.size)
417 const paddedPath = file.route.padEnd(maxPathLength)
418 const sizeStr = `${size.padStart(7)} kB`
419 const gzipStr = `${gzip.padStart(7)} kB`
420 console.log(`${paddedPath} β”‚ ${sizeStr} β”‚ ${gzipStr}`)
421 })
422 }
423​
424 if (skipped.length > 0) {
425 console.log('\nπŸ’Ύ Served on-demand:')
426 console.log(
427 'Path β”‚ Size β”‚ Gzip Size',
428 )
429 skipped
430 .sort((a, b) => a.route.localeCompare(b.route))
431 .forEach((file) => {
432 const { size, gzip } = formatFileSize(file.size)
433 const paddedPath = file.route.padEnd(maxPathLength)
434 const sizeStr = `${size.padStart(7)} kB`
435 const gzipStr = `${gzip.padStart(7)} kB`
436 console.log(`${paddedPath} β”‚ ${sizeStr} β”‚ ${gzipStr}`)
437 })
438 }
439 }
440​
441 // Show detailed verbose info if enabled
442 if (VERBOSE) {
443 if (loaded.length > 0 || skipped.length > 0) {
444 const allFiles = [...loaded, ...skipped].sort((a, b) =>
445 a.route.localeCompare(b.route),
446 )
447 console.log('\nπŸ“Š Detailed file information:')
448 console.log(
449 'Status β”‚ Path β”‚ MIME Type β”‚ Reason',
450 )
451 allFiles.forEach((file) => {
452 const isPreloaded = loaded.includes(file)
453 const status = isPreloaded ? 'MEMORY' : 'ON-DEMAND'
454 const reason =
455 !isPreloaded && file.size > MAX_PRELOAD_BYTES
456 ? 'too large'
457 : !isPreloaded
458 ? 'filtered'
459 : 'preloaded'
460 const route =
461 file.route.length > 30
462 ? file.route.substring(0, 27) + '...'
463 : file.route
464 console.log(
465 `${status.padEnd(12)} β”‚ ${route.padEnd(30)} β”‚ ${file.type.padEnd(28)} β”‚ ${reason.padEnd(10)}`,
466 )
467 })
468 } else {
469 console.log('\nπŸ“Š No files found to display')
470 }
471 }
472​
473 // Log summary after the file list
474 console.log() // Empty line for separation
475 if (loaded.length > 0) {
476 log.success(
477 `Preloaded ${String(loaded.length)} files (${(totalPreloadedBytes / 1024 / 1024).toFixed(2)} MB) into memory`,
478 )
479 } else {
480 log.info('No files preloaded into memory')
481 }
482​
483 if (skipped.length > 0) {
484 const tooLarge = skipped.filter((f) => f.size > MAX_PRELOAD_BYTES).length
485 const filtered = skipped.length - tooLarge
486 log.info(
487 `${String(skipped.length)} files will be served on-demand (${String(tooLarge)} too large, ${String(filtered)} filtered)`,
488 )
489 }
490 } catch (error) {
491 log.error(
492 `Failed to load static files from ${clientDirectory}: ${String(error)}`,
493 )
494 }
495​
496 return { routes, loaded, skipped }
498​
499/**
500 * Initialize the server
501 */
502async function initializeServer() {
503 log.header('Starting Production Server')
504​
505 // Load TanStack Start server handler
506 let handler: { fetch: (request: Request) => Response | Promise<Response> }
507 try {
508 const serverModule = (await import(SERVER_ENTRY_POINT)) as {
509 default: { fetch: (request: Request) => Response | Promise<Response> }
510 }
511 handler = serverModule.default
512 log.success('TanStack Start application handler initialized')
513 } catch (error) {
514 log.error(`Failed to load server handler: ${String(error)}`)
515 process.exit(1)
516 }
517​
518 // Build static routes with intelligent preloading
519 const { routes } = await initializeStaticRoutes(CLIENT_DIRECTORY)
520​
521 // Create Bun server
522 const server = Bun.serve({
523 port: SERVER_PORT,
524​
525 routes: {
526 // Serve static assets (preloaded or on-demand)
527 ...routes,
528​
529 // Fallback to TanStack Start handler for all other routes
530 '/*': (req: Request) => {
531 try {
532 return handler.fetch(req)
533 } catch (error) {
534 log.error(`Server handler error: ${String(error)}`)
535 return new Response('Internal Server Error', { status: 500 })
536 }
537 },
538 },
539​
540 // Global error handler
541 error(error) {
542 log.error(
543 `Uncaught server error: ${error instanceof Error ? error.message : String(error)}`,
544 )
545 return new Response('Internal Server Error', { status: 500 })
546 },
547 })
548​
549 log.success(`Server listening on http://localhost:${String(server.port)}`)
551​
552// Initialize the server
553initializeServer().catch((error: unknown) => {
554 log.error(`Failed to start server: ${String(error)}`)
555 process.exit(1)
556})