Shared Options​

Unless noted, the options in this section are applied to all dev, build, and preview.

root​

• Type:string
• Default:process.cwd()

Project root directory (whereindex.html is located). Can be an absolute path, or a path relative to the current working directory.

SeeProject Root for more details.

base​

• Type:string
• Default:/
• Related:server.origin

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

• Absolute URL pathname, e.g./foo/
• Full URL, e.g.https://bar.com/foo/ (The origin part won't be used in development so the value is the same as/foo/)
• Empty string or./ (for embedded deployment)

SeePublic Base Path for more details.

mode​

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

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

SeeEnv Variables and Modes for more details.

define​

• Type:Record<string, any>

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

Vite usesesbuild defines to perform replacements, so value expressions must be a string that contains a JSON-serializable value (null, boolean, number, string, array, or object) or a single identifier. For non-string values, Vite will automatically convert it to a string withJSON.stringify.

Example:

export default defineConfig({  define: {    __APP_VERSION__:JSON.stringify('v1.0.0'),    __API_URL__:'window.__backend_api_url',  },})

// vite-env.d.tsdeclare const __APP_VERSION__: string

plugins​

• Type:(Plugin | Plugin[] | Promise<Plugin | Plugin[]>)[]

Array of plugins to use. Falsy plugins are ignored and arrays of plugins are flattened. If a promise is returned, it would be resolved before running. SeePlugin API for more details on Vite plugins.

publicDir​

• Type:string | false
• Default:"public"

Directory to serve as plain static assets. Files in this directory are served at/ during dev and copied to the root ofoutDir 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.

DefiningpublicDir asfalse disables this feature.

SeeThepublic 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 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. Default to.vite when no package.json is detected.

resolve.alias​

• Type:Record<string, string> | Array<{ find: string | RegExp, replacement: string, customResolver?: ResolverFunction | ResolverObject }>

Will be passed to@rollup/plugin-alias as itsentries option. Can either be an object, or an array of{ find, replacement, customResolver } 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 throughplugins.

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[]
• Default:['module', 'browser', 'development|production'] (defaultClientConditions)

Additional allowed conditions when resolvingConditional Exports from a package.

A package with conditional exports may have the followingexports field in itspackage.json:

{  "exports": {    ".": {      "import":"./index.mjs",      "require":"./index.js"    }  }}

Here,import andrequire are "conditions". Conditions can be nested and should be specified from most specific to least specific.

development|production is a special value that is replaced withproduction ordevelopment depending on the value ofprocess.env.NODE_ENV. It is replaced withproduction whenprocess.env.NODE_ENV === 'production' anddevelopment otherwise.

Note thatimport,require,default conditions are always applied if the requirements are met.

resolve.mainFields​

• Type:string[]
• Default:['browser', 'module', 'jsnext:main', 'jsnext'] (defaultClientMainFields)

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

resolve.extensions​

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

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

resolve.preserveSymlinks​

• Type:boolean
• Default:false

Enabling this setting causes vite to determine file identity by the original file path (i.e. the path without following symlinks) instead of the real file path (i.e. the path after following symlinks).

• Related:esbuild#preserve-symlinks,webpack#resolve.symlinks

html.cspNonce​

• Type:string
• Related:Content Security Policy (CSP)

A nonce value placeholder that will be used when generating script / style tags. Setting this value will also generate a meta tag with nonce value.

css.modules​

• Type:
  ts

  interface CSSModulesOptions {  getJSON?: (    cssFileName: string,    json: Record<string,string>,    outputFileName: string,  )=> void  scopeBehaviour?: 'global' | 'local'  globalModulePaths?: RegExp[]  exportGlobals?: boolean  generateScopedName?:    | string    | ((name: string,filename: string,css: string)=> string)  hashPrefix?: string  /**   * default: undefined   */  localsConvention?:    | 'camelCase'    | 'camelCaseOnly'    | 'dashes'    | 'dashesOnly'    | ((        originalClassName: string,        generatedClassName: string,        inputFile: string,      )=> string)}

Configure CSS modules behavior. The options are passed on topostcss-modules.

This option doesn't have any effect when usingLightning CSS. If enabled,css.lightningcss.cssModules should be used instead.

css.postcss​

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

Inline PostCSS config or a custom directory to search PostCSS config from (default is project root).

For inline PostCSS config, it expects the same format aspostcss.config.js. But forplugins property, onlyarray format can be used.

The search is done usingpostcss-load-config and only the supported config file names are loaded. Config files outside the workspace root (or theproject root if no workspace is found) are not searched by default. You can specify a custom path outside of the root to load the specific config file instead if needed.

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. The file extensions are used as keys for the options. The supported options for each preprocessor can be found in their respective documentation:

• sass/scss:
  • Usessass-embedded if installed, otherwise usessass. For the best performance, it's recommended to install thesass-embedded package.
  • Options
• less:Options.
• styl/stylus: Onlydefine is supported, which can be passed as an object.

Example:

