Vite Config Cheatsheet — 60+ vite.config.ts Options with Defaults and Examples

The port the dev server listens on. If the port is already in use, Vite will automatically try the next available port unless `server.strictPort` is set to `true`.

server: {
  port: 3000,
}

Set to `"0.0.0.0"` or `true` to expose the dev server on all network interfaces, including LAN and public addresses. Required when testing on a mobile device on the same network.

server: {
  host: true,      // same as '0.0.0.0'
}

Automatically open the app in the browser when the server starts. Pass a URL string to open a specific page, e.g. `"/dashboard"` to skip the homepage.

server: {
  open: true,
  // or: open: '/dashboard',
}

Configure custom proxy rules for the dev server. Requests matching the key pattern are forwarded to the target. Use `changeOrigin: true` when the target is on a different hostname. Use `rewrite` to strip a path prefix the backend does not expect.

server: {
  proxy: {
    '/api': {
      target: 'http://localhost:3001',
      changeOrigin: true,
      rewrite: (path) => path.replace(/^\/api/, ''),
    },
    '/ws': {
      target: 'ws://localhost:3001',
      ws: true,
    },
  },
}

Configure CORS for the dev server. Set to `true` to allow all origins, or pass a `CorsOptions` object for fine-grained control. Useful when testing your dev server from a different origin.

server: {
  cors: true,
  // or fine-grained:
  // cors: {
  //   origin: 'https://example.com',
  //   methods: ['GET', 'POST'],
  // },
}

Enable or disable HMR (Hot Module Replacement). Set `hmr: false` to disable. Pass an object to configure the HMR WebSocket connection — useful when running Vite behind a reverse proxy that does not forward WebSocket connections correctly.

server: {
  hmr: {
    protocol: 'ws',
    host: 'localhost',
    port: 5173,
  },
}

Specify custom HTTP response headers for the dev server. Use to add security headers like `Cross-Origin-Opener-Policy` or to enable `SharedArrayBuffer` which requires `Cross-Origin-Embedder-Policy: require-corp`.

server: {
  headers: {
    'Cross-Origin-Opener-Policy': 'same-origin',
    'Cross-Origin-Embedder-Policy': 'require-corp',
  },
}

When set to `true`, Vite exits with an error if the configured port is already in use instead of silently trying the next port. Useful in CI environments or scripts that depend on a specific port.

server: {
  port: 3000,
  strictPort: true,
}

The port used by `vite preview`, which serves the production build locally. Separate from `server.port` to avoid conflicts when running both simultaneously.

preview: {
  port: 8080,
  open: true,
}

The browser compatibility target for the production build. `"modules"` targets browsers with native ES module support (Chrome 87+, Firefox 78+, Safari 14+). Use `"esnext"` for the latest syntax. Pass an array like `["chrome87", "firefox78", "safari14"]` to target a specific browser set. Uses esbuild transforms for syntax lowering.

build: {
  target: 'es2020',
  // or: target: ['chrome87', 'firefox78', 'safari14'],
}

The output directory for the production build, relative to the project root. Vite will empty this directory before building if `build.emptyOutDir` is `true`.

build: {
  outDir: 'dist',
}

Subdirectory inside `outDir` where generated assets (JS chunks, CSS, images) are placed. The full path of a chunk is `{outDir}/{assetsDir}/[name]-[hash].js`.

build: {
  assetsDir: 'static',   // outputs to dist/static/
}

Clears the output directory before building. Defaults to `true` when `outDir` is inside the project root, `false` when it is outside (to prevent accidental deletion). Set explicitly to `true` to always clean.

build: {
  emptyOutDir: true,
}

Controls JS minification. `"esbuild"` is the default and is very fast. `"terser"` produces slightly smaller output but is 20-40× slower. Set to `false` to disable minification entirely — useful for debugging production builds.

build: {
  minify: 'esbuild',    // fast (default)
  // minify: 'terser',  // smaller, slower
  // minify: false,     // disable for debugging
}

