npm-tanstack--react-start

1
# Vite Plugin
2

3
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.
4

5
## Capabilities
6

7
### TanStack Start Plugin
8

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

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

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

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

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

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

45
**Usage Examples:**
46

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

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

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

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

90
## Plugin Configuration
91

92
### Environment-Specific Settings
93

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

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

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

129
### Default Entry Points
130

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

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

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

151
## Development Features
152

153
### Hot Module Replacement
154

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

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

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

173
### Development Server Integration
174

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

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

194
## Build Configuration
195

196
### Production Optimizations
197

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

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

219
### Code Splitting
220

221
Automatic code splitting for optimal loading performance:
222

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

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

253
## Advanced Plugin Usage
254

255
### Multi-Environment Builds
256

257
Configure different builds for various deployment targets:
258

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

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

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

286
### Custom Transformations
287

288
Add custom transformations for specific use cases:
289

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

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

313
### Integration with Other Tools
314

315
Combine with other Vite plugins and tools:
316

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

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

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

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

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

353
## Environment Variables and Constants
354

355
### Vite Environment Names
356

357
The plugin recognizes specific environment names for configuration:
358

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

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

374
### Build-time Constants
375

376
Constants available during build and runtime:
377

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

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

391
## Types
392

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

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

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

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

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

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

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

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

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

476
## Constants
477

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

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

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