export default defineConfig({  css: {    preprocessorOptions: {      less: {        math:'parens-division',      },      styl: {        define: {          $specialColor:new stylus.nodes.RGBA(51,197,255,1),        },      },      scss: {        importers: [          // ...        ],      },    },  },})

css.preprocessorOptions[extension].additionalData​

• Type:string | ((source: string, filename: string) => (string | { content: string; map?: SourceMap }))

This option can be used to inject extra code for each style content. Note that if you include actual styles and not just variables, those styles will be duplicated in the final bundle.

Example:

export default defineConfig({  css: {    preprocessorOptions: {      scss: {        additionalData:`$injectedColor: orange;`,      },    },  },})

css.preprocessorMaxWorkers​

• Type:number | true
• Default:true

Specifies the maximum number of threads CSS preprocessors can use.true means up to the number of CPUs minus 1. When set to0, Vite will not create any workers and will run the preprocessors in the main thread.

Depending on the preprocessor options, Vite may run the preprocessors on the main thread even if this option is not set to0.

css.devSourcemap​

• Experimental:Give Feedback
• Type:boolean
• Default:false

Whether to enable sourcemaps during dev.

css.transformer​

• Experimental:Give Feedback
• Type:'postcss' | 'lightningcss'
• Default:'postcss'

Selects the engine used for CSS processing. Check outLightning CSS for more information.

css.lightningcss​

• Experimental:Give Feedback
• Type:

import type {  CSSModulesConfig,  Drafts,  Features,  NonStandard,  PseudoClasses,  Targets,}from 'lightningcss'

{  targets?: Targets  include?: Features  exclude?: Features  drafts?: Drafts  nonStandard?: NonStandard  pseudoClasses?: PseudoClasses  unusedSymbols?: string[]  cssModules?: CSSModulesConfig,  // ...}

Configures Lightning CSS. Full transform options can be found inthe Lightning CSS repo.

json.namedExports​

• Type:boolean
• Default:true

Whether to support named imports from.json files.

json.stringify​

• Type:boolean | 'auto'
• Default:'auto'

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

If set to'auto', the data will be stringified only ifthe data is bigger than 10kB.

esbuild​

• Type:ESBuildOptions | false

ESBuildOptions extendsesbuild's own transform options. The most common use case is customizing JSX:

export default defineConfig({  esbuild: {    jsxFactory:'h',    jsxFragment:'Fragment',  },})

By default, esbuild is applied tots,jsx andtsx files. You can customize this withesbuild.include andesbuild.exclude, which can be a regex, apicomatch pattern, or an array of either.

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

export default defineConfig({  esbuild: {    jsxInject:`import React from 'react'`,  },})

Whenbuild.minify istrue, all minify optimizations are applied by default. To disablecertain aspects of it, set any ofesbuild.minifyIdentifiers,esbuild.minifySyntax, oresbuild.minifyWhitespace options tofalse. Note theesbuild.minify option can't be used to overridebuild.minify.

Set tofalse to disable esbuild transforms.

assetsInclude​

• Type:string | RegExp | (string | RegExp)[]
• Related:Static Asset Handling

Specify additionalpicomatch patterns to be treated as static assets so that:

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

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

The built-in asset type list can be foundhere.

Example:

export default defineConfig({  assetsInclude: ['**/*.gltf'],})

logLevel​

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

Adjust console output verbosity. Default is'info'.

customLogger​

• Type:
  ts

  interface Logger {  info(msg: string,options?: LogOptions): void  warn(msg: string,options?: LogOptions): void  warnOnce(msg: string,options?: LogOptions): void  error(msg: string,options?: LogErrorOptions): void  clearScreen(type: LogType): void  hasErrorLogged(error: Error | RollupError): boolean  hasWarned: boolean}

Use a custom logger to log messages. You can use Vite'screateLogger API to get the default logger and customize it to, for example, change the message or filter out certain warnings.

import {
createLogger
,
defineConfig
 }from 'vite'const
logger
 =
createLogger
()const
loggerWarn
 =
logger
.
warn
logger
.
warn
 = (
msg
,
options
)=> {  // Ignore empty CSS files warning  if (
msg
.
includes
('vite:css')&&
msg
.
includes
(' is empty'))return
loggerWarn
(
msg
,
options
)}export default
defineConfig
({
customLogger
:
logger
,})

clearScreen​

• Type:boolean
• Default:true

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

envDir​

• Type:string | false
• Default:root

The directory from which.env files are loaded. Can be an absolute path, or a path relative to the project root.false will disable the.env file loading.

Seehere for more about environment files.

envPrefix​

• Type:string | string[]
• Default:VITE_

Env variables starting withenvPrefix will be exposed to your client source code viaimport.meta.env.

define: {  'import.meta.env.ENV_VARIABLE':JSON.stringify(process.env.ENV_VARIABLE)}

appType​

• Type:'spa' | 'mpa' | 'custom'
• Default:'spa'

Whether your application is a Single Page Application (SPA), aMulti Page Application (MPA), or Custom Application (SSR and frameworks with custom HTML handling):

• 'spa': include HTML middlewares and use SPA fallback. Configuresirv withsingle: true in preview
• 'mpa': include HTML middlewares
• 'custom': don't include HTML middlewares

Learn more in Vite'sSSR guide. Related:server.middlewareMode.

future​

• Type:Record<string, 'warn' | undefined>
• Related:Breaking Changes

Enable future breaking changes to prepare for a smooth migration to the next major version of Vite. The list may be updated, added, or removed at any time as new features are developed.

See theBreaking Changes page for details of the possible options.