Vite Plugin Configuration

Configure the TanStack Start Vite plugin for React, Solid, or Vue applications

The TanStack Start Vite plugin is the core integration that enables full-stack functionality in your application. It handles server functions, routing, SSR, and build configuration.

Installation

The plugin is included with your framework-specific Start package:

npm install @tanstack/react-start
# or
npm install @tanstack/solid-start
# or
npm install @tanstack/vue-start

Basic Setup

Add the plugin to your vite.config.ts:

React

import { defineConfig } from 'vite'
import { tanstackStart } from '@tanstack/react-start/plugin/vite'

export default defineConfig({
  plugins: [tanstackStart()],
})

Configuration Options

The plugin accepts a configuration object with the following options:

srcDirectory

Specify the source directory for your application.

tanstackStart({
  srcDirectory: 'src', // default: 'src'
})

start

Configure the Start entry point.

tanstackStart({
  start: {
    entry: './src/start.tsx', // Custom start entry file
  },
})

router

Configure router-specific options.

tanstackStart({
  router: {
    entry: './src/router.tsx', // Custom router entry
    basepath: '/', // Base path for routing
    routesDirectory: 'routes', // Routes directory relative to src
    generatedRouteTree: 'routeTree.gen.ts', // Generated route tree file
  },
})

Router Options

• entry: Custom router entry file path
• basepath: Base path for all routes (default: inherits from Vite’s base option)
• routesDirectory: Directory containing route files (default: 'routes')
• generatedRouteTree: Path for generated route tree file (default: 'routeTree.gen.ts')

client

Configure client-side build options.

tanstackStart({
  client: {
    entry: './src/client.tsx', // Custom client entry
    base: '/_build', // Client asset base path (default: '/_build')
  },
})

server

Configure server-side build options. See Server Options for details.

tanstackStart({
  server: {
    entry: './src/server.ts', // Custom server entry
    build: {
      staticNodeEnv: true, // Replace process.env.NODE_ENV at build time
    },
  },
})

serverFns

Configure server function behavior.

tanstackStart({
  serverFns: {
    base: '/_serverFn', // Base path for server functions (default: '/_serverFn')
    generateFunctionId: ({ filename, functionName }) => {
      // Custom function ID generation
      return `${filename}:${functionName}`
    },
  },
})

serverFns Options

• base: Base path for server function endpoints (default: '/_serverFn')
• generateFunctionId: Custom function to generate unique IDs for server functions

pages

Define pages for prerendering and sitemap generation.

tanstackStart({
  pages: [
    {
      path: '/',
      sitemap: {
        priority: 1.0,
        changefreq: 'daily',
      },
    },
    {
      path: '/about',
      prerender: {
        enabled: true,
        outputPath: '/about.html',
      },
    },
  ],
})

prerender

Configure static site generation. See Static Generation for details.

tanstackStart({
  prerender: {
    enabled: true,
    concurrency: 4, // Number of pages to prerender concurrently
    failOnError: true, // Fail build if prerendering errors
    autoStaticPathsDiscovery: true, // Auto-discover static paths
    maxRedirects: 5, // Maximum redirects to follow
    crawlLinks: true, // Crawl links to discover pages
    retryCount: 3, // Retry failed prerenders
    retryDelay: 1000, // Delay between retries (ms)
    headers: {
      'User-Agent': 'TanStack-Start-Prerenderer',
    },
    onSuccess: ({ page, html }) => {
      console.log(`Prerendered: ${page.path}`)
    },
  },
})

sitemap

Configure sitemap generation.

tanstackStart({
  sitemap: {
    enabled: true,
    host: 'https://example.com',
    outputPath: 'sitemap.xml', // default: 'sitemap.xml'
  },
})

spa

Configure Single Page Application (SPA) mode.

tanstackStart({
  spa: {
    enabled: true,
    maskPath: '/', // Path to use for SPA shell
    prerender: {
      outputPath: '/_shell',
      crawlLinks: false,
    },
  },
})

dev

Configure development server options.

tanstackStart({
  dev: {
    ssrStyles: {
      enabled: true, // Enable SSR styles in development
      basepath: '/', // Base path for SSR styles
    },
  },
})

importProtection

Configure import protection to prevent server code from being bundled in the client.

tanstackStart({
  importProtection: {
    enabled: true,
    behavior: 'error', // 'error' | 'mock'
    // or separate behavior for dev and build
    behavior: {
      dev: 'mock',
      build: 'error',
    },
    mockAccess: 'error', // 'error' | 'warn' | 'off'
    client: {
      specifiers: ['fs', 'path'], // Deny specific imports on client
      files: [/\.server\./], // Deny files matching pattern
      excludeFiles: [/node_modules/], // Exclude from checking
    },
    server: {
      specifiers: ['react-dom/client'], // Deny specific imports on server
    },
    onViolation: (violation) => {
      // Custom violation handler
      console.error('Import violation:', violation)
      return false // Return true to suppress error
    },
    maxTraceDepth: 50, // Maximum import chain depth to trace
    log: 'once', // 'once' | 'always'
  },
})

Import Protection Options

• enabled: Enable import protection (default: true)
• behavior: How to handle violations - 'error' throws, 'mock' creates mock exports
• mockAccess: Control runtime diagnostics when mocked imports are accessed
• client: Rules for client-side imports
  • specifiers: Array of import specifiers to deny (strings or RegExp)
  • files: Array of file patterns to deny (strings or RegExp)
  • excludeFiles: Array of file patterns to exclude from checking
• server: Rules for server-side imports
• onViolation: Callback when a violation occurs
• maxTraceDepth: Maximum depth to trace import chains
• log: Control logging frequency for violations

vite

Advanced Vite integration options.

tanstackStart({
  vite: {
    installDevServerMiddleware: true, // Install dev server middleware
  },
})

Complete Example

Here’s a comprehensive configuration example:

import { defineConfig } from 'vite'
import { tanstackStart } from '@tanstack/react-start/plugin/vite'

export default defineConfig({
  plugins: [
    tanstackStart({
      srcDirectory: 'src',
      router: {
        basepath: '/',
        routesDirectory: 'routes',
      },
      client: {
        base: '/_build',
      },
      server: {
        build: {
          staticNodeEnv: true,
        },
      },
      serverFns: {
        base: '/_serverFn',
      },
      prerender: {
        enabled: true,
        concurrency: 4,
        crawlLinks: true,
      },
      sitemap: {
        enabled: true,
        host: 'https://example.com',
      },
      importProtection: {
        enabled: true,
        behavior: {
          dev: 'mock',
          build: 'error',
        },
        client: {
          specifiers: ['fs', 'path', 'crypto'],
        },
      },
    }),
  ],
})

Environment Variables

The plugin automatically defines several environment variables that are replaced at build time:

• TSS_SERVER_FN_BASE: Base path for server functions
• TSS_CLIENT_OUTPUT_DIR: Client output directory
• TSS_ROUTER_BASEPATH: Router base path
• TSS_SHELL: Whether SPA shell is enabled (dev only)
• TSS_DEV_SERVER: Whether running in dev server
• TSS_DEV_SSR_STYLES_ENABLED: Whether SSR styles are enabled in dev
• TSS_DEV_SSR_STYLES_BASEPATH: Base path for SSR styles in dev

These are available via process.env.TSS_* or import.meta.env.TSS_*.

Next Steps

Build Options

Learn about build configuration options

Server Options

Configure server-side rendering and deployment