web-tooling-vite

Vite Build Tool Patterns

Quick Guide: Vite is the build tool for frontend apps. Keep path aliases in sync between vite.config.ts and tsconfig.json (or use resolve.tsconfigPaths in Vite 8). Use vendor chunk splitting (manualChunks in Vite 7, codeSplitting.groups in Vite 8). Use loadEnv() for environment-specific builds. Vite 8 uses Rolldown by default with build.rolldownOptions.

Current versions: Vite 8 (stable, March 2026) with Rolldown bundler. Vite 7 (June 2025) still widely deployed.

<critical_requirements>

CRITICAL: Before Using This Skill

All code must follow project conventions in CLAUDE.md (kebab-case, named exports, import ordering, import type, named constants)

(You MUST keep path aliases in sync between vite.config.ts and tsconfig.json - mismatches cause import resolution failures)

(You MUST use build.rolldownOptions in Vite 8+ - build.rollupOptions is a deprecated alias)

(You MUST use codeSplitting.groups for chunk splitting in Vite 8 - object-form manualChunks is removed, function-form deprecated)

(You MUST use build.modulePreload.polyfill instead of deprecated build.polyfillModulePreload)

(You MUST use Sass modern API (default in Vite 6+) - legacy API is removed in Vite 7+)

</critical_requirements>

Auto-detection: Vite, vite.config.ts, vite.config.js, manualChunks, advancedChunks, codeSplitting, loadEnv, rolldownOptions, rollupOptions, modulePreload, resolve.alias, resolve.tsconfigPaths, build.target, baseline-widely-available

When to use:

• Configuring Vite build tool for frontend applications
• Setting up path aliases with tsconfig sync
• Vendor chunk splitting for production builds
• Environment-specific build configuration (dev/staging/prod)
• Migrating from Vite 7 (Rollup) to Vite 8 (Rolldown)
• Configuring module preload, build targets, or Sass preprocessing

When NOT to use:

• Server-side build processes (Docker builds, CI/CD pipelines)
• Linter or formatter configuration (separate tooling skill)
• TypeScript compiler options (separate tooling skill)

Key patterns covered:

• Path aliases with tsconfig sync (and Vite 8 resolve.tsconfigPaths)
• Vendor chunk splitting (manualChunks for Vite 7, codeSplitting for Vite 8)
• Environment-specific builds with loadEnv and define
• Module preload configuration
• Sass modern API configuration
• Environment API (experimental, primarily for framework authors)
• Build target selection (baseline-widely-available)

Detailed resources:

• [examples/core.md](examples/core.md) - Full code examples for all patterns
• [reference.md](reference.md) - Quick-lookup tables, migration checklist, external links

<philosophy>

Philosophy

Vite should be fast, zero-config by default, and environment-aware. The build tool stays out of your way during development (instant HMR) and optimizes aggressively for production (chunk splitting, minification, tree-shaking).

When to use this skill:

• Configuring or optimizing Vite builds
• Setting up path aliases, chunk splitting, or environment configs
• Migrating between Vite major versions (7 to 8)
• Configuring Sass, build targets, or module preload

When NOT to use:

• Runtime application code (this is build-time configuration only)
• SSR meta-framework configuration (handled by meta-framework skills)
• CI/CD pipeline configuration

</philosophy>

<patterns>

Core Patterns

Pattern 1: Path Aliases

Configure path aliases in both vite.config.ts and tsconfig.json to eliminate deep relative imports. In Vite 8, use resolve.tsconfigPaths: true instead of manual resolve.alias.

// Vite 7: manual resolve.alias
resolve: {
  alias: {
    "@": path.resolve(__dirname, "./src"),
    "@components": path.resolve(__dirname, "./src/components"),
  },
},

// Vite 8: built-in tsconfig path resolution
resolve: {
  tsconfigPaths: true, // reads from tsconfig.json automatically
},

Key point: resolve.tsconfigPaths is disabled by default (performance cost). Enable only if using tsconfig paths. See [examples/core.md](examples/core.md) for complete configs.

