Skip to main content
Agent skill

Vite Patterns

Vite build tool patterns including config, plugins, HMR, env variables, proxy setup, SSR, library mode, dependency pre-bundling, and build optimization. Activate when working with vite.config.ts, Vite plugins, or Vite-based projects.

Get started

Get the complete skill folder, including its scripts and reference files.

·

When to use this skill

Use Vite Patterns when an AI agent needs a reusable SKILL.md workflow for this job: Vite build tool patterns including config, plugins, HMR, env variables, proxy setup, SSR, library mode, dependency pre-bundling, and build optimization. Activate when working with vite.config.ts, Vite plugins, or Vite-based projects.

When not to use it

Skip Vite Patterns when the task is outside the coding category, or when a more specific skill in this directory already covers the same workflow with clearer triggers.

How to install

Where will you use it?

Install scope
Claude Code folder setup
mkdir -p ~/.claude/skills/vite-patterns
# Save SKILL.md to ~/.claude/skills/vite-patterns/SKILL.md
  1. Claude Code personal install: place the skill and its bundled files at ~/.claude/skills/vite-patterns/SKILL.md. For a shared project, commit the folder at .claude/skills/vite-patterns/ instead.
  2. Current Claude Code detects SKILL.md changes in watched directories during the session. If you just created a top-level skills directory, run /reload-skills. Check that the skill is listed before testing its trigger.
  3. For Claude chat or Cowork in the Desktop app, manage uploaded skills in Customize > Skills; copying files into a local Claude Code folder is not a Desktop install. Other agents may use different install locations.

Full install guide for Claude, Cursor, and Codex →

Try a starter prompt

After installing the skill, paste this starter prompt into your agent to verify it triggers on a small task.

Starter prompt
Use the Vite Patterns skill for this task: Configuring vite.config.ts or vite.config.js. Confirm any required inputs or files before making changes.

What supports this recommendation?

83/100 provisional content score. This measures documentation, practical detail and source signals. It is not a measured task success rate or a security certification.

Documentation
92/100
Practical detail
92/100
Source evidence
63/100
Source signals
72/100
Model compatibility evidence
  • claudeuntested

    No model-specific signal or recorded compatibility test was found.

  • chatgptuntested

    No model-specific signal or recorded compatibility test was found.

  • geminiuntested

    No model-specific signal or recorded compatibility test was found.

  • copilotuntested

    No model-specific signal or recorded compatibility test was found.

  • llamauntested

    No model-specific signal or recorded compatibility test was found.

  • perplexityuntested

    No model-specific signal or recorded compatibility test was found.

  • mistraluntested

    No model-specific signal or recorded compatibility test was found.

  • grokuntested

    No model-specific signal or recorded compatibility test was found.

Inferred compatibility is based on content signals. Check the app, its available tools and setup requirements before running a skill.

What this skill does

# Vite Patterns

Build tool and dev server patterns for Vite 8+ projects. Covers configuration, environment variables, proxy setup, library mode, dependency pre-bundling, and common production pitfalls.

## When to Use

- Configuring `vite.config.ts` or `vite.config.js` - Setting up environment variables or `.env` files - Configuring dev server proxy for API backends - Optimizing build output (chunks, minification, assets) - Publishing libraries with `build.lib` - Troubleshooting dependency pre-bundling or CJS/ESM interop - Debugging HMR, dev server, or build errors - Choosing or ordering Vite plugins

## How It Works

- **Dev mode** serves source files as native ESM — no bundling. Transforms happen on-demand per module request, which is why cold starts are fast and HMR is precise. - **Build mode** uses Rolldown (v7+) or Rollup (v5–v6) to bundle the app for production with tree-shaking, code-splitting, and Oxc-based minification. - **Dependency pre-bundling** converts CJS/UMD deps to ESM once via esbuild and caches the result under `node_modules/.vite`, so subsequent starts skip the work. - **Plugins** share a unified interface across dev and build — the same plugin object works for both the dev server's on-demand transforms and the production pipeline. - **Environment variables** are statically inlined at build time. `VITE_`-prefixed vars become public constants in the bundle; everything unprefixed is invisible to client code.

## Examples

### Config Structure

#### Basic Config

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

export default defineConfig({ plugins: [react()], resolve: { alias: { '@': new URL('./src', import.meta.url).pathname }, }, }) ```

#### Conditional Config

```typescript // vite.config.ts import { defineConfig, loadEnv } from 'vite' import react from '@vitejs/plugin-react'

