npm-tanstack--react-start

1
# Server-Side Rendering
2

3
Server-side rendering components, streaming handlers, request processing utilities, and server route creation for TanStack React Start applications with full SSR support and React Server Components integration.
4

5
## Capabilities
6

7
### StartServer Component
8

9
Main server-side application component that renders the React application on the server.
10

11
```typescript { .api }
12
/**
13
 * Main server-side application component for TanStack Start
14
 * Renders the React application with router provider on the server
15
 * @param props - Component props containing the router instance
16
 * @returns JSX element with router provider for server rendering
17
 */
18
function StartServer<TRouter extends AnyRouter>(props: {
19
  router: TRouter
20
}): JSX.Element;
21
```
22

23
**Usage Example:**
24

25
```typescript
26
import { StartServer } from '@tanstack/react-start/server';
27
import { createRouter } from './router';
28

29
function serverEntry({ request }: { request: Request }) {
30
  const router = createRouter();
31
  return <StartServer router={router} />;
32
}
33
```
34

35
### Request Handler Creation
36

37
Core functionality for creating request handlers that process incoming HTTP requests.
38

39
```typescript { .api }
40
/**
41
 * Creates a Start request handler for processing HTTP requests
42
 * @param options - Configuration options including router factory
43
 * @returns Function that accepts a handler callback and returns configured handler
44
 */
45
function createStartHandler(options: {
46
  createRouter: () => AnyRouter;
47
}): (handler: HandlerCallback) => HandlerCallback;
48

49
interface CustomizeStartHandler {
50
  (handler: HandlerCallback): HandlerCallback;
51
}
52

53
interface HandlerCallback {
54
  (context: {
55
    request: Request;
56
    router: AnyRouter;
57
    responseHeaders: Headers;
58
  }): Response | Promise<Response>;
59
}
60
```
61

62
**Usage Example:**
63

64
```typescript
65
import { createStartHandler, defaultStreamHandler } from '@tanstack/react-start/server';
66
import { createRouter } from './router';
67

68
// Create the main request handler
69
export default createStartHandler({
70
  createRouter,
71
})(defaultStreamHandler);
72
```
73

74
### Default Handlers
75

76
Pre-configured handlers for common server-side rendering scenarios.
77

78
```typescript { .api }
79
/**
80
 * Default streaming handler for server-side rendering with streaming support
81
 * Renders the application as a stream for optimal performance
82
 */
83
const defaultStreamHandler: HandlerCallback;
84

85
/**
86
 * Default render handler for server-side rendering to string
87
 * Renders the application to a complete HTML string
88
 */
89
const defaultRenderHandler: HandlerCallback;
90
```
91

92
**Usage Examples:**
93

94
```typescript
95
import { 
96
  createStartHandler, 
97
  defaultStreamHandler, 
98
  defaultRenderHandler 
99
} from '@tanstack/react-start/server';
100

101
// Using streaming handler (recommended)
102
const streamHandler = createStartHandler({ createRouter })(defaultStreamHandler);
103

104
// Using string rendering handler
105
const stringHandler = createStartHandler({ createRouter })(defaultRenderHandler);
106
```
107

108
### Router SSR Utilities
109

110
Utilities for server-side rendering integration with TanStack Router.
111

112
```typescript { .api }
113
/**
114
 * Attaches server-side rendering utilities to a router instance
115
 * @param router - Router instance to enhance with SSR capabilities
116
 */
117
function attachRouterServerSsrUtils(router: AnyRouter): void;
118

119
/**
120
 * Creates a request handler for processing HTTP requests with router
121
 * @param options - Handler configuration options
122
 * @returns Configured request handler function
123
 */
124
function createRequestHandler(options: {
125
  createRouter: () => AnyRouter;
126
  getRouter?: (request: Request) => AnyRouter;
127
}): (request: Request) => Promise<Response>;
128

129
/**
130
 * Defines a handler callback with proper typing
131
 * @param callback - Handler function to wrap
132
 * @returns Typed handler callback
133
 */
134
function defineHandlerCallback(
135
  callback: HandlerCallback
136
): HandlerCallback;
137

138
/**
139
 * Transforms a ReadableStream with router integration
140
 * @param options - Transformation options
141
 * @returns Transformed stream
142
 */
143
function transformReadableStreamWithRouter(options: {
144
  request: Request;
145
  router: AnyRouter;
146
  responseHeaders: Headers;
147
  children: React.ReactNode;
148
}): ReadableStream;
149

150
/**
151
 * Transforms a pipeable stream with router integration
152
 * @param options - Transformation options
153
 * @returns Transformed pipeable stream
154
 */
155
function transformPipeableStreamWithRouter(options: {
156
  request: Request;
157
  router: AnyRouter;
158
  responseHeaders: Headers;
159
  children: React.ReactNode;
160
}): any; // Pipeable stream type varies by React version
161
```
162

