0
# Vite Plugin
1

2
The TanStack Start Vite plugin provides seamless integration with Vite for development and build processes. It configures automatic transformations, optimizations, and provides the necessary tooling for server functions, isomorphic functions, and SSR support.
3

4
## Capabilities
5

6
### TanStack Start Plugin
7

8
The main Vite plugin that provides complete integration with TanStack Start features.
9

10
```typescript { .api }
11
/**
12
 * Creates the TanStack Start Vite plugin with configuration options
13
 * @param options - Plugin configuration options
14
 * @returns Array of Vite plugins for complete Start integration
15
 */
16
function tanstackStart(
17
  options?: TanStackStartInputConfig
18
): Array<PluginOption>;
19

20
interface TanStackStartInputConfig {
21
  /** Framework type - currently only 'react' is supported */
22
  framework?: 'react';
23

24
  /** Default entry point paths for different environments */
25
  defaultEntryPaths?: {
26
    client?: string;
27
    server?: string;
28
    start?: string;
29
  };
30

31
  /** Additional plugin-specific options */
32
  [key: string]: any;
33
}
34

35
interface PluginOption {
36
  name: string;
37
  configResolved?: (config: any) => void;
38
  configureServer?: (server: any) => void;
39
  buildStart?: (options: any) => void;
40
  transform?: (code: string, id: string) => any;
41
}
42
```
43

44
**Usage Examples:**
45

46
```typescript
47
// Basic Vite configuration
48
import { defineConfig } from "vite";
49
import { tanstackStart } from "@tanstack/react-start/plugin/vite";
50

51
export default defineConfig({
52
  plugins: [tanstackStart()],
53
});
54

55
// Advanced configuration with custom options
56
export default defineConfig({
57
  plugins: [
58
    tanstackStart({
59
      framework: "react",
60
      defaultEntryPaths: {
61
        client: "./src/entry.client.tsx",
62
        server: "./src/entry.server.tsx",
63
        start: "./src/entry.start.ts"
64
      }
65
    })
66
  ],
67
  // Additional Vite configuration
68
  build: {
69
    target: "esnext"
70
  }
71
});
72

73
// Multiple environments configuration
74
export default defineConfig(({ command, mode }) => ({
75
  plugins: [
76
    tanstackStart({
77
      framework: "react",
78
      // Environment-specific configuration
79
      ...(mode === "production" && {
80
        optimizeDeps: {
81
          include: ["react", "react-dom"]
82
        }
83
      })
84
    })
85
  ]
86
}));
87
```
88

89
## Plugin Configuration
90

91
### Environment-Specific Settings
92

93
The plugin automatically configures different settings for client and server environments:
94

95
```typescript
96
// Client environment configuration
97
{
98
  resolve: {
99
    dedupe: ["react", "react-dom", "@tanstack/react-start", "@tanstack/react-router"]
100
  },
101
  optimizeDeps: {
102
    exclude: ["@tanstack/react-start", "@tanstack/react-router"],
103
    include: [
104
      "react",
105
      "react/jsx-runtime",
106
      "react/jsx-dev-runtime",
107
      "react-dom",
108
      "react-dom/client"
109
    ]
110
  }
111
}
112

113
// Server environment configuration
114
{
115
  optimizeDeps: {
116
    exclude: ["@tanstack/react-start", "@tanstack/react-router"],
117
    include: [
118
      "react",
119
      "react/jsx-runtime",
120
      "react/jsx-dev-runtime",
121
      "react-dom",
122
      "react-dom/server"
123
    ]
124
  }
125
}
126
```
127

128
### Default Entry Points
129

130
The plugin provides default entry points that can be customized:
131

132
```typescript
133
// Default entry point paths
134
const defaultEntryPaths = {
135
  client: path.resolve(__dirname, "../default-entry/client.tsx"),
136
  server: path.resolve(__dirname, "../default-entry/server.ts"),
137
  start: path.resolve(__dirname, "../default-entry/start.ts")
138
};
139

140
// Custom entry points
141
const customConfig = {
142
  defaultEntryPaths: {
143
    client: "./src/custom-client.tsx",
144
    server: "./src/custom-server.ts",
145
    start: "./src/custom-start.ts"
146
  }
147
};
148
```
149

150
## Development Features
151

152
### Hot Module Replacement
153

154
The plugin integrates with Vite's HMR system for rapid development:
155