Pattern 2: Vendor Chunk Splitting

Split vendor dependencies into separate chunks for better caching. API differs between Vite 7 and 8.

// Vite 7: manualChunks (object form)
build: {
  rollupOptions: {
    output: {
      manualChunks: {
        "vendor": ["react", "react-dom"],
      },
    },
  },
},

// Vite 8: codeSplitting.groups (regex-based)
build: {
  rolldownOptions: {
    output: {
      codeSplitting: {
        groups: [
          { name: "vendor", test: /[\\/]node_modules[\\/]react(-dom)?[\\/]/ },
        ],
      },
    },
  },
},

Key point: In Vite 8, object-form manualChunks is removed and function-form is deprecated. Rolldown generates a runtime.js chunk alongside code-split groups. See [examples/core.md](examples/core.md) for full examples.

Pattern 3: Environment-Specific Builds

Use loadEnv() for environment-aware configuration and define for build-time constants.

export default defineConfig(({ mode }) => {
  const env = loadEnv(mode, process.cwd(), "");
  return {
    define: {
      __APP_VERSION__: JSON.stringify(process.env.npm_package_version),
    },
    build: {
      sourcemap: mode === "development",
      minify: mode === "production",
    },
  };
});

Key point: The third argument to loadEnv() ("") loads all env vars, not just VITE_-prefixed ones. Use --mode flag for environment selection. See [examples/core.md](examples/core.md) for full config with scripts.

Pattern 4: Module Preload Configuration

build: {
  modulePreload: {
    polyfill: false, // disable for modern-only targets
    resolveDependencies: (filename, deps, { hostId, hostType }) => {
      return deps.filter((dep) => !dep.includes("large-vendor"));
    },
  },
},

Key point: build.polyfillModulePreload is deprecated. Use build.modulePreload.polyfill (current API since Vite 6).

Pattern 5: Sass Configuration (Vite 6+)

css: {
  preprocessorOptions: {
    scss: {
      // modern API is the default in Vite 6+ — no need to specify
      additionalData: `@use "@/styles/variables" as *;`,
    },
  },
},

Key point: Legacy API (api: 'legacy') is removed in Vite 7+. Migrate @import to @use/@forward with namespaced access (variables.$color-primary).

Pattern 6: Environment API (Experimental)

Primarily for framework authors. Remains in RC phase as of Vite 8. Most apps do not need this.

environments: {
  client: { build: { outDir: "dist/client" } },
  ssr: { build: { outDir: "dist/server", ssr: true } },
},

See [examples/core.md](examples/core.md) for full multi-environment config.

Pattern 7: Dev Server Proxy

const DEV_SERVER_PORT = 3000;
const API_PROXY_TARGET = "http://localhost:8000";

server: {
  port: DEV_SERVER_PORT,
  proxy: {
    "/api": { target: API_PROXY_TARGET, changeOrigin: true },
  },
},

</patterns>

<decision_framework>

Decision Framework

Vite Version Selection

Which Vite version?
├─ New project (March 2026+)?
│   └─ Vite 8 (Rolldown bundler, fastest builds) ✓
├─ Existing Vite 7 project?
│   ├─ Build performance is a bottleneck?
│   │   └─ YES → Migrate to Vite 8 (10-30x faster)
│   └─ NO → Stay on Vite 7 (stable, no migration needed)
└─ Existing Vite 6 project?
    └─ Plan upgrade to Vite 7 first, then Vite 8

Chunk Splitting Strategy

How to split chunks?
├─ Vite 8 (Rolldown)?
│   ├─ Simple vendor separation?
│   │   └─ codeSplitting.groups with regex patterns ✓
│   └─ Complex splitting (size limits, shared modules)?
│       └─ codeSplitting with maxSize/minSize/minShareCount
├─ Vite 7 (Rollup)?
│   ├─ Simple vendor separation?
│   │   └─ manualChunks object form ✓
│   └─ Complex splitting lo