163
### Server Functions Handler
164

165
Handler for processing server function requests.
166

167
```typescript { .api }
168
/**
169
 * Handles server function action requests
170
 * Processes RPC-style calls from client to server functions
171
 * @param request - HTTP request containing server function call
172
 * @returns Response with server function result
173
 */
174
function handleServerAction(request: Request): Promise<Response>;
175
```
176

177
### Server Routes
178

179
Creation and management of server-only routes for API endpoints and server-side logic.
180

181
```typescript { .api }
182
/**
183
 * Creates a server-only route that doesn't render on the client
184
 * @param options - Server route configuration options
185
 * @returns Configured server route
186
 */
187
function createServerRoute<TRouteTypes extends ServerRouteTypes>(
188
  options: ServerRouteOptions<TRouteTypes>
189
): ServerRouteWithTypes<TRouteTypes>;
190

191
/**
192
 * Creates a file-based server route
193
 * @param path - File path for the route
194
 * @returns File-based server route creator function
195
 */
196
function createServerFileRoute<TPath extends string>(
197
  path: TPath
198
): CreateServerFileRoute<TPath>;
199

200
/**
201
 * Creates a server-only root route
202
 * @param options - Root route configuration options
203
 * @returns Configured server root route
204
 */
205
function createServerRootRoute<TRouteTypes extends ServerRouteTypes>(
206
  options?: ServerRouteOptions<TRouteTypes>
207
): ServerRouteWithTypes<TRouteTypes>;
208

209
interface ServerRouteOptions<TRouteTypes extends ServerRouteTypes> {
210
  id?: string;
211
  path?: string;
212
  methods?: ServerRouteMethodsOptions<TRouteTypes>;
213
  middleware?: ServerRouteMiddleware<TRouteTypes>;
214
  afterMiddleware?: ServerRouteAfterMiddleware<TRouteTypes>;
215
}
216

217
interface CreateServerFileRoute<TPath extends string> {
218
  (options?: ServerRouteOptions<any>): ServerFileRoutesByPath[TPath];
219
}
220

221
interface ServerRouteTypes {
222
  params?: Record<string, any>;
223
  search?: Record<string, any>;
224
  context?: Record<string, any>;
225
}
226
```
227

228
**Usage Examples:**
229

230
```typescript
231
import { createServerRoute, createServerFileRoute } from '@tanstack/react-start/server';
232

233
// Create a server route
234
const apiRoute = createServerRoute({
235
  path: '/api/users',
236
  methods: {
237
    GET: async ({ request }) => {
238
      const users = await getUsersFromDatabase();
239
      return Response.json(users);
240
    },
241
    POST: async ({ request }) => {
242
      const userData = await request.json();
243
      const newUser = await createUser(userData);
244
      return Response.json(newUser);
245
    },
246
  },
247
});
248

249
// Create a file-based server route
250
const userRoute = createServerFileRoute('/api/users/$userId')({
251
  methods: {
252
    GET: async ({ params }) => {
253
      const user = await getUserById(params.userId);
254
      return Response.json(user);
255
    },
256
  },
257
});
258
```
259

260
### Server Route Methods
261

262
HTTP method handlers and utilities for server routes.
263

