npm-tanstack--react-start

1
# Server Utilities
2

3
Server-side utilities for handling requests, creating handlers, and managing server operations within TanStack Start applications.
4

5
## Capabilities
6

7
### Request Handler Creation
8

9
Create and configure request handlers for server-side operations.
10

11
```typescript { .api }
12
/**
13
 * Creates a start handler for server-side request processing
14
 * @param options - Configuration options for the handler
15
 * @returns Request handler function
16
 */
17
function createStartHandler(
18
  options?: { streamHandler?: StreamHandler }
19
): RequestHandler<Register>;
20

21
/**
22
 * Handle server actions and provide proper error handling
23
 * @param action - The server action to handle
24
 * @returns Promise resolving to action result
25
 */
26
function handleServerAction<T>(action: T): Promise<T>;
27

28
/**
29
 * Create a request handler with custom logic
30
 * @param handler - Function to handle the request
31
 * @returns Request handler with proper typing
32
 */
33
function requestHandler<TRegister>(
34
  handler: (request: Request) => Response | Promise<Response>
35
): RequestHandler<TRegister>;
36
```
37

38
**Usage Examples:**
39

40
```typescript
41
import { createStartHandler, requestHandler } from "@tanstack/react-start/server";
42

43
// Basic start handler
44
const handler = createStartHandler();
45

46
// Custom request handler
47
const apiHandler = requestHandler(async (request) => {
48
  if (request.url.includes("/api/")) {
49
    return new Response(JSON.stringify({ message: "API endpoint" }), {
50
      headers: { "Content-Type": "application/json" }
51
    });
52
  }
53
  return new Response("Not found", { status: 404 });
54
});
55

56
// Handler with custom stream handler
57
const streamHandler = createStartHandler({
58
  streamHandler: (readable) => {
59
    // Custom streaming logic
60
    return readable;
61
  }
62
});
63
```
64

65
### Request Context Access
66

67
Access request information and context within server functions.
68

69
```typescript { .api }
70
/**
71
 * Get the current request object
72
 * @returns Current HTTP request
73
 */
74
function getRequest(): Request;
75

76
/**
77
 * Get all request headers as an object
78
 * @returns Object containing all request headers
79
 */
80
function getRequestHeaders(): Record<string, string>;
81

82
/**
83
 * Get a specific request header by name
84
 * @param name - Header name to retrieve
85
 * @returns Header value or undefined
86
 */
87
function getRequestHeader(name: string): string | undefined;
88

89
/**
90
 * Get the client IP address from the request
91
 * @param options - Options for IP detection
92
 * @returns Client IP address or undefined
93
 */
94
function getRequestIP(options?: { ipHeader?: string }): string | undefined;
95
```
96

97
**Usage Examples:**
98

99
```typescript
100
import {
101
  getRequest,
102
  getRequestHeaders,
103
  getRequestHeader,
104
  getRequestIP
105
} from "@tanstack/react-start";
106

107
// Access request information in a server function
108
const getUserInfo = createServerFn()
109
  .handler(async () => {
110
    const request = getRequest();
111
    const headers = getRequestHeaders();
112
    const userAgent = getRequestHeader("user-agent");
113
    const clientIP = getRequestIP();
114

115
    return {
116
      method: request.method,
117
      url: request.url,
118
      userAgent,
119
      clientIP,
120
      headers
121
    };
122
  });
123
```
124

125
### Response Utilities
126

127
Utilities for creating and manipulating HTTP responses.
128

129
```typescript { .api }
130
/**
131
 * Create a JSON response with proper headers
132
 * @param data - Data to serialize as JSON
133
 * @param options - Response options
134
 * @returns JSON response object
135
 */
136
function json<T>(
137
  data: T,
138
  options?: { status?: number; headers?: HeadersInit }
139
): JsonResponse;
140

141
/**
142
 * Merge multiple header objects into one
143
 * @param headers - Header objects to merge
144
 * @returns Merged headers object
145
 */
146
function mergeHeaders(...headers: HeadersInit[]): Headers;
147
```
148

149
**Usage Examples:**
150

151
```typescript
152
import { json, mergeHeaders } from "@tanstack/react-start";
153

154
// Create JSON responses
155
const getUsers = createServerFn()
156
  .handler(async () => {
157
    const users = await db.user.findMany();
158

159
    return json(users, {
160
      status: 200,
161
      headers: { "Cache-Control": "max-age=300" }
162
    });
163
  });
164

165
// Merge headers from multiple sources
166
const createUser = createServerFn()
167
  .handler(async (userData) => {
168
    const user = await db.user.create({ data: userData });
169

170
    const responseHeaders = mergeHeaders(
171
      { "Content-Type": "application/json" },
172
      { "X-User-ID": user.id },
173
      { "Cache-Control": "no-cache" }
174
    );
175

176
    return json(user, { headers: responseHeaders });
177
  });
178
```
179

180
### Router Server-Side Utilities
181

182
Server-side utilities specific to TanStack Router integration.
183

184
```typescript { .api }
185
/**
186
 * Attach router server-side SSR utilities
187
 * @param router - Router instance to enhance
188
 * @returns Enhanced router with SSR utilities
189
 */
190
function attachRouterServerSsrUtils<T>(router: T): T;
191

192
/**
193
 * Transform readable stream with router context
194
 * @param stream - Readable stream to transform
195
 * @param router - Router instance
196
 * @returns Transformed stream
197
 */
198
function transformReadableStreamWithRouter<T>(
199
  stream: ReadableStream<T>,
200
  router: any
201
): ReadableStream<T>;
202

203
/**
204
 * Transform pipeable stream with router context
205
 * @param stream - Pipeable stream to transform
206
 * @param router - Router instance
207
 * @returns Transformed stream
208
 */
209
function transformPipeableStreamWithRouter<T>(
210
  stream: T,
211
  router: any
212
): T;
213
```
214

215
### Server Context Management
216

217
Functions for managing server execution context.
218

219
```typescript { .api }
220
/**
221
 * Get the global Start context
222
 * @returns Global Start context object
223
 */
224
function getGlobalStartContext(): StartContext;
225

226
/**
227
 * Get the current router instance
228
 * @returns Router instance
229
 */
230
function getRouterInstance(): AnyRouter;
231
```
232

233
## Types
234

235
```typescript { .api }
236
// Request handler types
237
interface RequestHandler<TRegister> {
238
  (request: Request): Promise<Response> | Response;
239
}
240

241
interface RequestOptions {
242
  onError?: (error: Error) => Response | Promise<Response>;
243
  onRequest?: (request: Request) => Request | Promise<Request>;
244
  onResponse?: (response: Response) => Response | Promise<Response>;
245
}
246

247
// Stream handler types
248
interface StreamHandler {
249
  (readable: ReadableStream): ReadableStream;
250
}
251

252
// JSON response type
253
interface JsonResponse {
254
  json(): any;
255
  status: number;
256
  headers: Headers;
257
  ok: boolean;
258
  statusText: string;
259
}
260

261
// Start context type
262
interface StartContext {
263
  request: Request;
264
  response?: Response;
265
  [key: string]: any;
266
}
267

268
// Router types
269
interface AnyRouter {
270
  // Router implementation from TanStack Router
271
}
272

273
// Registration interface
274
interface Register {
275
  // Extend this for custom type registration
276
}
277
```
278

279
## Constants
280

281
```typescript { .api }
282
// HTTP headers constants
283
const HEADERS: {
284
  readonly CONTENT_TYPE: string;
285
  readonly CACHE_CONTROL: string;
286
  readonly X_TSS_SERIALIZED: string;
287
};
288
```