npm-tanstack--react-start

1
# TanStack React Start
2

3
TanStack React Start is a modern full-stack React framework that provides server-side rendering (SSR), streaming, server functions, API routes, and integrated bundling capabilities built on top of TanStack Router and Vite. It enables developers to build scalable React applications with advanced features like type-safe server functions, real-time data streaming, and seamless client-server communication through RPC-style APIs.
4

5
## Package Information
6

7
- **Package Name**: @tanstack/react-start
8
- **Package Type**: npm
9
- **Language**: TypeScript
10
- **Installation**: `npm install @tanstack/react-start`
11

12
## Core Imports
13

14
```typescript
15
import {
16
  useServerFn,
17
  createServerFn,
18
  createIsomorphicFn,
19
  createServerOnlyFn,
20
  createClientOnlyFn,
21
  createMiddleware,
22
  createStart,
23
  hydrate,
24
  json,
25
  mergeHeaders
26
} from "@tanstack/react-start";
27
```
28

29
For entry points:
30
```typescript
31
// Client-side components
32
import { StartClient, hydrateStart } from "@tanstack/react-start/client";
33

34
// Server-side components
35
import { StartServer, defaultStreamHandler, defaultRenderHandler } from "@tanstack/react-start/server";
36

37
// RPC functionality
38
import { createClientRpc } from "@tanstack/react-start/client-rpc";
39
import { createServerRpc } from "@tanstack/react-start/server-rpc";
40

41
// Vite plugin
42
import { tanstackStart } from "@tanstack/react-start/plugin/vite";
43
```
44

45
## Basic Usage
46

47
```typescript
48
// 1. Server function example
49
import { createServerFn } from "@tanstack/react-start";
50

51
const getUser = createServerFn()
52
  .handler(async (id: string) => {
53
    // Server-only code
54
    return await db.user.findUnique({ where: { id } });
55
  });
56

57
// 2. Client usage of server function
58
import { useServerFn } from "@tanstack/react-start";
59

60
function UserProfile({ userId }: { userId: string }) {
61
  const getUserFn = useServerFn(getUser);
62
  const [user, setUser] = useState(null);
63

64
  useEffect(() => {
65
    getUserFn(userId).then(setUser);
66
  }, [userId]);
67

68
  return user ? <div>Hello, {user.name}!</div> : <div>Loading...</div>;
69
}
70

71
// 3. Vite configuration
72
import { defineConfig } from "vite";
73
import { tanstackStart } from "@tanstack/react-start/plugin/vite";
74

75
export default defineConfig({
76
  plugins: [tanstackStart()],
77
});
78
```
79

80
## Architecture
81

82
TanStack React Start is built around several key components:
83

84
- **Server Functions**: Type-safe functions that run on the server but can be called from the client
85
- **Isomorphic Functions**: Functions with different implementations for client and server environments
86
- **Middleware System**: Composable middleware for server function validation, authentication, and processing
87
- **SSR Components**: `StartClient` and `StartServer` for hydration and server-side rendering
88
- **RPC System**: Client-server communication layer with automatic serialization
89
- **Vite Integration**: Seamless development experience with hot module replacement and bundling
90

91
## Capabilities
92

93
### Server Functions
94

95
Create and manage server-side functions with full type safety and automatic serialization. Perfect for database operations, API calls, and server-side business logic.
96

97
```typescript { .api }
98
function createServerFn<TMethod extends Method>(
99
  options?: { method?: TMethod }
100
): ServerFnBuilder<{}, TMethod>;
101

102
interface ServerFnBuilder<TRegister, TMethod extends Method> {
103
  handler<TResponse>(
104
    handler: (...args: any[]) => Promise<TResponse> | TResponse
105
  ): ServerFn<TRegister, TMethod, TResponse>;
106
  middleware<TMiddleware>(
107
    middleware: TMiddleware
108
  ): ServerFnBuilder<TRegister & TMiddleware, TMethod>;
109
  inputValidator<TValidator>(
110
    validator: TValidator
111
  ): ServerFnBuilder<TRegister & { validator: TValidator }, TMethod>;
112
}
113

114
function useServerFn<T extends (...args: any[]) => Promise<any>>(
115
  serverFn: T
116
): (...args: Parameters<T>) => ReturnType<T>;
117
```
118

119
[Server Functions](./server-functions.md)
120

121
### Isomorphic Functions
122

123
Create functions with different implementations for client and server environments, enabling code that adapts to its execution context.
124

125
```typescript { .api }
126
function createIsomorphicFn(): IsomorphicFnBase;
127

128
interface IsomorphicFnBase {
129
  server<TArgs extends Array<any>, TServer>(
130
    serverImpl: (...args: TArgs) => TServer
131
  ): ServerOnlyFn<TArgs, TServer>;
132
  client<TArgs extends Array<any>, TClient>(
133
    clientImpl: (...args: TArgs) => TClient
134
  ): ClientOnlyFn<TArgs, TClient>;
135
}
136

137
function createServerOnlyFn<TArgs extends Array<any>, TServer>(
138
  serverImpl: (...args: TArgs) => TServer
139
): ServerOnlyFn<TArgs, TServer>;
140

141
function createClientOnlyFn<TArgs extends Array<any>, TClient>(
142
  clientImpl: (...args: TArgs) => TClient
143
): ClientOnlyFn<TArgs, TClient>;
144
```
145