264
```typescript { .api }
265
interface ServerRouteMethods<TRouteTypes extends ServerRouteTypes> {
266
  GET?: ServerRouteMethodHandlerFn<TRouteTypes>;
267
  POST?: ServerRouteMethodHandlerFn<TRouteTypes>;
268
  PUT?: ServerRouteMethodHandlerFn<TRouteTypes>;
269
  PATCH?: ServerRouteMethodHandlerFn<TRouteTypes>;
270
  DELETE?: ServerRouteMethodHandlerFn<TRouteTypes>;
271
  HEAD?: ServerRouteMethodHandlerFn<TRouteTypes>;
272
  OPTIONS?: ServerRouteMethodHandlerFn<TRouteTypes>;
273
}
274

275
interface ServerRouteMethodHandlerFn<TRouteTypes extends ServerRouteTypes> {
276
  (context: ServerRouteMethodHandlerCtx<TRouteTypes>): 
277
    | Response 
278
    | Promise<Response> 
279
    | any 
280
    | Promise<any>;
281
}
282

283
interface ServerRouteMethodHandlerCtx<TRouteTypes extends ServerRouteTypes> {
284
  request: Request;
285
  params: TRouteTypes['params'];
286
  search: TRouteTypes['search'];
287
  context: TRouteTypes['context'];
288
}
289

290
type ServerRouteVerb = 
291
  | 'GET' 
292
  | 'POST' 
293
  | 'PUT' 
294
  | 'PATCH' 
295
  | 'DELETE' 
296
  | 'HEAD' 
297
  | 'OPTIONS';
298
```
299

300
### Server Route Builders
301

302
Fluent API for building server routes with middleware and validation.
303

304
```typescript { .api }
305
interface ServerRouteMethodBuilder<TRouteTypes extends ServerRouteTypes> {
306
  /** Add middleware to the route method */
307
  middleware<TMiddleware>(
308
    middleware: ServerRouteMethodBuilderMiddleware<TRouteTypes, TMiddleware>
309
  ): ServerRouteMethodBuilderWithTypes<TRouteTypes, TMiddleware>;
310
  
311
  /** Add after middleware to the route method */
312
  afterMiddleware<TAfterMiddleware>(
313
    middleware: ServerRouteMethodBuilderAfterMiddleware<TRouteTypes, TAfterMiddleware>
314
  ): ServerRouteMethodBuilderWithTypes<TRouteTypes, TAfterMiddleware>;
315
  
316
  /** Set the handler function for the route method */
317
  handler(
318
    handler: ServerRouteMethodBuilderHandler<TRouteTypes>
319
  ): ServerRouteMethod<TRouteTypes>;
320
}
321

322
interface ServerRouteMethodBuilderWithTypes<TRouteTypes, TMiddleware> 
323
  extends ServerRouteMethodBuilder<TRouteTypes> {
324
  middleware: TMiddleware;
325
}
326

327
interface ServerRouteMethodBuilderHandler<TRouteTypes extends ServerRouteTypes> {
328
  (context: ServerRouteMethodHandlerCtx<TRouteTypes>): 
329
    | Response 
330
    | Promise<Response> 
331
    | any 
332
    | Promise<any>;
333
}
334

335
interface ServerRouteMethodBuilderMiddleware<TRouteTypes, TMiddleware> {
336
  (context: ServerRouteMethodHandlerCtx<TRouteTypes>): TMiddleware | Promise<TMiddleware>;
337
}
338

339
interface ServerRouteMethodBuilderAfterMiddleware<TRouteTypes, TAfterMiddleware> {
340
  (context: ServerRouteMethodHandlerCtx<TRouteTypes>): TAfterMiddleware | Promise<TAfterMiddleware>;
341
}
342
```
343

344
### HTTP Constants
345

346
HTTP header constants and utilities.
347

348
```typescript { .api }
349
/** TanStack Start specific header constants */
350
const HEADERS: {
351
  readonly TSS_SHELL: 'X-TSS_SHELL';
352
};
353
```
354

355
### H3 Integration
356

357
Integration utilities for H3 server framework.
358

359
```typescript { .api }
360
/**
361
 * Converts H3 event to Web Request
362
 * @param event - H3 event object
363
 * @returns Web Request object
364
 */
365
function toWebRequest(event: H3Event): Request;
366

367
/**
368
 * Defines an H3 event handler
369
 * @param handler - Handler function for H3 events
370
 * @returns Configured H3 event handler
371
 */
372
function defineEventHandler<T>(
373
  handler: (event: H3Event) => T | Promise<T>
374
): H3EventHandler<T>;
375

376
interface H3Event {
377
  node: {
378
    req: IncomingMessage;
379
    res: ServerResponse;
380
  };
381
  context: Record<string, any>;
382
  [key: string]: any;
383
}
384

385
interface H3EventHandler<T> {
386
  (event: H3Event): T | Promise<T>;
387
}
388

389
/**
390
 * Runs a function with an H3 event in AsyncLocalStorage context
391
 * @param event - H3 event to store in context
392
 * @param fn - Function to run with the event context
393
 * @returns Promise resolving to the function result
394
 */
395
function runWithEvent<T>(
396
  event: H3Event,
397
  fn: () => T | Promise<T>
398
): Promise<T>;
399

400
/**
401
 * Gets the current H3 event from AsyncLocalStorage context
402
 * @returns Current H3 event
403
 * @throws Error if no event is found in context
404
 */
405
function getEvent(): H3Event;
406
```
407

