npm-tanstack--react-start

1
# TanStack React Start
2

3
TanStack React Start is a full-stack React framework that provides SSR (Server-Side Rendering), streaming, server functions, API routes, and bundling capabilities. Built on top of TanStack Router and Vite, it offers type-safe routing with built-in caching and URL state management for modern React applications with seamless deployment to various hosting providers.
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
- **Peer Dependencies**: React 18+/19+, Vite 6+, @vitejs/plugin-react 4.3.4+
12

13
## Core Imports
14

15
**Client-side (default import)**:
16
```typescript
17
import { StartClient, useServerFn, createServerFn } from "@tanstack/react-start";
18
```
19

20
**Explicit client import**:
21
```typescript
22
import { StartClient, useServerFn, createServerFn } from "@tanstack/react-start/client";
23
```
24

25
**Server-side**:
26
```typescript
27
import { StartServer, defaultStreamHandler, createStartHandler } from "@tanstack/react-start/server";
28
```
29

30
**Vite plugin**:
31
```typescript
32
import { TanStackStartVitePlugin } from "@tanstack/react-start/plugin/vite";
33
```
34

35
**Server functions**:
36
```typescript
37
// Client-side server function calls
38
import { createClientRpc } from "@tanstack/react-start/server-functions-client";
39

40
// Server-side server function handlers
41
import { createServerRpc } from "@tanstack/react-start/server-functions-server";
42
```
43

44
## Basic Usage
45

46
### Client Application Setup
47

48
```typescript
49
import { StrictMode, startTransition } from 'react';
50
import { hydrateRoot } from 'react-dom/client';
51
import { StartClient } from '@tanstack/react-start';
52
import { createRouter } from './router'; // Your router configuration
53

54
const router = createRouter();
55

56
startTransition(() => {
57
  hydrateRoot(
58
    document,
59
    <StrictMode>
60
      <StartClient router={router} />
61
    </StrictMode>
62
  );
63
});
64
```
65

66
### Server Application Setup
67

68
```typescript
69
import { createStartHandler, defaultStreamHandler } from '@tanstack/react-start/server';
70
import { createRouter } from './router'; // Your router configuration
71

72
export default createStartHandler({
73
  createRouter,
74
})(defaultStreamHandler);
75
```
76

77
### Vite Configuration
78

79
```typescript
80
import { defineConfig } from 'vite';
81
import { TanStackStartVitePlugin } from '@tanstack/react-start/plugin/vite';
82

83
export default defineConfig({
84
  plugins: [
85
    TanStackStartVitePlugin({
86
      // Configuration options
87
    }),
88
  ],
89
});
90
```
91

92
### Server Functions
93

94
```typescript
95
import { createServerFn } from '@tanstack/react-start';
96
import { useServerFn } from '@tanstack/react-start';
97

98
// Define a server function
99
const getUser = createServerFn().handler(async (userId: string) => {
100
  // This runs on the server
101
  return await fetchUserFromDatabase(userId);
102
});
103

104
// Use in a React component
105
function UserProfile({ userId }: { userId: string }) {
106
  const serverFn = useServerFn(getUser);
107
  
108
  const handleClick = async () => {
109
    const user = await serverFn(userId);
110
    console.log(user);
111
  };
112
  
113
  return <button onClick={handleClick}>Load User</button>;
114
}
115
```
116

117
## Architecture
118

119
TanStack React Start is built around several key architectural patterns:
120

121
- **Full-Stack Type Safety**: Complete TypeScript integration from client to server with shared type definitions
122
- **Server Functions**: Type-safe RPC-style communication between client and server code
123
- **SSR/Streaming**: Built-in server-side rendering with streaming support for optimal performance
124
- **File-Based Routing**: Leverages TanStack Router's file-based routing with server-side route support
125
- **Vite Integration**: Deep integration with Vite for modern development experience and optimized builds
126
- **Middleware System**: Comprehensive middleware support for server functions with validation and context passing
127
- **Serialization**: Custom serialization system for complex data types between client and server
128

129
## Capabilities
130

131
### Client-Side Framework
132

133
Core client-side functionality including the main application component, React hooks for server function integration, and client-side utilities for full-stack applications.
134

135
```typescript { .api }
136
function StartClient(props: { router: AnyRouter }): JSX.Element;
137

138
function useServerFn<T extends (...deps: Array<any>) => Promise<any>>(
139
  serverFn: T
140
): (...args: Parameters<T>) => ReturnType<T>;
141
```
142

143
[Client-Side Framework](./client.md)
144

145
### Server-Side Rendering
146

147
Server-side rendering components, streaming handlers, and utilities for processing requests and generating responses with full React Server Components support.
148

149
```typescript { .api }
150
function StartServer<TRouter extends AnyRouter>(props: {
151
  router: TRouter
152
}): JSX.Element;
153

154
function createStartHandler(options: {
155
  createRouter: () => AnyRouter;
156
}): (handler: HandlerCallback) => HandlerCallback;
157

158
const defaultStreamHandler: HandlerCallback;
159
const defaultRenderHandler: HandlerCallback;
160
```
161

162
[Server-Side Rendering](./server.md)
163

164
### Server Functions
165

166
Type-safe server function system enabling seamless communication between client and server code with middleware support, validation, and automatic serialization.
167

168
```typescript { .api }
169
function createServerFn<TValidator = undefined, TMiddleware = []>(
170
  options?: ServerFnBaseOptions<TValidator, TMiddleware>
171
): ServerFnBuilder<TValidator, TMiddleware>;
172

173
function createIsomorphicFn<TArgs extends Array<any>, TReturn>(
174
  clientFn: (...args: TArgs) => TReturn,
175
  serverFn: (...args: TArgs) => TReturn
176
): IsomorphicFn<TArgs, TReturn>;
177

178
function createMiddleware<TOptions extends FunctionMiddlewareOptions>(
179
  options: TOptions
180
): FunctionMiddlewareWithTypes<TOptions>;
181
```
182

183
[Server Functions](./server-functions.md)
184

185
### Vite Build Integration
186

187
Vite plugin for seamless integration with the Vite build system, providing automatic code splitting, server-side entry generation, and development server configuration.
188

189
```typescript { .api }
190
function TanStackStartVitePlugin(
191
  opts?: TanStackStartInputConfig & WithReactPlugin
192
): Array<PluginOption>;
193

194
interface TanStackStartInputConfig {
195
  react?: ViteReactOptions;
196
  customViteReactPlugin?: boolean;
197
}
198
```
199

200
[Vite Build Integration](./vite-plugin.md)
201

202
## Core Types
203

204
```typescript { .api }
205
interface AnyRouter {
206
  state: {
207
    matches: Array<any>;
208
    location: any;
209
  };
210
  navigate: (options: any) => Promise<any>;
211
  resolveRedirect: (redirect: any) => { options: any };
212
}
213

214
interface HandlerCallback {
215
  (context: {
216
    request: Request;
217
    router: AnyRouter;
218
    responseHeaders: Headers;
219
  }): Response | Promise<Response>;
220
}
221

222
interface ServerFnBaseOptions<TValidator, TMiddleware> {
223
  method?: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
224
  validator?: TValidator;
225
  middleware?: TMiddleware;
226
}
227

228
interface IsomorphicFn<TArgs extends Array<any>, TReturn> {
229
  (...args: TArgs): TReturn;
230
}
231

232
type PluginOption = {
233
  name: string;
234
  configEnvironment?: () => any;
235
  [key: string]: any;
236
};
237
```