156
```typescript
157
// Automatic HMR for server functions
158
if (import.meta.hot) {
159
  import.meta.hot.accept('./server-functions', () => {
160
    // Server functions are automatically reloaded
161
  });
162
}
163

164
// HMR for isomorphic functions
165
if (import.meta.hot) {
166
  import.meta.hot.accept('./isomorphic-functions', () => {
167
    // Both client and server implementations are updated
168
  });
169
}
170
```
171

172
### Development Server Integration
173

174
The plugin configures the Vite development server for optimal Start development:
175

176
```typescript
177
// Development server configuration
178
{
179
  server: {
180
    middlewareMode: false,
181
    hmr: true,
182
    // Server function handling in development
183
    proxy: {
184
      '/api/functions': {
185
        target: 'http://localhost:3000',
186
        changeOrigin: true
187
      }
188
    }
189
  }
190
}
191
```
192

193
## Build Configuration
194

195
### Production Optimizations
196

197
The plugin applies production-specific optimizations during build:
198

199
```typescript
200
// Production build configuration
201
{
202
  build: {
203
    rollupOptions: {
204
      external: ["react", "react-dom"],
205
      output: {
206
        globals: {
207
          react: "React",
208
          "react-dom": "ReactDOM"
209
        }
210
      }
211
    },
212
    minify: "esbuild",
213
    sourcemap: true
214
  }
215
}
216
```
217

218
### Code Splitting
219

220
Automatic code splitting for optimal loading performance:
221

222
```typescript
223
// Client bundle splitting
224
{
225
  build: {
226
    rollupOptions: {
227
      output: {
228
        manualChunks: {
229
          vendor: ["react", "react-dom"],
230
          router: ["@tanstack/react-router"],
231
          start: ["@tanstack/react-start"]
232
        }
233
      }
234
    }
235
  }
236
}
237

238
// Server bundle configuration
239
{
240
  build: {
241
    ssr: true,
242
    rollupOptions: {
243
      external: ["react", "react-dom", "node:*"],
244
      output: {
245
        format: "esm"
246
      }
247
    }
248
  }
249
}
250
```
251

252
## Advanced Plugin Usage
253

254
### Multi-Environment Builds
255

256
Configure different builds for various deployment targets:
257

258
```typescript
259
import { defineConfig } from "vite";
260
import { tanstackStart } from "@tanstack/react-start/plugin/vite";
261

262
export default defineConfig(({ command, mode }) => {
263
  const isProduction = mode === "production";
264
  const isCloudflare = process.env.PLATFORM === "cloudflare";
265

266
  return {
267
    plugins: [
268
      tanstackStart({
269
        framework: "react",
270
        // Platform-specific configurations
271
        ...(isCloudflare && {
272
          target: "webworker",
273
          external: ["node:*"]
274
        })
275
      })
276
    ],
277
    define: {
278
      __PRODUCTION__: isProduction,
279
      __PLATFORM__: JSON.stringify(process.env.PLATFORM || "node")
280
    }
281
  };
282
});
283
```
284

285
### Custom Transformations
286

287
Add custom transformations for specific use cases:
288

289
```typescript
290
import { defineConfig } from "vite";
291
import { tanstackStart } from "@tanstack/react-start/plugin/vite";
292

293
export default defineConfig({
294
  plugins: [
295
    tanstackStart(),
296
    {
297
      name: "custom-server-fn-transform",
298
      transform(code, id) {
299
        if (id.includes("server-functions")) {
300
          // Custom transformations for server functions
301
          return {
302
            code: transformServerFunctions(code),
303
            map: null
304
          };
305
        }
306
      }
307
    }
308
  ]
309
});
310
```
311

312
### Integration with Other Tools
313

314
Combine with other Vite plugins and tools:
315

316
```typescript
317
import { defineConfig } from "vite";
318
import { tanstackStart } from "@tanstack/react-start/plugin/vite";
319
import { visualizer } from "rollup-plugin-visualizer";
320

321
export default defineConfig({
322
  plugins: [
323
    tanstackStart(),
324

325
    // Bundle analyzer
326
    visualizer({
327
      filename: "dist/stats.html",
328
      open: true,
329
      gzipSize: true
330
    }),
331

332
    // Custom environment handling
333
    {
334
      name: "environment-config",
335
      configResolved(config) {
336
        if (config.command === "serve") {
337
          // Development-specific setup
338
          process.env.NODE_ENV = "development";
339
        }
340
      }
341
    }
342
  ],
343

344
  // Environment variables
345
  define: {
346
    __VERSION__: JSON.stringify(process.env.npm_package_version),
347
    __BUILD_TIME__: JSON.stringify(new Date().toISOString())
348
  }
349
});
350
```
351

