Vite Configuration Reference

TL;DR

• Bottom line: Use defineConfig in vite.config.ts for type-safe configuration; key areas are plugins, resolve.alias, server.proxy, and build.rollupOptions.
• Key tool/command: npx vite (dev) / npx vite build (production)
• Watch out for: Using server.proxy and expecting it to work in production — it is dev-server only.
• Works with: Vite 5.x–6.x, Node.js 18+, React, Vue, Svelte, Solid.

Constraints

• vite.config.ts must use defineConfig for type safety
• server.proxy only works during dev — production needs a real reverse proxy
• build.target defaults to "modules" (ES2020) — set explicitly for broader support
• isolatedModules: true required in tsconfig when using Vite
• Environment variables must be prefixed with VITE_ to be exposed to client code

Quick Reference

Decision Tree

START
├── React? → @vitejs/plugin-react-swc (faster)
├── Vue? → @vitejs/plugin-vue
├── Svelte? → @sveltejs/vite-plugin-svelte
├── Library? → build.lib + rollupOptions.external
├── Need SSR? → build.ssr + server middleware
├── Need API proxy? → server.proxy
└── DEFAULT → defineConfig + resolve.alias + build defaults

Step-by-Step Guide

1. Create vite.config.ts

[src1]

import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react-swc';

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

2. Configure path aliases

[src1]

import path from 'node:path';
export default defineConfig({
  resolve: {
    alias: {
      '@': path.resolve(__dirname, 'src'),
    },
  },
});

3. Set up dev server proxy

[src2]

export default defineConfig({
  server: {
    port: 3000,
    proxy: {
      '/api': {
        target: 'http://localhost:8080',
        changeOrigin: true,
      },
    },
  },
});

4. Configure production build

[src3]

export default defineConfig({
  build: {
    target: 'es2022',
    sourcemap: true,
    rollupOptions: {
      output: {
        manualChunks: {
          vendor: ['react', 'react-dom'],
        },
      },
    },
  },
});

Code Examples

Complete React + TypeScript Config

import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react-swc';
import tsconfigPaths from 'vite-tsconfig-paths';

export default defineConfig({
  plugins: [react(), tsconfigPaths()],
  server: {
    port: 3000,
    strictPort: true,
    proxy: { '/api': { target: 'http://localhost:8080', changeOrigin: true } },
  },
  build: {
    target: 'es2022',
    sourcemap: true,
    rollupOptions: {
      output: {
        manualChunks(id) {
          if (id.includes('node_modules')) {
            if (id.includes('react')) return 'vendor-react';
            return 'vendor';
          }
        },
      },
    },
  },
});

Library Mode Config

import { defineConfig } from 'vite';
import { resolve } from 'node:path';
import dts from 'vite-plugin-dts';

export default defineConfig({
  plugins: [dts({ rollupTypes: true })],
  build: {
    lib: {
      entry: resolve(__dirname, 'src/index.ts'),
      name: 'MyLib',
      formats: ['es', 'cjs'],
    },
    rollupOptions: {
      external: ['react', 'react-dom'],
    },
  },
});

Anti-Patterns

Wrong: Expecting server.proxy in production

// ❌ BAD — proxy only works in dev
export default defineConfig({
  server: { proxy: { '/api': 'http://api:8080' } },
  // Production: proxy is gone!

Correct: Use env variables for production API URLs

// ✅ GOOD — production reads VITE_API_URL
// const API = import.meta.env.VITE_API_URL || '/api';

Wrong: Not using defineConfig

// ❌ BAD — no type safety
export default { sever: { port: 3000 } }; // Typo not caught!

Correct: Always use defineConfig

// ✅ GOOD — typos caught at type-check
import { defineConfig } from 'vite';
export default defineConfig({ server: { port: 3000 } });

Wrong: Exposing secrets via VITE_ prefix

# ❌ BAD — bundled into client JS, visible to anyone
VITE_DATABASE_URL=postgresql://user:password@host/db

Correct: Only prefix public values

# ✅ GOOD — secrets stay server-only
VITE_API_URL=https://api.example.com
DATABASE_URL=postgresql://...

Common Pitfalls

• Port in use: Fix: server: { strictPort: true } to fail fast. [src2]
• Path aliases not resolved: Fix: use vite-tsconfig-paths plugin. [src7]
• CSS modules not working: Fix: files must be named *.module.css. [src4]
• Dependency pre-bundling issues: Fix: add to optimizeDeps.include. [src1]
• Build output too large: Fix: use manualChunks. [src3]
• Env vars undefined: Fix: prefix with VITE_. [src4]

Diagnostic Commands

# Check Vite version
npx vite --version

# Start with debug logging
npx vite --debug

# Preview production build
npx vite preview

# Force dependency optimization
npx vite optimize --force

Version History & Compatibility

When to Use / When Not to Use

Important Caveats

• Vite 6 Environment API is experimental — stick with standard config
• server.proxy uses http-proxy — complex scenarios may need custom middleware
• build.target: "esnext" requires all users on very modern browsers
• Worker scripts need separate worker.format and worker.plugins config