Generate source maps for the production build. `true` creates separate `.map` files. `"inline"` embeds the source map as a data URI in the bundle. `"hidden"` creates `.map` files without the `//# sourceMappingURL` comment — use with error monitoring tools that upload maps privately.

build: {
  sourcemap: true,
  // or 'inline' | 'hidden'
}

Directly customize the Rollup bundle configuration. Commonly used to configure `external` dependencies for libraries, `output.manualChunks` for code splitting, and `input` for multi-page apps. Full Rollup API is available.

build: {
  rollupOptions: {
    external: ['react', 'react-dom'],
    output: {
      globals: {
        react: 'React',
        'react-dom': 'ReactDOM',
      },
      manualChunks: {
        vendor: ['lodash', 'axios'],
      },
    },
  },
}

Configure Vite in library mode for publishing npm packages. Specify the entry point and output formats. Always set `rollupOptions.external` to list peer dependencies that should not be bundled.

build: {
  lib: {
    entry: 'src/index.ts',
    name: 'MyLib',
    fileName: 'my-lib',
    formats: ['es', 'cjs'],
  },
  rollupOptions: {
    external: ['react', 'react-dom'],
  },
}

When enabled (default), CSS imported by async JS chunks is split into separate CSS files. When disabled, all CSS is combined into a single file. Set to `false` when building a library to keep CSS in JS, or when you want a single CSS bundle.

build: {
  cssCodeSplit: true,   // default, split per chunk
  // cssCodeSplit: false,  // one CSS file
}

Assets smaller than this threshold (in bytes) are inlined as base64 data URIs instead of being emitted as separate files. Reduces HTTP requests for small assets at the cost of larger JS/CSS bundle size. Set to `0` to disable inlining.

build: {
  assetsInlineLimit: 8192,   // 8 KB
  // assetsInlineLimit: 0,   // never inline
}

Chunk size warning threshold in kB. Vite warns when a chunk exceeds this size. Increase the limit only if you have verified that large chunks are acceptable; better to use `rollupOptions.output.manualChunks` to split them.

build: {
  chunkSizeWarningLimit: 1000,   // 1 MB
}

When `true`, files in the `public/` directory are copied to `outDir` at the end of the build. Set to `false` when building a library — libraries do not need the public directory contents.

build: {
  copyPublicDir: false,   // useful for library builds
}

Define file system path aliases. Any import matching a key is replaced with the corresponding path value at build time. The most common use is creating a `@/` alias for the `src/` directory. Remember to add matching `paths` in `tsconfig.json` — Vite and TypeScript alias configs are independent.

import path from 'path';
import { defineConfig } from 'vite';

export default defineConfig({
  resolve: {
    alias: {
      '@': path.resolve(__dirname, './src'),
      '@components': path.resolve(__dirname, './src/components'),
      '@utils': path.resolve(__dirname, './src/utils'),
    },
  },
});

File extensions tried when resolving bare imports without an extension. The default list covers the common TypeScript and JavaScript extensions. Avoid adding `.vue`, `.svelte`, etc. here — framework plugins handle those.

resolve: {
  extensions: ['.mjs', '.js', '.ts', '.jsx', '.tsx', '.json'],
}

Conditions checked against the `exports` field in `package.json`. Vite uses `"browser"` in the client build and `"node"` in SSR. Add custom conditions to resolve package entry points differently per environment.

resolve: {
  conditions: ['module', 'browser'],
}

Force specific packages to resolve to the same instance. Prevents duplicate instances in the module graph, which can cause issues with singletons (React context, Vue reactivity system). Useful when using local packages via `file:` links or monorepos.

resolve: {
  dedupe: ['react', 'react-dom'],
}

Array of Vite plugins. Plugins are applied in order. Framework plugins (e.g. `@vitejs/plugin-react`) should generally come first. You can return `null` or `false` inside the array to conditionally skip a plugin.

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

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

Load a plugin only in specific modes by using a ternary or logical AND inside the plugins array. `false` and `null` values are filtered out by Vite. The `command` and `mode` parameters from `defineConfig` let you enable plugins only for builds or only in production.

