Vite Syntax Config

vite-syntax-config

Quick Reference

Config File Resolution Order

Vite automatically resolves the config file from the project root in this order:

Shared Options Summary

Critical Warnings

NEVER set envPrefix to '' (empty string) -- this exposes ALL environment variables (including DB_PASSWORD, SECRET_KEY, etc.) to client-side code via import.meta.env.

ALWAYS use defineConfig() -- it provides full TypeScript IntelliSense and type checking for all config options, even in plain .js files.

ALWAYS use JSON.stringify() when setting string values in define -- values are used as raw code expressions, so bare strings cause syntax errors.

NEVER put sensitive data in VITE_-prefixed env variables -- they are embedded in the client bundle and visible to anyone.

Config Patterns

Basic Config with defineConfig()

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

export default defineConfig({
  root: './src',
  base: '/my-app/',
  plugins: [],
})

Conditional Config (command/mode)

ALWAYS use a function export when config differs between serve (dev) and build (production):

export default defineConfig(({ command, mode, isSsrBuild, isPreview }) => {
  if (command === 'serve') {
    return {
      // Dev-only config
    }
  } else {
    // command === 'build'
    return {
      // Production-only config
    }
  }
})

Parameters available in the function:

• command: 'serve' (dev server) or 'build' (production build)
• mode: 'development', 'production', or custom mode string
• isSsrBuild: boolean -- true during SSR builds
• isPreview: boolean -- true during vite preview

Async Config

Use async config when you need to fetch data or run async operations before configuring:

export default defineConfig(async ({ command, mode }) => {
  const data = await asyncFunction()
  return {
    // config using fetched data
  }
})

Loading Environment Variables in Config

Environment variables are NOT available via process.env in the config file by default. ALWAYS use loadEnv() to access them:

import { defineConfig, loadEnv } from 'vite'

export default defineConfig(({ mode }) => {
  // Load env from envDir (default: root). Third arg '' loads ALL env vars, not just VITE_-prefixed
  const env = loadEnv(mode, process.cwd(), '')
  return {
    define: {
      __APP_ENV__: JSON.stringify(env.APP_ENV),
    },
  }
})

loadEnv(mode, envDir, prefixes) parameters:

• mode: Which .env.[mode] file to load
• envDir: Directory containing .env files
• prefixes: String or array of prefixes to filter (default: 'VITE_'). Use '' to load all.

Decision Trees

Which Config Pattern to Use?

Need different config for dev vs build?
├── YES → Use conditional: defineConfig(({ command }) => { ... })
│         Need env vars in config?
│         ├── YES → Use loadEnv() inside the function
│         └── NO  → Return config object per command
├── NO, but need async operations?
│   └── YES → Use async: defineConfig(async () => { ... })
└── NO → Use static: defineConfig({ ... })

Which appType to Use?

Building a Single Page Application (client-side routing)?
├── YES → appType: 'spa' (default, includes SPA fallback middleware)
├── NO, Multi-Page Application (separate HTML files)?
│   └── YES → appType: 'mpa' (HTML middleware, no SPA fallback)
└── NO, Custom server (Express, Fastify, etc.)?
    └── YES → appType: 'custom' (no HTML middleware at all)

Transformer Options (v8+)

oxc (replaces esbuild in v8)

Vite 8+ uses Oxc for JSX/TS transformation. Applied to .ts, .jsx, .tsx by default:

export default defineConfig({
  oxc: {
    jsx: {
      runtime: 'classic',
      pragma: 'h',
      pragmaFrag: 'Fragment',
    },
  },
})

Set oxc: false to disable the Oxc transform entirely.

esbuild (deprecated in v8)

In Vite 8+, esbuild config is converted internally to oxc. ALWAYS use the oxc option directly when targeting Vite 8+. For Vite 6/7, use esbuild as before.

Custom Logger

Create a filtered logger to suppress specific warnings:

import { createLogger, defineConfig } from 'vite'

const logger = createLogger()
const loggerWarn = logger.warn
logger.warn = (msg, options) => {
  if (msg.includes('vite:css') && msg.includes(' is empty')) return
  loggerWarn(msg, options)
}

export default defineConfig({
  customLogger: logger,
})

Reference Links

• references/config-options.md -- Complete shared config options with types, defaults, and descriptions
• references/examples.md -- Working code examples for conditional config, async config, loadEnv, and plugin arrays
• references/anti-patterns.md -- Common configuration mistakes and how to avoid them

Official Sources

• https://vite.dev/config/
• https://vite.dev/config/shared-options
• https://vite.dev/guide/