export default defineConfig(({ command, mode }) => { const env = loadEnv(mode, process.cwd()) // VITE_ prefixed only (safe)

return { plugins: [react()], server: command === 'serve' ? { port: 3000 } : undefined, define: { __API_URL__: JSON.stringify(env.VITE_API_URL), }, } }) ```

#### Key Config Options

| Key | Default | Description | |-----|---------|-------------| | `root` | `'.'` | Project root (where `index.html` lives) | | `base` | `'/'` | Public base path for deployed assets | | `envPrefix` | `'VITE_'` | Prefix for client-exposed env vars | | `build.outDir` | `'dist'` | Output directory | | `build.minify` | `'oxc'` | Minifier (`'oxc'`, `'terser'`, or `false`) | | `build.sourcemap` | `false` | `true`, `'inline'`, or `'hidden'` |

### Plugins

#### Essential Plugins

Most plugin needs are covered by a handful of well-maintained packages. Reach for these before writing your own.

| Plugin | Purpose | When to use | |--------|---------|-------------| | `@vitejs/plugin-react-swc` | React HMR + Fast Refresh via SWC | Default for React apps (faster than Babel variant) | | `@vitejs/plugin-react` | React HMR + Fast Refresh via Babel | Only if you need Babel plugins (emotion, MobX decorators) | | `@vitejs/plugin-vue` | Vue 3 SFC support | Vue apps | | `vite-plugin-checker` | Runs `tsc` + ESLint in worker thread with HMR overlay | **Any TypeScript app** — Vite does NOT type-check during `vite build` | | `vite-tsconfig-paths` | Honors `tsconfig.json` `paths` aliases | Any time you already have aliases in `tsconfig.json` | | `vite-plugin-dts` | Emits `.d.ts` files in library mode | Publishing TypeScript libraries | | `vite-plugin-svgr` | Imports SVGs as React components | React apps using SVGs as components | | `rollup-plugin-visualizer` | Bundle treemap/sunburst report | Periodic bundle size audits (use `enforce: 'post'`) | | `vite-plugin-pwa` | Zero-config PWA + Workbox | Offline-capable apps |

**Critical callout:** `vite build` transpiles but does NOT type-check. Type errors silently ship to production unless you add `vite-plugin-checker` or run `tsc --noEmit` in CI.

#### Authoring Custom Plugins

Authoring is rare — most needs are covered by existing plugins. When you do need one, start inline in `vite.config.ts` and only extract if reused.

```typescript // vite.config.ts — minimal inline plugin function myPlugin(): Plugin { return { name: 'my-plugin', // required, must be unique enforce: 'pre', // 'pre' | 'post' (optional) apply: 'build', // 'build' | 'serve' (optional) transform(code, id) { if (!id.endsWith('.custom')) return return { code: transformCustom(code), map: null } }, } } ```

**Key hooks:** `transform` (modify source), `resolveId` + `load` (virtual modules), `transformIndexHtml` (inject into HTML), `configureServer` (add dev middleware), `hotUpdate` (custom HMR — replaces deprecated `handleHotUpdate` in v7+).

**Virtual modules** use the `\0` prefix convention — `resolveId` returns `'\0virtual:my-id'` so other plugins skip it. User code imports `'virtual:my-id'`.

