npm-tanstack--react-start

1
# Vite Build Integration
2

3
Vite plugin for seamless integration with the Vite build system, providing automatic code splitting, server-side entry generation, client hydration setup, and development server configuration for TanStack React Start applications.
4

5
## Capabilities
6

7
### TanStackStartVitePlugin
8

9
Main Vite plugin that configures the build system for TanStack React Start applications.
10

11
```typescript { .api }
12
/**
13
 * Main Vite plugin for TanStack React Start integration
14
 * Configures Vite for full-stack React applications with SSR support
15
 * @param opts - Optional plugin configuration options
16
 * @returns Array of Vite plugins for complete Start integration
17
 */
18
function TanStackStartVitePlugin(
19
  opts?: TanStackStartInputConfig & WithReactPlugin
20
): Array<PluginOption>;
21

22
/**
23
 * Alias for TanStackStartVitePlugin
24
 * @param opts - Optional plugin configuration options
25
 * @returns Array of Vite plugins for complete Start integration
26
 */
27
const tanstackStart: typeof TanStackStartVitePlugin;
28
```
29

30
**Usage Examples:**
31

32
```typescript
33
// Basic usage
34
import { defineConfig } from 'vite';
35
import { TanStackStartVitePlugin } from '@tanstack/react-start/plugin/vite';
36

37
export default defineConfig({
38
  plugins: [
39
    TanStackStartVitePlugin(),
40
  ],
41
});
42

43
// With custom React plugin configuration
44
import { defineConfig } from 'vite';
45
import { TanStackStartVitePlugin } from '@tanstack/react-start/plugin/vite';
46
import react from '@vitejs/plugin-react';
47

48
export default defineConfig({
49
  plugins: [
50
    react({
51
      // Custom React plugin options
52
      babel: {
53
        plugins: ['babel-plugin-styled-components'],
54
      },
55
    }),
56
    TanStackStartVitePlugin({
57
      customViteReactPlugin: true, // Tells Start not to add its own React plugin
58
    }),
59
  ],
60
});
61

62
// Using the alias
63
import { tanstackStart } from '@tanstack/react-start/plugin/vite';
64

65
export default defineConfig({
66
  plugins: [tanstackStart()],
67
});
68
```
69

70
### Plugin Configuration
71

72
Configuration options for customizing the TanStack Start Vite plugin behavior.
73

74
```typescript { .api }
75
/**
76
 * Parses and validates TanStack Start plugin options
77
 * @param opts - Input configuration options
78
 * @returns Validated and processed configuration
79
 */
80
function getTanStackStartOptions(
81
  opts?: TanStackStartInputConfig
82
): TanStackStartOutputConfig;
83

84
interface TanStackStartInputConfig {
85
  /** Custom React plugin options (passed to @vitejs/plugin-react) */
86
  react?: ViteReactOptions;
87
  
88
  /** 
89
   * Set to true if you're manually adding @vitejs/plugin-react to your config
90
   * Prevents Start from adding its own React plugin automatically
91
   */
92
  customViteReactPlugin?: boolean;
93
}
94

95
interface TanStackStartOutputConfig extends TanStackStartInputConfig {
96
  react: ViteReactOptions;
97
  customViteReactPlugin: boolean;
98
}
99

100
interface WithReactPlugin {
101
  react?: ViteReactOptions;
102
  customViteReactPlugin?: boolean;
103
}
104

105
interface ViteReactOptions {
106
  /** Babel configuration for React plugin */
107
  babel?: {
108
    plugins?: Array<string | [string, any]>;
109
    presets?: Array<string | [string, any]>;
110
  };
111
  
112
  /** Include/exclude patterns for React plugin processing */
113
  include?: string | RegExp | Array<string | RegExp>;
114
  exclude?: string | RegExp | Array<string | RegExp>;
115
  
116
  /** JSX runtime configuration */
117
  jsxRuntime?: 'automatic' | 'classic';
118
  jsxImportSource?: string;
119
  
120
  /** Additional options passed to @vitejs/plugin-react */
121
  [key: string]: any;
122
}
123
```
124

125
### Virtual Module Generation
126

127
The plugin automatically generates virtual modules for client and server entry points.
128