146
[Isomorphic Functions](./isomorphic-functions.md)
147

148
### Middleware System
149

150
Build composable middleware for server functions to handle validation, authentication, logging, and other cross-cutting concerns.
151

152
```typescript { .api }
153
function createMiddleware<TType extends MiddlewareType>(
154
  options?: { type?: TType }
155
): CreateMiddlewareResult<{}, TType>;
156

157
interface CreateMiddlewareResult<TRegister, TType> {
158
  middleware<T>(middleware: T): CreateMiddlewareResult<TRegister & T, TType>;
159
  inputValidator<T>(validator: T): CreateMiddlewareResult<TRegister & T, TType>;
160
  client<T>(client: T): CreateMiddlewareResult<TRegister & T, TType>;
161
  server<T>(server: T): CreateMiddlewareResult<TRegister & T, TType>;
162
}
163
```
164

165
[Middleware](./middleware.md)
166

167
### SSR Components
168

169
React components for server-side rendering and client-side hydration with streaming support.
170

171
```typescript { .api }
172
function StartClient(): JSX.Element;
173
function StartServer<TRouter extends AnyRouter>(props: {
174
  router: TRouter;
175
}): JSX.Element;
176

177
function createStartHandler(
178
  streamHandler?: StreamHandler
179
): RequestHandler<Register>;
180

181
function defaultStreamHandler(): StreamHandler;
182
function defaultRenderHandler(): RenderHandler;
183
```
184

185
[SSR Components](./ssr-components.md)
186

187
### RPC System
188

189
Type-safe client-server RPC communication with automatic serialization and request handling.
190

191
```typescript { .api }
192
function createClientRpc(
193
  functionId: string,
194
  fetcher: (...args: any[]) => Promise<any>
195
): ClientRpc;
196

197
function createServerRpc(
198
  functionId: string,
199
  splitImportFn: (...args: any[]) => any
200
): ServerRpc;
201
```
202

203
[RPC System](./rpc-system.md)
204

205
### Core Utilities
206

207
Core utilities for application initialization, hydration, and response handling.
208

209
```typescript { .api }
210
function createStart<TOptions>(
211
  options?: TOptions
212
): StartInstance<TOptions>;
213

214
function hydrate<T>(data: T): Promise<T>;
215

216
function json<T>(
217
  data: T,
218
  options?: { status?: number; headers?: HeadersInit }
219
): JsonResponse;
220

221
function mergeHeaders(...headers: HeadersInit[]): Headers;
222
```
223

224
### Request/Response Utilities
225

226
Utilities for accessing request information and handling server-side operations.
227

228
```typescript { .api }
229
function getRequest(): Request;
230
function getRequestHeaders(): Record<string, string>;
231
function getRequestHeader(name: string): string | undefined;
232
function getRequestIP(options?: { ipHeader?: string }): string | undefined;
233
```
234

235
[Request/Response Utilities](./request-response.md)
236

237
### Server Handler Creation
238

239
Functions for creating request handlers and managing server-side operations.
240

241
```typescript { .api }
242
function createStartHandler(
243
  options?: { streamHandler?: StreamHandler }
244
): RequestHandler<Register>;
245

246
function handleServerAction<T>(action: T): Promise<T>;
247

248
function requestHandler<TRegister>(
249
  handler: (request: Request) => Response | Promise<Response>
250
): RequestHandler<TRegister>;
251
```
252

253
[Server Utilities](./server-utilities.md)
254

255
### Vite Integration
256

257
Vite plugin for seamless integration with TanStack Start, providing automatic configuration and development tools.
258

259
```typescript { .api }
260
function tanstackStart(
261
  options?: TanStackStartInputConfig
262
): Array<PluginOption>;
263

264
interface TanStackStartInputConfig {
265
  framework?: 'react';
266
  defaultEntryPaths?: {
267
    client?: string;
268
    server?: string;
269
    start?: string;
270
  };
271
  // Additional configuration options
272
}
273
```
274

275
[Vite Plugin](./vite-plugin.md)
276

277
## Types
278