352
## Environment Variables and Constants
353

354
### Vite Environment Names
355

356
The plugin recognizes specific environment names for configuration:
357

358
```typescript
359
const VITE_ENVIRONMENT_NAMES = {
360
  client: "client",
361
  server: "server",
362
  start: "start"
363
} as const;
364

365
// Usage in plugin configuration
366
if (environmentName === VITE_ENVIRONMENT_NAMES.client) {
367
  // Client-specific configuration
368
} else if (environmentName === VITE_ENVIRONMENT_NAMES.server) {
369
  // Server-specific configuration
370
}
371
```
372

373
### Build-time Constants
374

375
Constants available during build and runtime:
376

377
```typescript
378
// Available in your application code
379
declare const __PRODUCTION__: boolean;
380
declare const __VERSION__: string;
381
declare const __BUILD_TIME__: string;
382
declare const __PLATFORM__: "node" | "cloudflare" | "vercel";
383

384
// Usage
385
if (__PRODUCTION__) {
386
  console.log(`Production build ${__VERSION__} built at ${__BUILD_TIME__}`);
387
}
388
```
389

390
## Types
391

392
```typescript { .api }
393
// Main plugin configuration interface
394
interface TanStackStartInputConfig {
395
  framework?: 'react';
396
  defaultEntryPaths?: {
397
    client?: string;
398
    server?: string;
399
    start?: string;
400
  };
401
  target?: 'node' | 'webworker' | 'browser';
402
  external?: string[];
403
  optimizeDeps?: {
404
    include?: string[];
405
    exclude?: string[];
406
    noDiscovery?: boolean;
407
  };
408
  resolve?: {
409
    noExternal?: boolean | string[];
410
    external?: string[];
411
  };
412
}
413

414
// Vite plugin option type
415
interface PluginOption {
416
  name: string;
417
  configResolved?: (config: ResolvedConfig) => void | Promise<void>;
418
  configureServer?: (server: ViteDevServer) => void | Promise<void>;
419
  buildStart?: (options: NormalizedInputOptions) => void | Promise<void>;
420
  resolveId?: (id: string, importer?: string) => string | null | Promise<string | null>;
421
  load?: (id: string) => string | null | Promise<string | null>;
422
  transform?: (code: string, id: string) => TransformResult | Promise<TransformResult>;
423
  generateBundle?: (options: OutputOptions, bundle: OutputBundle) => void | Promise<void>;
424
}
425

426
// Environment names constants
427
interface ViteEnvironmentNames {
428
  readonly client: "client";
429
  readonly server: "server";
430
  readonly start: "start";
431
}
432

433
// Transform result type
434
interface TransformResult {
435
  code: string;
436
  map?: string | SourceMap | null;
437
}
438

439
// Vite configuration types (from Vite)
440
interface ResolvedConfig {
441
  command: "build" | "serve";
442
  mode: string;
443
  isProduction: boolean;
444
  env: Record<string, any>;
445
  resolve: ResolveOptions;
446
  plugins: Plugin[];
447
}
448

449
interface ViteDevServer {
450
  middlewares: any;
451
  hot: any;
452
  ws: any;
453
  config: ResolvedConfig;
454
}
455

456
// Build options
457
interface NormalizedInputOptions {
458
  input: string | string[] | Record<string, string>;
459
  external: (string | RegExp)[] | RegExp | string | ((id: string, parentId: string, isResolved: boolean) => boolean);
460
  plugins: Plugin[];
461
}
462

463
interface OutputOptions {
464
  format: "amd" | "cjs" | "es" | "iife" | "umd" | "system";
465
  file?: string;
466
  dir?: string;
467
  globals?: Record<string, string>;
468
}
469

470
interface OutputBundle {
471
  [fileName: string]: OutputAsset | OutputChunk;
472
}
473
```
474

475
## Constants
476

477
```typescript { .api }
478
// Vite environment names used by the plugin
479
const VITE_ENVIRONMENT_NAMES: ViteEnvironmentNames;
480

481
// Default plugin configuration
482
const DEFAULT_CONFIG: TanStackStartInputConfig;
483

484
// Internal plugin markers
485
const TANSTACK_START_PLUGIN_NAME: "tanstack-react-start:config";
486
const TANSTACK_START_CORE_PLUGIN_NAME: "tanstack-start-plugin-core";
487
```