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

Command Usage

npm run dev

Dev server HMR

npm run build

Build production

npm run preview

Preview build

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

Anti-Pattern Why It's Bad Correct Approach

No VITE_ prefix for env vars Won't be exposed to client All client vars need VITE_ prefix

Relative imports Hard to refactor Use path aliases (@/...)

Ignoring chunk size warnings Large initial bundles Use manual chunks or lazy loading

Not using TypeScript for config Missing type hints Use defineConfig from 'vite'

No dev/prod environment separation Same config for both Use env-specific .env files

Large public folder Slow builds Only static assets in public/

Quick Troubleshooting

Issue Cause Solution

Env vars undefined Missing VITE_ prefix Rename to VITE_API_URL

HMR not working Proxy configuration Check server.hmr settings

Build fails with dynamic imports Wrong syntax Use import() not require()

Slow dev server Too many dependencies Add to optimizeDeps.include

404 on refresh (SPA) No fallback Add server.historyApiFallback

CORS errors in dev Wrong proxy config Configure server.proxy correctly

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

Metric Target

Bundle size (gzip) < 200KB

Initial load time < 2s

Build time < 60s

Lighthouse Performance

90

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