gt-agent-company/.agents/skills/vite/references/core-config.md

name, description

name	description
core-config	Vite configuration file setup, defineConfig helper, conditional and async configs

Vite Configuration

Vite automatically resolves a config file named vite.config.* in the project root.

Basic Configuration

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

export default defineConfig({
  // config options
})

Use defineConfig for TypeScript intellisense. Alternatively, use JSDoc annotations:

/** @type {import('vite').UserConfig} */
export default {
  // config options
}

Conditional Config

Export a function to conditionally determine options based on command, mode, or build type:

import { defineConfig } from 'vite'

export default defineConfig(({ command, mode, isSsrBuild, isPreview }) => {
  if (command === 'serve') {
    // dev specific config
    return {
      define: {
        __DEV__: true
      }
    }
  } else {
    // build specific config
    return {
      define: {
        __DEV__: false
      }
    }
  }
})

• command is 'serve' during dev (vite, vite dev, vite serve) and 'build' for production
• mode defaults to 'development' for serve, 'production' for build

Async Config

import { defineConfig } from 'vite'

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

Key Configuration Options

Root and Base

export default defineConfig({
  root: './src',           // Project root directory (where index.html is)
  base: '/my-app/',        // Public base path for assets
  publicDir: 'public',     // Static assets directory
  cacheDir: 'node_modules/.vite'  // Cache directory
})

Resolve Aliases

import { resolve } from 'path'

export default defineConfig({
  resolve: {
    alias: {
      '@': resolve(__dirname, 'src'),
      '~': resolve(__dirname, 'src/components')
    },
    // File extensions to try for imports without extension
    extensions: ['.mjs', '.js', '.mts', '.ts', '.jsx', '.tsx', '.json']
  }
})

Define Global Constants

export default defineConfig({
  define: {
    __APP_VERSION__: JSON.stringify('1.0.0'),
    __API_URL__: JSON.stringify('https://api.example.com')
  }
})

Values must be JSON-serializable or a single identifier. Add TypeScript declarations:

// vite-env.d.ts
declare const __APP_VERSION__: string
declare const __API_URL__: string

JSON Handling

export default defineConfig({
  json: {
    namedExports: true,  // Support named imports from JSON
    stringify: 'auto'    // Stringify large JSON for performance
  }
})

Using Environment Variables in Config

Variables from .env files are NOT automatically available in config. Use loadEnv:

import { defineConfig, loadEnv } from 'vite'

export default defineConfig(({ mode }) => {
  // Load env vars from .env files
  const env = loadEnv(mode, process.cwd(), '')
  
  return {
    define: {
      __APP_ENV__: JSON.stringify(env.APP_ENV)
    },
    server: {
      port: env.APP_PORT ? Number(env.APP_PORT) : 5173
    }
  }
})

Specifying Config File

vite --config my-config.ts

Config Loading Methods

# Default: bundle with Rolldown (may have issues in monorepos)
vite

# Use module runner (no temp file, transforms on the fly)
vite --configLoader runner

# Use native runtime (requires Node.js with TypeScript support)
vite --configLoader native