129
```typescript { .api }
130
interface VirtualModuleContext {
131
  /** Path to the router configuration file */
132
  routerFilepath: string;
133
  
134
  /** Path to the server entry file */
135
  serverEntryFilepath: string;
136
  
137
  /** Build target (client or server) */
138
  target: 'client' | 'server';
139
}
140

141
/**
142
 * Generates virtual client entry module
143
 * Creates the client-side hydration and rendering setup
144
 */
145
interface VirtualClientEntry {
146
  content: string; // Generated client entry code
147
}
148

149
/**
150
 * Generates virtual server entry module  
151
 * Creates the server-side request handler
152
 */
153
interface VirtualServerEntry {
154
  content: string; // Generated server entry code
155
}
156

157
/**
158
 * Generates virtual server root handler for deployment platforms
159
 * Creates platform-specific server handlers (H3, etc.)
160
 */
161
interface VirtualServerRootHandler {
162
  content: string; // Generated server root handler code
163
}
164
```
165

166
The plugin generates these virtual modules:
167

168
**Client Entry** (automatically generated):
169
```typescript
170
import { StrictMode, startTransition } from 'react';
171
import { hydrateRoot } from 'react-dom/client';
172
import { StartClient } from '@tanstack/react-start';
173
import { createRouter } from './router'; // Your router file
174

175
const router = createRouter();
176

177
startTransition(() => {
178
  hydrateRoot(
179
    document,
180
    <StrictMode>
181
      <StartClient router={router} />
182
    </StrictMode>
183
  );
184
});
185
```
186

187
**Server Entry** (automatically generated):
188
```typescript
189
import { createStartHandler, defaultStreamHandler } from '@tanstack/react-start/server';
190
import { createRouter } from './router'; // Your router file
191

192
export default createStartHandler({
193
  createRouter,
194
})(defaultStreamHandler);
195
```
196

197
**Server Root Handler** (automatically generated):
198
```typescript
199
import { toWebRequest, defineEventHandler } from '@tanstack/react-start/server';
200
import serverEntry from './server-entry'; // Generated server entry
201

202
export default defineEventHandler(function(event) {
203
  const request = toWebRequest(event);
204
  return serverEntry({ request });
205
});
206
```
207

208
### Build Configuration
209

210
The plugin automatically configures Vite with optimized settings for TanStack Start applications.
211

212
```typescript { .api }
213
interface StartBuildConfig {
214
  /** Resolve configuration for dependencies */
215
  resolve: {
216
    /** Deduplicated packages to prevent version conflicts */
217
    dedupe: Array<string>;
218
    
219
    /** External packages for monorepo development */
220
    external?: Array<string>;
221
  };
222
  
223
  /** Dependency optimization configuration */
224
  optimizeDeps: {
225
    /** Packages to exclude from optimization */
226
    exclude: Array<string>;
227
    
228
    /** Packages to include in optimization */
229
    include: Array<string>;
230
  };
231
}
232
```
233

234
Default configuration applied:
235
```typescript
236
{
237
  resolve: {
238
    dedupe: ['react', 'react-dom', '@tanstack/react-router'],
239
  },
240
  optimizeDeps: {
241
    exclude: ['@tanstack/react-router-devtools'],
242
    include: [
243
      'react',
244
      'react/jsx-runtime',
245
      'react/jsx-dev-runtime',
246
      'react-dom',
247
      'react-dom/client',
248
      '@tanstack/react-router',
249
    ],
250
  },
251
}
252
```
253

254
### Package Crawling
255

256
The plugin includes intelligent package crawling for dependency management.
257

258
```typescript { .api }
259
interface PackageCrawlOptions {
260
  /** Package name */
261
  name: string;
262
  
263
  /** Package exports field from package.json */
264
  exports?: Record<string, unknown> | string;
265
  
266
  /** Peer dependencies */
267
  peerDependencies: Record<string, string>;
268
}
269

270
type CrawlResult = 'include' | 'exclude' | undefined;
271

272
/**
273
 * Determines how packages should be handled during the build process
274
 * @param opts - Package information for crawling decision
275
 * @returns Crawl result indicating how to handle the package
276
 */
277
interface PackageCrawler {
278
  (opts: PackageCrawlOptions): CrawlResult;
279
}
280
```
281

282
The plugin uses these crawling rules:
283
- **Exclude** `@tanstack/react-router-devtools` (development only)
284
- **Include** packages with root exports and React peer dependencies
285
- **Undefined** for other packages (use default Vite behavior)
286

287
### Framework Integration
288

289
Integration with the TanStack Start framework core.
290

