vite（Vite 前端构建）

Vite - Quick Reference

When to Use This Skill

• Set up React/Vue/Svelte projects
• Configure dev server and proxy
• Optimize production builds

Deep Knowledge: Use mcp__documentation__fetch_docs with technology: vite for comprehensive documentation.

When NOT to Use This Skill

• Webpack-based projects - Use webpack skill for webpack.config.js
• Next.js - Has its own build system (uses SWC/Turbopack)
• Create React App - Still uses Webpack (consider migrating)
• Pure Rollup - Use Rollup directly for libraries

Essential Patterns

Setup

npm create vite@latest my-app -- --template react-ts
cd my-app
npm install
npm run dev

Basic Config

// vite.config.ts
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import path from 'path';

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

  resolve: {
    alias: {
      '@': path.resolve(__dirname, './src'),
    }
  },

  server: {
    port: 3000,
    proxy: {
      '/api': {
        target: 'http://localhost:8080',
        changeOrigin: true
      }
    }
  },

  build: {
    outDir: 'dist',
    sourcemap: true
  }
});

Environment Variables

# .env
VITE_API_URL=http://localhost:8080/api

// Usage
const apiUrl = import.meta.env.VITE_API_URL;
const isProd = import.meta.env.PROD;

// TypeScript types (vite-env.d.ts)
interface ImportMetaEnv {
  readonly VITE_API_URL: string;
}

Code Splitting

// Dynamic imports
const AdminPanel = lazy(() => import('./AdminPanel'));

// Manual chunks
export default defineConfig({
  build: {
    rollupOptions: {
      output: {
        manualChunks: {
          vendor: ['react', 'react-dom'],
        }
      }
    }
  }
});

Commands

Anti-Patterns to Avoid

• Do not forget the VITE_ prefix for env vars
• Do not use relative paths (use aliases)
• Do not ignore chunk size warnings

Anti-Patterns

Quick Troubleshooting

Production Readiness

Build Optimization

// vite.config.ts
import { defineConfig, splitVendorChunkPlugin } from 'vite';
import { visualizer } from 'rollup-plugin-visualizer';

export default defineConfig({
  plugins: [
    react(),
    splitVendorChunkPlugin(),
    visualizer({ open: true }), // Bundle analysis
  ],

  build: {
    target: 'es2020',
    minify: 'esbuild',
    sourcemap: true,
    rollupOptions: {
      output: {
        manualChunks: {
          vendor: ['react', 'react-dom'],
          router: ['react-router-dom'],
          ui: ['@radix-ui/react-dialog', '@radix-ui/react-dropdown-menu'],
        },
      },
    },
    chunkSizeWarningLimit: 500,
  },

  // Optimize deps
  optimizeDeps: {
    include: ['react', 'react-dom'],
    exclude: ['@some/heavy-package'],
  },
});

Security Configuration

// vite.config.ts
export default defineConfig({
  // Never expose server-only vars
  define: {
    'process.env.API_SECRET': 'undefined',
  },

  server: {
    // CORS for dev
    cors: {
      origin: 'http://localhost:3000',
      credentials: true,
    },
    // Proxy to avoid CORS issues
    proxy: {
      '/api': {
        target: 'http://localhost:8080',
        changeOrigin: true,
        secure: false,
      },
    },
  },

  // Preview server (for testing prod builds)
  preview: {
    port: 4173,
    strictPort: true,
  },
});

// Type-safe env vars
// env.d.ts
/// <reference types="vite/client" />

interface ImportMetaEnv {
  readonly VITE_API_URL: string;
  readonly VITE_APP_TITLE: string;
  // Add all VITE_ prefixed vars here
}

interface ImportMeta {
  readonly env: ImportMetaEnv;
}

Performance

// vite.config.ts
export default defineConfig({
  build: {
    // CSS code splitting
    cssCodeSplit: true,

    // Asset inlining threshold (4kb)
    assetsInlineLimit: 4096,

    // Terser for smaller bundles (slower build)
    minify: 'terser',
    terserOptions: {
      compress: {
        drop_console: true,
        drop_debugger: true,
      },
    },
  },

  // Enable compression
  plugins: [
    react(),
    compression({ algorithm: 'gzip' }),
    compression({ algorithm: 'brotliCompress', ext: '.br' }),
  ],
});

// Lazy loading routes
// router.tsx
const Dashboard = lazy(() => import('./pages/Dashboard'));
const Settings = lazy(() => import('./pages/Settings'));

const routes = [
  {
    path: '/dashboard',
    element: (
      <Suspense fallback={<Loading />}>
        <Dashboard />
      </Suspense>
    ),
  },
];

Testing Configuration

// vite.config.ts
import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    globals: true,
    environment: 'jsdom',
    setupFiles: ['./src/test/setup.ts'],
    coverage: {
      provider: 'v8',
      reporter: ['text', 'json', 'html'],
      exclude: ['node_modules/', 'src/test/'],
    },
    include: ['src/**/*.{test,spec}.{js,ts,jsx,tsx}'],
  },
});

// src/test/setup.ts
import '@testing-library/jest-dom';
import { vi } from 'vitest';

// Mock environment variables
vi.stubEnv('VITE_API_URL', 'http://localhost:8080');

CI/CD Integration

# .github/workflows/build.yml
name: Build

on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'

      - run: npm ci

      - name: Type check
        run: npm run typecheck

      - name: Lint
        run: npm run lint

      - name: Test
        run: npm run test:coverage

      - name: Build
        run: npm run build

      - name: Upload coverage
        uses: codecov/codecov-action@v4

Monitoring Metrics

Checklist

• Type-safe environment variables
• Manual chunks for large dependencies
• Bundle analysis with visualizer
• Lazy loading for routes
• CSS code splitting enabled
• Compression (gzip/brotli)
• Console removed in production
• Source maps enabled
• Vitest configured with coverage
• CI/CD pipeline

Further Reading

For advanced configurations: mcp__documentation__fetch_docs - Technology: vite - Vite Docs