Skip to content
On this page

Beyond Fast

ViteConf 2023

Watch the replay!

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 to the current working directory.

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, any>

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

  • 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).

  • To be consistent with esbuild behavior, expressions must either be a JSON object (null, boolean, number, string, array, or object) or a single identifier.

  • Replacements are performed only when the match isn't surrounded by other letters, numbers, _ or $.

WARNING

Because it's implemented as straightforward text replacements without any syntax analysis, 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.

NOTE

For TypeScript users, make sure to add the type declarations in the env.d.ts or vite-env.d.ts file to get type checks and Intellisense.

Example:

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

NOTE

Since dev and build implement define differently, we should avoid some use cases to avoid inconsistency.

Example:

js
const obj = {
  __NAME__, // Don't define object shorthand property names
  __KEY__: value, // Don't define object key
}

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. See Plugin 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 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.

Defining publicDir as false disables this feature.

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 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 its entries 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 through plugins.

Using with SSR

If you have configured aliases for SSR externalized dependencies, you may want to alias the actual node_modules packages. Both Yarn and pnpm support aliasing via the npm: prefix.

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).

SSR + ESM

For SSR builds, deduplication does not work for ESM build outputs configured from build.rollupOptions.output. A workaround is to use CJS build outputs until ESM has better plugin support for module loading.

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:

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

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.

Resolving subpath exports

Export keys ending with "/" is deprecated by Node and may not work well. Please contact the package author to use * subpath patterns instead.

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.browserField

  • Type: boolean
  • Default: true
  • Deprecated

Whether to enable resolving to browser field.

In future, resolve.mainFields's default value will be ['browser', 'module', 'jsnext:main', 'jsnext'] and this option will be removed.

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 is NOT recommended to omit extensions for custom import types (e.g. .vue) since it can interfere with IDE and type support.

  • 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).

css.modules

  • Type:
    ts
    interface CSSModulesOptions {
      scopeBehaviour?: 'global' | 'local'
      globalModulePaths?: RegExp[]
      generateScopedName?:
        | string
        | ((name: string, filename: string, css: string) => string)
      hashPrefix?: string
      /**
       * default: null
       */
      localsConvention?:
        | 'camelCase'
        | 'camelCaseOnly'
        | 'dashes'
        | 'dashesOnly'
        | null
    }

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

This option doesn't have any effect when using Lightning 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 as postcss.config.js. But for plugins property, only array format can be used.

The search is done using postcss-load-config and only the supported config file names are loaded.

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 preprocessors can be found in their respective documentation:

  • sass/scss - Options.
  • less - Options.
  • styl/stylus - Only define is supported, which can be passed as an object.

All preprocessor options also support the additionalData option, which 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:

js
export default defineConfig({
  css: {
    preprocessorOptions: {
      scss: {
        additionalData: `$injectedColor: orange;`,
      },
      less: {
        math: 'parens-division',
      },
      styl: {
        define: {
          $specialColor: new stylus.nodes.RGBA(51, 197, 255, 1),
        },
      },
    },
  },
})

css.devSourcemap

Whether to enable sourcemaps during dev.

css.transformer

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

Selects the engine used for CSS processing. Check out Lightning CSS for more information.

css.lightningcss

js
import type {
  CSSModulesConfig,
  Drafts,
  Features,
  NonStandard,
  PseudoClasses,
  Targets,
} from 'lightningcss'
js
{
  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 in the Lightning CSS repo.

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:

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

By default, esbuild is applied to ts, jsx and tsx files. You can customize this with esbuild.include and esbuild.exclude, which can be a regex, a picomatch pattern, or an array of either.

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

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

When build.minify is true, all minify optimizations are applied by default. To disable certain aspects of it, set any of esbuild.minifyIdentifiers, esbuild.minifySyntax, or esbuild.minifyWhitespace options to false. Note the esbuild.minify option can't be used to override build.minify.

Set to false to disable esbuild transforms.

assetsInclude

Specify additional picomatch 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 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.

Example:

js
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's createLogger API to get the default logger and customize it to, for example, change the message or filter out certain warnings.

js
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 to false to prevent Vite from clearing the terminal screen when logging certain messages. Via command line, use --clearScreen false.

envDir

  • Type: string
  • Default: root

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

See here for more about environment files.

envPrefix

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

Env variables starting with envPrefix will be exposed to your client source code via import.meta.env.

SECURITY NOTES

envPrefix should not be set as '', which will expose all your env variables and cause unexpected leaking of sensitive information. Vite will throw an error when detecting ''.

If you would like to expose an unprefixed variable, you can use define to expose it:

js
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), a Multi Page Application (MPA), or Custom Application (SSR and frameworks with custom HTML handling):

  • 'spa': include HTML middlewares and use SPA fallback. Configure sirv with single: true in preview
  • 'mpa': include HTML middlewares
  • 'custom': don't include HTML middlewares

Learn more in Vite's SSR guide. Related: server.middlewareMode.

Released under the MIT License. (1dda64fc)