export default defineConfig(({ command, mode }) => ({
  plugins: [
    react(),
    mode === 'production' && vitePWA(),  // only in prod
    command === 'build' && bundleAnalyzer(),
  ].filter(Boolean),
}));

Helper function that provides TypeScript autocomplete for the config object. Pass a function to receive `command` (`"serve"` | `"build"`), `mode` (e.g. `"development"` | `"production"`), and `isSsrBuild` — useful for environment-aware configuration.

import { defineConfig } from 'vite';

export default defineConfig(({ command, mode }) => {
  return {
    build: {
      sourcemap: command === 'serve',   // sourcemap in dev only
    },
  };
});

Define global constant replacements. Values are replaced as-is in the source code (not quoted). `import.meta.env.VITE_*` should be preferred for runtime env vars, but `define` is useful for build-time constants like feature flags and version strings.

define: {
  __APP_VERSION__: JSON.stringify('1.2.3'),
  __FEATURE_FLAG__: true,
}

The public base path when served in development or production. Must include a trailing slash. Set to `"/sub-path/"` when deploying to a sub-directory (GitHub Pages, Netlify sub-paths). All asset URLs will be prefixed with this value.

export default defineConfig({
  base: '/my-app/',   // deployed to example.com/my-app/
});

Configure CSS Modules behavior. `localsConvention: "camelCaseOnly"` converts dashed class names to camelCase in JS. `generateScopedName` lets you customize the scoped class name format — useful for readable class names in development.

css: {
  modules: {
    localsConvention: 'camelCaseOnly',
    generateScopedName: '[name]__[local]__[hash:5]',
  },
}

Pass options to CSS preprocessors (Sass, Less, Stylus). The most common use is injecting global variables or imports so they are available in every style file without explicit imports.

css: {
  preprocessorOptions: {
    scss: {
      additionalData: '@use "@/styles/variables" as *;',
    },
    less: {
      globalVars: {
        primaryColor: '#1890ff',
      },
    },
  },
}

Inline PostCSS configuration or a path to a PostCSS config file. Use to configure plugins like `autoprefixer` and `cssnano`. When specified here, Vite does not search for an external `postcss.config.js` file.

import autoprefixer from 'autoprefixer';

css: {
  postcss: {
    plugins: [
      autoprefixer(),
    ],
  },
}

Enable CSS source maps in development. When enabled, browser DevTools shows the original CSS file location instead of the transformed output. Has a slight performance cost — leave disabled unless you are actively debugging CSS.

css: {
  devSourcemap: true,
}

Force-include specific dependencies in the pre-bundling step. Useful for dependencies that are not automatically detected (e.g. deeply nested imports, dynamic imports). Entries must be resolvable import paths, not file system paths.

optimizeDeps: {
  include: ['lodash-es', 'some-cjs-dep > nested-dep'],
}

Exclude specific dependencies from pre-bundling. Use for ESM-native packages that have circular dependencies or ship broken CJS builds that esbuild handles incorrectly. Also useful for large packages where you only use a small part.

optimizeDeps: {
  exclude: ['@ffmpeg/ffmpeg', 'some-esm-native-dep'],
}

Force re-run of dependency pre-bundling, ignoring the cached result. Use this temporarily when the cache seems stale. Do not commit this to `vite.config.ts` — it slows down dev startup for everyone. Use the CLI flag `vite --force` for a one-time reset instead.

optimizeDeps: {
  force: true,  // ⚠ temporary only, don't commit
}

Options passed to esbuild for individual file transforms. `esbuild.jsxInject` auto-imports React so you do not need `import React from "react"` in every file. `esbuild.drop` removes `console` or `debugger` calls in production. Set to `false` to disable esbuild transforms entirely.

esbuild: {
  jsxInject: `import React from 'react'`,
  drop: ['console', 'debugger'],  // prod only
  target: 'es2020',
}

Force specified dependencies to be bundled into the SSR output instead of being externalized. Useful for packages that do not ship a valid CJS build or use browser-specific globals that need to be transformed.

ssr: {
  noExternal: ['some-esm-only-package', /^@my-org//],
}