Shared Options

root

  • Type: string

  • Default: process.cwd()

    Project root directory (where index.html is located). Can be an absolute path, or a path relative from the location of the config file itself.

    See Project Root for more details.

base

  • Type: string

  • Default: /

    Base public path when served in development or production. Valid values include:

    • Absolute URL pathname, e.g. /foo/
    • Full URL, e.g. https://foo.com/
    • Empty string or ./ (for embedded deployment)

    See Public Base Path for more details.

mode

  • Type: string

  • Default: 'development' for serve, 'production' for build

    Specifying this in config will override the default mode for both serve and build. This value can also be overridden via the command line --mode option.

    See Env Variables and Modes for more details.

define

  • Type: Record<string, string>

    Define global constant replacements. Entries will be defined as globals during dev and statically replaced during build.

    • Starting from 2.0.0-beta.70, string values will be used as raw expressions, so if defining a string constant, it needs to be explicitly quoted (e.g. with JSON.stringify).

    • Replacements are performed only when the match is surrounded by word boundaries (\b).

    Because it’s implemented as straightforward text replacements without any syntax analyzation, we recommend using define for CONSTANTS only.

    For example, process.env.FOO and __APP_VERSION__ are good fits. But process or global should not be put into this option. Variables can be shimmed or polyfilled instead.

plugins

  • Type: (Plugin | Plugin[])[]

    Array of plugins to use. Falsy plugins are ignored and arrays of plugins are flattened. See Plugin API for more details on Vite plugins.

publicDir

  • Type: string

  • Default: "public"

    Directory to serve as plain static assets. Files in this directory are served at / during dev and copied to the root of outDir during build, and are always served or copied as-is without transform. The value can be either an absolute file system path or a path relative to project root.

    See The public Directory for more details.

cacheDir

  • Type: string

  • Default: "node_modules/.vite"

    Directory to save cache files. Files in this directory are pre-bundled deps or some other cache files that generated by vite, which can improve the performance. You can use --force flag or manually delete the directory to regenerate the cache files. The value can be either an absolute file system path or a path relative to project root.

resolve.alias

  • Type:Record<string, string> | Array<{ find: string | RegExp, replacement: string }>

    Will be passed to @rollup/plugin-alias as its entries option. Can either be an object, or an array of { find, replacement } pairs.

    When aliasing to file system paths, always use absolute paths. Relative alias values will be used as-is and will not be resolved into file system paths.

    More advanced custom resolution can be achieved through plugins.

resolve.dedupe

  • Type: string[]

    If you have duplicated copies of the same dependency in your app (likely due to hoisting or linked packages in monorepos), use this option to force Vite to always resolve listed dependencies to the same copy (from project root).

resolve.conditions

  • Type: string[]

    Additional allowed conditions when resolving Conditional Exports from a package.

    A package with conditional exports may have the following exports field in its package.json:

    1. {
    2.   "exports": {
    3.     ".": {
    4.       "import": "./index.esm.js",
    5.       "require": "./index.cjs.js"
    6.     }
    7.   }
    8. }

    Here, import and require are “conditions”. Conditions can be nested and should be specified from most specific to least specific.

    Vite has a list of “allowed conditions” and will match the first condition that is in the allowed list. The default allowed conditions are: import, module, browser, default, and production/development based on current mode. The resolve.conditions config option allows specifying additional allowed conditions.

resolve.mainFields

  • Type: string[]

  • Default: ['module', 'jsnext:main', 'jsnext']

    List of fields in package.json to try when resolving a package’s entry point. Note this takes lower precedence than conditional exports resolved from the exports field: if an entry point is successfully resolved from exports, the main field will be ignored.

resolve.extensions

  • Type: string[]

  • Default: ['.mjs', '.js', '.ts', '.jsx', '.tsx', '.json']

    List of file extensions to try for imports that omit extensions. Note it is NOT recommended to omit extensions for custom import types (e.g. .vue) since it can interfere with IDE and type support.

css.modules

  • Type:

    1. interface CSSModulesOptions {
    2.   scopeBehaviour?: 'global' | 'local'
    3.   globalModulePaths?: string[]
    4.   generateScopedName?:
    5.     | string
    6.     | ((name: string, filename: string, css: string) => string)
    7.   hashPrefix?: string
    8.   /**
    9.    * default: 'camelCaseOnly'
    10.    */
    11.   localsConvention?: 'camelCase' | 'camelCaseOnly' | 'dashes' | 'dashesOnly'
    12. }

    Configure CSS modules behavior. The options are passed on to postcss-modules.

css.postcss

  • Type: string | (postcss.ProcessOptions & { plugins?: postcss.Plugin[] })

    Inline PostCSS config (expects the same format as postcss.config.js), or a custom path to search PostCSS config from (default is project root). The search is done using postcss-load-config.

    Note if an inline config is provided, Vite will not search for other PostCSS config sources.

css.preprocessorOptions

  • Type: Record<string, object>

    Specify options to pass to CSS pre-processors. Example:

    1. export default {
    2.   css: {
    3.     preprocessorOptions: {
    4.       scss: {
    5.         additionalData: `$injectedColor: orange;`
    6.       }
    7.     }
    8.   }
    9. }

json.namedExports

  • Type: boolean

  • Default: true

    Whether to support named imports from .json files.

json.stringify

  • Type: boolean

  • Default: false

    If set to true, imported JSON will be transformed into export default JSON.parse("...") which is significantly more performant than Object literals, especially when the JSON file is large.

    Enabling this disables named imports.

esbuild

  • Type: ESBuildOptions | false

    ESBuildOptions extends ESbuild’s own transform options. The most common use case is customizing JSX:

    1. export default {
    2.   esbuild: {
    3.     jsxFactory: 'h',
    4.     jsxFragment: 'Fragment'
    5.   }
    6. }

    By default, ESBuild is applied to ts, jsx and tsx files. You can customize this with esbuild.include and esbuild.exclude, both of which expects type of string | RegExp | (string | RegExp)[].

    In addition, you can also use esbuild.jsxInject to automatically inject JSX helper imports for every file transformed by ESBuild:

    1. export default {
    2.   esbuild: {
    3.     jsxInject: `import React from 'react'`
    4.   }
    5. }

    Set to false to disable ESbuild transforms.

assetsInclude

  • Type: string | RegExp | (string | RegExp)[]

  • Related: Static Asset Handling

    Specify additional file types to be treated as static assets so that:

    • They will be excluded from the plugin transform pipeline when referenced from HTML or directly requested over fetch or XHR.

    • Importing them from JS will return their resolved URL string (this can be overwritten if you have a enforce: 'pre' plugin to handle the asset type differently).

    The built-in asset type list can be found here.

logLevel

  • Type: 'info' | 'warn' | 'error' | 'silent'

    Adjust console output verbosity. Default is 'info'.

clearScreen

  • Type: boolean

  • Default: true

    Set to false to prevent Vite from clearing the terminal screen when logging certain messages. Via command line, use --clearScreen false.