291
```typescript { .api }
292
interface FrameworkIntegration {
293
  /** Framework identifier */
294
  framework: 'react';
295
  
296
  /** Virtual module generators */
297
  getVirtualServerRootHandler(ctx: VirtualModuleContext): string;
298
  getVirtualClientEntry(ctx: VirtualModuleContext): string;
299
  getVirtualServerEntry(ctx: VirtualModuleContext): string;
300
  
301
  /** Package crawling configuration */
302
  crawlPackages(opts: PackageCrawlOptions): CrawlResult;
303
}
304
```
305

306
## Plugin Architecture
307

308
The TanStackStartVitePlugin consists of multiple sub-plugins:
309

310
1. **Configuration Plugin**: Sets up Vite environment and build options
311
2. **Core Plugin**: Handles virtual module generation and framework integration  
312
3. **React Plugin**: Configures React transformation (unless `customViteReactPlugin: true`)
313

314
**Plugin Order:**
315
```typescript
316
[
317
  {
318
    name: 'tanstack-react-start:config',
319
    configEnvironment: () => ({ /* Vite config */ }),
320
  },
321
  TanStackStartVitePluginCore({
322
    framework: 'react',
323
    // ... framework-specific configuration
324
  }),
325
  !opts?.customViteReactPlugin && viteReact(options.react),
326
]
327
```
328

329
## Core Types
330

331
```typescript { .api }
332
interface PluginOption {
333
  /** Plugin name identifier */
334
  name: string;
335
  
336
  /** Configure Vite environment */
337
  configEnvironment?: () => {
338
    resolve?: any;
339
    optimizeDeps?: any;
340
    [key: string]: any;
341
  };
342
  
343
  /** Build start hook */
344
  buildStart?: (opts: any) => void | Promise<void>;
345
  
346
  /** Transform hook for code transformation */
347
  transform?: (code: string, id: string) => string | null | Promise<string | null>;
348
  
349
  /** Generate bundle hook */
350
  generateBundle?: (opts: any, bundle: any) => void | Promise<void>;
351
  
352
  /** Additional plugin options */
353
  [key: string]: any;
354
}
355

356
interface ViteConfig {
357
  plugins: Array<PluginOption>;
358
  resolve?: {
359
    dedupe?: Array<string>;
360
    external?: Array<string>;
361
    alias?: Record<string, string>;
362
  };
363
  optimizeDeps?: {
364
    include?: Array<string>;
365
    exclude?: Array<string>;
366
  };
367
  build?: {
368
    rollupOptions?: any;
369
    ssr?: boolean;
370
  };
371
  ssr?: {
372
    external?: Array<string>;
373
    noExternal?: Array<string>;
374
  };
375
}
376

377
interface CreateRpcFn {
378
  (functionId: string, serverBase: string, splitImportFn?: () => Promise<any>): any;
379
}
380
```
381

382
## Usage Patterns
383

384
### Basic Configuration
385

386
```typescript
387
import { defineConfig } from 'vite';
388
import { TanStackStartVitePlugin } from '@tanstack/react-start/plugin/vite';
389

390
export default defineConfig({
391
  plugins: [
392
    TanStackStartVitePlugin(),
393
  ],
394
});
395
```
396

397
### Advanced Configuration
398

399
```typescript
400
import { defineConfig } from 'vite';
401
import { TanStackStartVitePlugin } from '@tanstack/react-start/plugin/vite';
402
import react from '@vitejs/plugin-react';
403

404
export default defineConfig({
405
  plugins: [
406
    react({
407
      babel: {
408
        plugins: [
409
          ['styled-components', { displayName: true }],
410
        ],
411
      },
412
    }),
413
    TanStackStartVitePlugin({
414
      customViteReactPlugin: true,
415
    }),
416
  ],
417
  
418
  // Additional Vite configuration
419
  server: {
420
    port: 3000,
421
  },
422
  
423
  build: {
424
    sourcemap: true,
425
  },
426
});
427
```
428

429
### Monorepo Configuration
430

431
```typescript
432
import { defineConfig } from 'vite';
433
import { TanStackStartVitePlugin } from '@tanstack/react-start/plugin/vite';
434
import path from 'path';
435

436
export default defineConfig({
437
  plugins: [
438
    TanStackStartVitePlugin(),
439
  ],
440
  
441
  resolve: {
442
    alias: {
443
      '@': path.resolve(__dirname, 'src'),
444
      '@shared': path.resolve(__dirname, '../shared'),
445
    },
446
  },
447
});
448
```