279
```typescript { .api }
280
// Core server function types
281
type Method = 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
282

283
interface ServerFn<TRegister, TMethod extends Method, TResponse> {
284
  (...args: any[]): Promise<TResponse>;
285
  url: string;
286
  functionId: string;
287
}
288

289
interface ServerFnBuilder<TRegister, TMethod extends Method> {
290
  handler<TResponse>(
291
    handler: (...args: any[]) => Promise<TResponse> | TResponse
292
  ): ServerFn<TRegister, TMethod, TResponse>;
293
  middleware<TMiddleware>(
294
    middleware: TMiddleware
295
  ): ServerFnBuilder<TRegister & TMiddleware, TMethod>;
296
  inputValidator<TValidator>(
297
    validator: TValidator
298
  ): ServerFnBuilder<TRegister & { validator: TValidator }, TMethod>;
299
}
300

301
// Isomorphic function types
302
interface IsomorphicFn<TArgs extends Array<any>, TServer, TClient> {
303
  (...args: TArgs): TServer | TClient;
304
}
305

306
interface ServerOnlyFn<TArgs extends Array<any>, TServer>
307
  extends IsomorphicFn<TArgs, TServer> {
308
  client<TClient>(
309
    clientImpl: (...args: TArgs) => TClient
310
  ): IsomorphicFn<TArgs, TServer, TClient>;
311
}
312

313
interface ClientOnlyFn<TArgs extends Array<any>, TClient>
314
  extends IsomorphicFn<TArgs, undefined, TClient> {
315
  server<TServer>(
316
    serverImpl: (...args: TArgs) => TServer
317
  ): IsomorphicFn<TArgs, TServer, TClient>;
318
}
319

320
interface IsomorphicFnBase {
321
  server<TArgs extends Array<any>, TServer>(
322
    serverImpl: (...args: TArgs) => TServer
323
  ): ServerOnlyFn<TArgs, TServer>;
324
  client<TArgs extends Array<any>, TClient>(
325
    clientImpl: (...args: TArgs) => TClient
326
  ): ClientOnlyFn<TArgs, TClient>;
327
}
328

329
// Middleware types
330
interface FunctionMiddleware<TRegister = {}, TMethod extends Method = Method> {
331
  // Middleware implementation details
332
}
333

334
interface RequestMiddleware {
335
  // Request middleware implementation
336
}
337

338
type AnyFunctionMiddleware = FunctionMiddleware<any, any>;
339
type AnyRequestMiddleware = RequestMiddleware;
340

341
// Session management types
342
interface SessionManager<T> {
343
  get(): Promise<T | undefined>;
344
  update(updater: (current: T | undefined) => T): Promise<void>;
345
  clear(): Promise<void>;
346
}
347

348
interface SessionOptions {
349
  cookie?: {
350
    domain?: string;
351
    httpOnly?: boolean;
352
    maxAge?: number;
353
    path?: string;
354
    sameSite?: 'strict' | 'lax' | 'none';
355
    secure?: boolean;
356
  };
357
}
358

359
// Cookie management types
360
interface CookieOptions {
361
  domain?: string;
362
  expires?: Date;
363
  httpOnly?: boolean;
364
  maxAge?: number;
365
  path?: string;
366
  sameSite?: 'strict' | 'lax' | 'none';
367
  secure?: boolean;
368
}
369

370
// Request/Response types
371
interface RequestHandler<T> {
372
  (request: Request): Promise<Response>;
373
}
374

375
interface RequestOptions {
376
  onError?: (error: Error) => Response | Promise<Response>;
377
  onRequest?: (request: Request) => Request | Promise<Request>;
378
  onResponse?: (response: Response) => Response | Promise<Response>;
379
}
380

381
// Router types
382
interface AnyRouter {
383
  // Router implementation details from TanStack Router
384
}
385

386
// Response types
387
interface JsonResponse {
388
  json(): any;
389
  status: number;
390
  headers: Headers;
391
}
392

393
interface DehydratedRouter {
394
  // Dehydrated router state
395
}
396

397
// Start instance types
398
interface StartInstance<TSerializationAdapters = any, TDefaultSsr = any, TRequestMiddlewares = any, TFunctionMiddlewares = any> {
399
  getOptions(): StartInstanceOptions<TSerializationAdapters, TDefaultSsr, TRequestMiddlewares, TFunctionMiddlewares>;
400
}
401

402
interface StartInstanceOptions<TSerializationAdapters, TDefaultSsr, TRequestMiddlewares, TFunctionMiddlewares> {
403
  // Start instance configuration options
404
}
405

406
type AnyStartInstance = StartInstance<any, any, any, any>;
407
type AnyStartInstanceOptions = StartInstanceOptions<any, any, any, any>;
408

409
// RPC types
410
interface ClientRpc {
411
  // Client RPC implementation
412
}
413

414
interface ServerRpc {
415
  // Server RPC implementation
416
}
417

418
// Vite plugin types
419
interface TanStackStartInputConfig {
420
  framework?: 'react';
421
  defaultEntryPaths?: {
422
    client?: string;
423
    server?: string;
424
    start?: string;
425
  };
426
  [key: string]: any;
427
}
428

429
interface PluginOption {
430
  name: string;
431
  configResolved?: (config: any) => void;
432
  configureServer?: (server: any) => void;
433
  buildStart?: (options: any) => void;
434
  transform?: (code: string, id: string) => any;
435
}
436

437
// Registration interface for type augmentation
438
interface Register {
439
  // Extend this interface to register custom types
440
}
441
```