408
## Core Types
409

410
```typescript { .api }
411
interface AnyRouter {
412
  state: {
413
    matches: Array<any>;
414
    location: any;
415
  };
416
  navigate: (options: any) => Promise<any>;
417
  resolveRedirect: (redirect: any) => { options: any };
418
}
419

420
interface ServerRoute<TRouteTypes extends ServerRouteTypes = ServerRouteTypes> {
421
  id: string;
422
  path: string;
423
  methods: ServerRouteMethods<TRouteTypes>;
424
  middleware?: Array<ServerRouteMiddleware<TRouteTypes>>;
425
  afterMiddleware?: Array<ServerRouteAfterMiddleware<TRouteTypes>>;
426
}
427

428
interface AnyServerRoute extends ServerRoute<any> {}
429

430
interface ServerRouteWithTypes<TRouteTypes extends ServerRouteTypes> 
431
  extends ServerRoute<TRouteTypes> {}
432

433
interface AnyServerRouteWithTypes extends ServerRouteWithTypes<any> {}
434

435
interface ServerRouteManifest {
436
  routes: Record<string, AnyServerRoute>;
437
}
438

439
interface ServerFileRoutesByPath {
440
  [path: string]: AnyServerRoute;
441
}
442

443
interface ServerRouteMiddleware<TRouteTypes extends ServerRouteTypes> {
444
  (context: ServerRouteMethodHandlerCtx<TRouteTypes>): any | Promise<any>;
445
}
446

447
interface ServerRouteAfterMiddleware<TRouteTypes extends ServerRouteTypes> {
448
  (context: ServerRouteMethodHandlerCtx<TRouteTypes>): any | Promise<any>;
449
}
450

451
interface ServerRouteMethodsOptions<TRouteTypes extends ServerRouteTypes> {
452
  [verb in ServerRouteVerb]?: ServerRouteMethodHandlerFn<TRouteTypes>;
453
}
454

455
interface ServerRouteMethodsRecord<TRouteTypes extends ServerRouteTypes> {
456
  [verb in ServerRouteVerb]: ServerRouteMethod<TRouteTypes>;
457
}
458

459
interface ServerRouteMethod<TRouteTypes extends ServerRouteTypes> {
460
  verb: ServerRouteVerb;
461
  handler: ServerRouteMethodHandlerFn<TRouteTypes>;
462
  middleware?: Array<ServerRouteMiddleware<TRouteTypes>>;
463
  afterMiddleware?: Array<ServerRouteAfterMiddleware<TRouteTypes>>;
464
}
465

466
interface ServerRouteAfterMethods<TRouteTypes extends ServerRouteTypes> {
467
  [verb in ServerRouteVerb]: Array<ServerRouteAfterMiddleware<TRouteTypes>>;
468
}
469

470
type ResolveAllServerContext<TRouteTypes extends ServerRouteTypes> = 
471
  TRouteTypes['context'] extends Record<string, any> 
472
    ? TRouteTypes['context'] 
473
    : {};
474

475
type MergeMethodMiddlewares<T1, T2> = T1 & T2;
476

477
type AssignAllMethodContext<TRouteTypes, TContext> = TRouteTypes & {
478
  context: TContext;
479
};
480

481
type AnyRouteMethodsBuilder = ServerRouteMethodBuilder<any>;
482

483
interface ServerRouteMethodBuilderTypes {
484
  params?: Record<string, any>;
485
  search?: Record<string, any>;
486
  context?: Record<string, any>;
487
}
488

489
interface ServerRouteMethodBuilderOptions<TRouteTypes extends ServerRouteTypes> {
490
  middleware?: Array<ServerRouteMethodBuilderMiddleware<TRouteTypes, any>>;
491
  afterMiddleware?: Array<ServerRouteMethodBuilderAfterMiddleware<TRouteTypes, any>>;
492
}
493

494
interface ServerRouteAddFileChildrenFn<TRouteTypes extends ServerRouteTypes> {
495
  (children: Array<AnyServerRoute>): ServerRouteWithTypes<TRouteTypes>;
496
}
497
```