For full plugin API, see [vite.dev/guide/api-plugin](https://vite.dev/guide/api-plugin). Use `vite-plugin-inspect` during development to debug the transform pipeline.

### HMR API

Framework plugins (`@vitejs/plugin-react`, `@vitejs/plugin-vue`, etc.) handle HMR automatically. Reach for `import.meta.hot` directly only when building custom state stores, dev tools, or framework-agnostic utilities that need to persist state across updates.

```typescript // src/store.ts — manual HMR for a vanilla module if (import.meta.hot) { // Persist state across updates (must MUTATE, never reassign .data) import.meta.hot.data.count = import.meta.hot.data.count ?? 0

// Cleanup side effects before module is replaced import.meta.hot.dispose((data) => clearInterval(data.intervalId))

// Accept this module's own updates import.meta.hot.accept() } ```

All `import.meta.hot` code is tree-shaken out of production builds — no guard removal needed.

### Environment Variables

Vite loads `.env`, `.env.local`, `.env.[mode]`, and `.env.[mode].local` in that order (later overrides earlier); `*.local` files are gitignored and meant for local secrets.

#### Client-Side Access

Only `VITE_`-prefixed vars are exposed to client code:

```typescript import.meta.env.VITE_API_URL // string import.meta.env.MODE // 'development' | 'production' | custom import.meta.env.BASE_URL // base config value import.meta.env.DEV // boolean import.meta.env.PROD // boolean import.meta.env.SSR // boolean ```

#### Using Env in Config

```typescript // vite.config.ts import { defineConfig, loadEnv } from 'vite'

export default defineConfig(({ mode }) => { const env = loadEnv(mode, process.cwd()) // VITE_ prefixed only (safe) return { define: { __API_URL__: JSON.stringify(env.VITE_API_URL), }, } }) ```

### Security

#### `VITE_` Prefix is NOT a Security Boundary

Any variable prefixed with `VITE_` is **statically inlined into the client bundle at build time**. Minification, base64 encoding, and disabling source maps do NOT hide it. A determined attacker can extract any `VITE_` var from the shipped JavaScript.

**Rule:** Only public values (API URLs, feature flags, public keys) go in `VITE_` vars. Secrets (API tokens, database URLs, private keys) MUST live server-side behind an API or serverless function.

#### The `loadEnv('')` Trap

```typescript // BAD: passing '' as the third arg loads ALL env vars — including server secrets — // and makes them available to inline into client code via `define`. const env = loadEnv(mode, process.cwd(), '')

// GOOD: explicit prefix list const env = loadEnv(mode, process.cwd(), ['VITE_', 'APP_']) ```

#### Source Maps in Production

Production source maps leak your original source code. Disable them unless you upload to an error tracker (Sentry, Bugsnag) and delete locally afterward:

```typescript build: { sourcemap: false, // default — keep it this way } ```

#### `.gitignore` Checklist

- `.env.local`, `.env.*.local` — local secret overrides - `dist/` — build output - `node_modules/.vite` — pre-bundle cache (stale entries cause phantom errors)

### Server Proxy

```typescript // vite.config.ts — server.proxy server: { proxy: { '/foo': 'http://localhost:4567', // string shorthand

'/api': { target: 'http://localhost:8080', changeOrigin: true, // needed for virtual-hosted backends rewrite: (path) => path.replace(/^\/api/, ''), }, }, } ```

For WebSocket proxying, add `ws: true` to the route config.

### Build Optimization

#### Manual Chunks

```typescript // vite.config.ts — build.rolldownOptions build: { rolldownOptions: { output: { // Object form: group specific packages manualChunks: { 'react-vendor': ['react', 'react-dom'], 'ui-vendor': ['@radix-ui/react-dialog', '@radix-ui/react-popover'], }, }, }, } ```

```typescript // Function form: split by heuristic manualChunks(id) { if (id.includes('node_modules/react')) return 'react-vendor' if (id.includes('node_modules')) return 'vendor' } ```

### Performance

#### Avoid Barrel Files

Barrel files (`index.ts` re-exporting everything from a directory) force Vite to load every re-exported file even when you import a single symbol. This is the #1 dev-server slowdown flagged by the official docs.

```typescript // BAD — importing one util forces Vite to load the whole barrel import { slash } from '@/utils'

// GOOD — direct import, only the one file is loaded import { slash } from '@/utils/slash' ```

#### Be Explicit with Import Extensions

Each implicit extension forces up to 6 filesystem checks via `resolve.extensions`. In large codebases, this adds up.

```typescript // BAD import Component from './Component'

// GOOD import Component from './Component.tsx' ```

Narrow `tsconfig.json` `allowImportingTsExtensions` + `resolve.extensions` to only the extensions you actually use.

#### Warm-Up Hot-Path Routes

`server.warmup.clientFiles` pre-transforms known hot entries before the browser requests them — eliminating the cold-load request waterfall on large apps.

```typescript // vite.config.ts server: { warmup: { clientFiles: ['./src/main.tsx', './src/routes/**/*.tsx'], }, } ```

#### Profiling Slow Dev Servers

When `vite dev` feels slow, start with `vite --profile`, interact with the app, then press `p+enter` to save a `.cpuprofile`. Load it in [Speedscope](https://www.speedscope.app) to find which plugins are eating time — usually `buildStart`, `config`, or `configResolved` hooks in community plugins.

### Library Mode

When publishing an npm package, use `build.lib`. Two footguns matter more than config detail:

1. **Types are not emitted** — add `vite-plugin-dts` or run `tsc --emitDeclarationOnly` separately. 2. **Peer dependencies MUST be externalized** — unlisted peers get bundled into your library, causing duplicate-runtime errors in consumers.

```typescript // vite.config.ts build: { lib: { entry: 'src/index.ts', formats: ['es', 'cjs'], fileName: (format) => `my-lib.${format}.js`, }, rolldownOptions: { external: ['react', 'react-dom', 'react/jsx-runtime'], // every peer dep }, } ```

### SSR Externals

Bare `createServer({ middlewareMode: true })` setups are framework-author territory. Most apps should use Nuxt, Remix, SvelteKit, Astro, or TanStack Start instead. What you *will* tweak as a framework user is the externals config when deps break in SSR:

```typescript // vite.config.ts — ssr options ssr: { external: ['node-native-package'], // keep as require() in SSR bundle noExternal: ['esm-only-package'], // force-bundle into SSR output (fixes most SSR errors) target: 'node', // 'node' or 'webworker' } ```

### Dependency Pre-Bundling

Vite pre-bundles dependencies to convert CJS/UMD to ESM and reduce request count.

```typescript // vite.config.ts — optimizeDeps optimizeDeps: { include: [ 'lodash-es', // force pre-bundle known heavy deps 'cjs-package', // CJS deps that cause interop issues 'deep-lib/components/**', // glob for deep imports ], exclude: ['local-esm-package'], // must be valid ESM if excluded force: true, // ignore cache, re-optimize (temporary debugging) } ```

### Common Pitfalls

#### Dev Does Not Match Build

Dev uses esbuild/Rolldown for transforms; build uses Rolldown for bundling. CJS libraries can behave differently between the two. Always verify with `vite build && vite preview` before deploying.

#### Stale Chunks After Deployment

New builds produce new chunk hashes. Users with active sessions request old filenames that no longer exist. Vite has no built-in solution. Mitigations:

- Keep old `dist/assets/` files live for a deployment window - Catch dynamic import errors in your router and force a page reload

#### Docker and Containers

Vite binds to `localhost` by default, which is unreachable from outside a container:

```typescript // vite.config.ts — Docker/container setup server: { host: true, // bind 0.0.0.0 hmr: { clientPort: 3000 }, // if behind a reverse proxy } ```

#### Monorepo File Access

Vite restricts file serving to the project root. Packages outside root are blocked:

```typescript // vite.config.ts — monorepo file access server: { fs: { allow: ['..'], // allow parent directory (workspace root) }, } ```

### Anti-Patterns

```typescript // BAD: Setting envPrefix to '' exposes ALL env vars (including secrets) to the client envPrefix: ''

// BAD: Assuming require() works in application source code — Vite is ESM-first const lib = require('some-lib') // use import instead

// BAD: Splitting every node_module into its own chunk — creates hundreds of tiny files manualChunks(id) { if (id.includes('node_modules')) { return id.split('node_modules/')[1].split('/')[0] // one chunk per package } }

// BAD: Not externalizing peer deps in library mode — causes duplicate runtime errors // build.lib without rolldownOptions.external

// BAD: Using deprecated esbuild minifier build: { minify: 'esbuild' } // use 'oxc' (default) or 'terser'

// BAD: Mutating import.meta.hot.data by reassignment import.meta.hot.data = { count: 0 } // WRONG: must mutate properties, not reassign import.meta.hot.data.count = 0 // CORRECT ```

**Process anti-patterns:**

- **`vite preview` is NOT a production server** — it is a smoke test for the built bundle. Deploy `dist/` to a real static host (NGINX, Cloudflare Pages, Vercel static) or use a multi-stage Dockerfile. - **Expecting `vite build` to type-check** — it only transpiles. Type errors silently ship to production. Add `vite-plugin-checker` or run `tsc --noEmit` in CI. - **Shipping `@vitejs/plugin-legacy` by default** — it bloats bundles ~40%, breaks source-map bundle analyzers, and is unnecessary for the 95%+ of users on modern browsers. Gate it on real analytics, not assumption. - **Hand-rolling 30+ `resolve.alias` entries that duplicate `tsconfig.json` paths** — use `vite-tsconfig-paths` instead. Observed in Excalidraw and PostHog; avoid in new projects. - **Leaving stale `node_modules/.vite` after dep changes** — pre-bundle cache causes phantom errors. Clear it when switching branches or after patching deps.

## Quick Reference

| Pattern | When to Use | |---------|-------------| | `defineConfig` | Always — provides type inference | | `loadEnv(mode, root, ['VITE_'])` | Access env vars in config (explicit prefix) | | `vite-plugin-checker` | Any TypeScript app (fills the type-check gap) | | `vite-tsconfig-paths` | Instead of hand-rolled `resolve.alias` | | `optimizeDeps.include` | CJS deps causing interop issues | | `server.proxy` | Route API requests to backend in dev | | `server.host: true` | Docker, containers, remote access | | `server.warmup.clientFiles` | Pre-transform hot-path routes | | `build.lib` + `external` | Publishing npm packages | | `manualChunks` (object) | Vendor bundle splitting | | `vite --profile` | Debug slow dev server | | `vite build && vite preview` | Smoke-test prod bundle locally (NOT a prod server) |

## Related Skills

- `frontend-patterns` — React component patterns - `docker-patterns` — containerized dev with Vite - `nextjs-turbopack` — alternative bundler for Next.js

Intended uses

  • Configuring vite.config.ts or vite.config.js
  • Setting up environment variables or .env files
  • Configuring dev server proxy for API backends
  • Optimizing build output (chunks, minification, assets)
  • Publishing libraries with build.lib
  • Troubleshooting dependency pre-bundling or CJS/ESM interop
  • Debugging HMR, dev server, or build errors
  • Choosing or ordering Vite plugins

Implementation notes

  • Review the source instructions and adapt inputs before running the workflow.

Try it, then tell us how it went

A copied prompt does not tell us whether the task worked. Report your result after checking the output. We collect your tool and outcome, never your files or prompt.