|
| 1 | +# Shared Options |
| 2 | + |
| 3 | +## root |
| 4 | + |
| 5 | +- **Type:** `string` |
| 6 | +- **Default:** `process.cwd()` |
| 7 | + |
| 8 | +Project root directory (where `index.html` is located). Can be an absolute path, or a path relative to the location of the config file itself. |
| 9 | + |
| 10 | +See [Project Root](/guide/#index-html-and-project-root) for more details. |
| 11 | + |
| 12 | +## base |
| 13 | + |
| 14 | +- **Type:** `string` |
| 15 | +- **Default:** `/` |
| 16 | + |
| 17 | +Base public path when served in development or production. Valid values include: |
| 18 | + |
| 19 | +- Absolute URL pathname, e.g. `/foo/` |
| 20 | +- Full URL, e.g. `https://foo.com/` |
| 21 | +- Empty string or `./` (for embedded deployment) |
| 22 | + |
| 23 | +See [Public Base Path](/guide/build#public-base-path) for more details. |
| 24 | + |
| 25 | +## mode |
| 26 | + |
| 27 | +- **Type:** `string` |
| 28 | +- **Default:** `'development'` for serve, `'production'` for build |
| 29 | + |
| 30 | +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. |
| 31 | + |
| 32 | +See [Env Variables and Modes](/guide/env-and-mode) for more details. |
| 33 | + |
| 34 | +## define |
| 35 | + |
| 36 | +- **Type:** `Record<string, string>` |
| 37 | + |
| 38 | +Define global constant replacements. Entries will be defined as globals during dev and statically replaced during build. |
| 39 | + |
| 40 | +- 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`). |
| 41 | + |
| 42 | +- To be consistent with [esbuild behavior](https://esbuild.github.io/api/#define), expressions must either be a JSON object (null, boolean, number, string, array, or object) or a single identifier. |
| 43 | + |
| 44 | +- Replacements are performed only when the match isn't surrounded by other letters, numbers, `_` or `$`. |
| 45 | + |
| 46 | +::: warning |
| 47 | +Because it's implemented as straightforward text replacements without any syntax analysis, we recommend using `define` for CONSTANTS only. |
| 48 | + |
| 49 | +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. |
| 50 | +::: |
| 51 | + |
| 52 | +::: tip NOTE |
| 53 | +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. |
| 54 | + |
| 55 | +Example: |
| 56 | + |
| 57 | +```ts |
| 58 | +// vite-env.d.ts |
| 59 | +declare const __APP_VERSION__: string |
| 60 | +``` |
| 61 | +
|
| 62 | +::: |
| 63 | +
|
| 64 | +::: tip NOTE |
| 65 | +Since dev and build implement `define` differently, we should avoid some use cases to avoid inconsistency. |
| 66 | +
|
| 67 | +Example: |
| 68 | +
|
| 69 | +```js |
| 70 | +const obj = { |
| 71 | + __NAME__, // Don't define object shorthand property names |
| 72 | + __KEY__: value // Don't define object key |
| 73 | +} |
| 74 | +``` |
| 75 | + |
| 76 | +::: |
| 77 | + |
| 78 | +## plugins |
| 79 | + |
| 80 | +- **Type:** `(Plugin | Plugin[])[]` |
| 81 | + |
| 82 | +Array of plugins to use. Falsy plugins are ignored and arrays of plugins are flattened. See [Plugin API](/guide/api-plugin) for more details on Vite plugins. |
| 83 | + |
| 84 | +## publicDir |
| 85 | + |
| 86 | +- **Type:** `string | false` |
| 87 | +- **Default:** `"public"` |
| 88 | + |
| 89 | +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. |
| 90 | + |
| 91 | +Defining `publicDir` as `false` disables this feature. |
| 92 | + |
| 93 | +See [The `public` Directory](/guide/assets#the-public-directory) for more details. |
| 94 | + |
| 95 | +## cacheDir |
| 96 | + |
| 97 | +- **Type:** `string` |
| 98 | +- **Default:** `"node_modules/.vite"` |
| 99 | + |
| 100 | +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. |
| 101 | + |
| 102 | +## resolve.alias |
| 103 | + |
| 104 | +- **Type:** |
| 105 | + `Record<string, string> | Array<{ find: string | RegExp, replacement: string, customResolver?: ResolverFunction | ResolverObject }>` |
| 106 | + |
| 107 | +Will be passed to `@rollup/plugin-alias` as its [entries option](https://github.com/rollup/plugins/tree/master/packages/alias#entries). Can either be an object, or an array of `{ find, replacement, customResolver }` pairs. |
| 108 | + |
| 109 | +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. |
| 110 | + |
| 111 | +More advanced custom resolution can be achieved through [plugins](/guide/api-plugin). |
| 112 | + |
| 113 | +## resolve.dedupe |
| 114 | + |
| 115 | +- **Type:** `string[]` |
| 116 | + |
| 117 | +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). |
| 118 | + |
| 119 | +:::warning SSR + ESM |
| 120 | +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. |
| 121 | +::: |
| 122 | + |
| 123 | +## resolve.conditions |
| 124 | + |
| 125 | +- **Type:** `string[]` |
| 126 | + |
| 127 | +Additional allowed conditions when resolving [Conditional Exports](https://nodejs.org/api/packages.html#packages_conditional_exports) from a package. |
| 128 | + |
| 129 | +A package with conditional exports may have the following `exports` field in its `package.json`: |
| 130 | + |
| 131 | +```json |
| 132 | +{ |
| 133 | + "exports": { |
| 134 | + ".": { |
| 135 | + "import": "./index.mjs", |
| 136 | + "require": "./index.js" |
| 137 | + } |
| 138 | + } |
| 139 | +} |
| 140 | +``` |
| 141 | + |
| 142 | +Here, `import` and `require` are "conditions". Conditions can be nested and should be specified from most specific to least specific. |
| 143 | + |
| 144 | +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. |
| 145 | + |
| 146 | +:::warning Resolving subpath exports |
| 147 | +Export keys ending with "/" is deprecated by Node and may not work well. Please contact the package author to use [`*` subpath patterns](https://nodejs.org/api/packages.html#package-entry-points) instead. |
| 148 | +::: |
| 149 | + |
| 150 | +## resolve.mainFields |
| 151 | + |
| 152 | +- **Type:** `string[]` |
| 153 | +- **Default:** `['module', 'jsnext:main', 'jsnext']` |
| 154 | + |
| 155 | +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. |
| 156 | + |
| 157 | +## resolve.extensions |
| 158 | + |
| 159 | +- **Type:** `string[]` |
| 160 | +- **Default:** `['.mjs', '.js', '.ts', '.jsx', '.tsx', '.json']` |
| 161 | + |
| 162 | +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. |
| 163 | + |
| 164 | +## resolve.preserveSymlinks |
| 165 | + |
| 166 | +- **Type:** `boolean` |
| 167 | +- **Default:** `false` |
| 168 | + |
| 169 | +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). |
| 170 | + |
| 171 | +- **Related:** [esbuild#preserve-symlinks](https://esbuild.github.io/api/#preserve-symlinks), [webpack#resolve.symlinks |
| 172 | + ](https://webpack.js.org/configuration/resolve/#resolvesymlinks) |
| 173 | + |
| 174 | +## css.modules |
| 175 | + |
| 176 | +- **Type:** |
| 177 | + ```ts |
| 178 | + interface CSSModulesOptions { |
| 179 | + scopeBehaviour?: 'global' | 'local' |
| 180 | + globalModulePaths?: RegExp[] |
| 181 | + generateScopedName?: |
| 182 | + | string |
| 183 | + | ((name: string, filename: string, css: string) => string) |
| 184 | + hashPrefix?: string |
| 185 | + /** |
| 186 | + * default: null |
| 187 | + */ |
| 188 | + localsConvention?: |
| 189 | + | 'camelCase' |
| 190 | + | 'camelCaseOnly' |
| 191 | + | 'dashes' |
| 192 | + | 'dashesOnly' |
| 193 | + | null |
| 194 | + } |
| 195 | + ``` |
| 196 | + |
| 197 | +Configure CSS modules behavior. The options are passed on to [postcss-modules](https://github.com/css-modules/postcss-modules). |
| 198 | + |
| 199 | +## css.postcss |
| 200 | + |
| 201 | +- **Type:** `string | (postcss.ProcessOptions & { plugins?: postcss.Plugin[] })` |
| 202 | + |
| 203 | +Inline PostCSS config or a custom directory to search PostCSS config from (default is project root). |
| 204 | + |
| 205 | +For inline PostCSS config, it expects the same format as `postcss.config.js`. But for `plugins` property, only [array format](https://github.com/postcss/postcss-load-config/blob/main/README.md#array) can be used. |
| 206 | + |
| 207 | +The search is done using [postcss-load-config](https://github.com/postcss/postcss-load-config) and only the supported config file names are loaded. |
| 208 | + |
| 209 | +Note if an inline config is provided, Vite will not search for other PostCSS config sources. |
| 210 | + |
| 211 | +## css.preprocessorOptions |
| 212 | + |
| 213 | +- **Type:** `Record<string, object>` |
| 214 | + |
| 215 | +Specify options to pass to CSS pre-processors. The file extensions are used as keys for the options. Example: |
| 216 | + |
| 217 | +```js |
| 218 | +export default defineConfig({ |
| 219 | + css: { |
| 220 | + preprocessorOptions: { |
| 221 | + scss: { |
| 222 | + additionalData: `$injectedColor: orange;` |
| 223 | + }, |
| 224 | + styl: { |
| 225 | + additionalData: `$injectedColor ?= orange` |
| 226 | + } |
| 227 | + } |
| 228 | + } |
| 229 | +}) |
| 230 | +``` |
| 231 | + |
| 232 | +## css.devSourcemap |
| 233 | + |
| 234 | +- **Experimental** |
| 235 | +- **Type:** `boolean` |
| 236 | +- **Default:** `false` |
| 237 | + |
| 238 | +Whether to enable sourcemaps during dev. |
| 239 | + |
| 240 | +## json.namedExports |
| 241 | + |
| 242 | +- **Type:** `boolean` |
| 243 | +- **Default:** `true` |
| 244 | + |
| 245 | +Whether to support named imports from `.json` files. |
| 246 | + |
| 247 | +## json.stringify |
| 248 | + |
| 249 | +- **Type:** `boolean` |
| 250 | +- **Default:** `false` |
| 251 | + |
| 252 | +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. |
| 253 | + |
| 254 | +Enabling this disables named imports. |
| 255 | + |
| 256 | +## esbuild |
| 257 | + |
| 258 | +- **Type:** `ESBuildOptions | false` |
| 259 | + |
| 260 | +`ESBuildOptions` extends [esbuild's own transform options](https://esbuild.github.io/api/#transform-api). The most common use case is customizing JSX: |
| 261 | + |
| 262 | +```js |
| 263 | +export default defineConfig({ |
| 264 | + esbuild: { |
| 265 | + jsxFactory: 'h', |
| 266 | + jsxFragment: 'Fragment' |
| 267 | + } |
| 268 | +}) |
| 269 | +``` |
| 270 | + |
| 271 | +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](https://github.com/micromatch/picomatch#globbing-features) pattern, or an array of either. |
| 272 | + |
| 273 | +In addition, you can also use `esbuild.jsxInject` to automatically inject JSX helper imports for every file transformed by esbuild: |
| 274 | + |
| 275 | +```js |
| 276 | +export default defineConfig({ |
| 277 | + esbuild: { |
| 278 | + jsxInject: `import React from 'react'` |
| 279 | + } |
| 280 | +}) |
| 281 | +``` |
| 282 | + |
| 283 | +Set to `false` to disable esbuild transforms. |
| 284 | + |
| 285 | +## assetsInclude |
| 286 | + |
| 287 | +- **Type:** `string | RegExp | (string | RegExp)[]` |
| 288 | +- **Related:** [Static Asset Handling](/guide/assets) |
| 289 | + |
| 290 | +Specify additional [picomatch patterns](https://github.com/micromatch/picomatch#globbing-features) to be treated as static assets so that: |
| 291 | + |
| 292 | +- They will be excluded from the plugin transform pipeline when referenced from HTML or directly requested over `fetch` or XHR. |
| 293 | + |
| 294 | +- 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). |
| 295 | + |
| 296 | +The built-in asset type list can be found [here](https://github.com/vitejs/vite/blob/main/packages/vite/src/node/constants.ts). |
| 297 | + |
| 298 | +**Example:** |
| 299 | + |
| 300 | +```js |
| 301 | +export default defineConfig({ |
| 302 | + assetsInclude: ['**/*.gltf'] |
| 303 | +}) |
| 304 | +``` |
| 305 | + |
| 306 | +## logLevel |
| 307 | + |
| 308 | +- **Type:** `'info' | 'warn' | 'error' | 'silent'` |
| 309 | + |
| 310 | +Adjust console output verbosity. Default is `'info'`. |
| 311 | + |
| 312 | +## clearScreen |
| 313 | + |
| 314 | +- **Type:** `boolean` |
| 315 | +- **Default:** `true` |
| 316 | + |
| 317 | +Set to `false` to prevent Vite from clearing the terminal screen when logging certain messages. Via command line, use `--clearScreen false`. |
| 318 | + |
| 319 | +## envDir |
| 320 | + |
| 321 | +- **Type:** `string` |
| 322 | +- **Default:** `root` |
| 323 | + |
| 324 | +The directory from which `.env` files are loaded. Can be an absolute path, or a path relative to the project root. |
| 325 | + |
| 326 | +See [here](/guide/env-and-mode#env-files) for more about environment files. |
| 327 | + |
| 328 | +## envPrefix |
| 329 | + |
| 330 | +- **Type:** `string | string[]` |
| 331 | +- **Default:** `VITE_` |
| 332 | + |
| 333 | +Env variables starts with `envPrefix` will be exposed to your client source code via import.meta.env. |
| 334 | + |
| 335 | +:::warning SECURITY NOTES |
| 336 | +`envPrefix` should not be set as `''`, which will expose all your env variables and cause unexpected leaking of of sensitive information. Vite will throw error when detecting `''`. |
| 337 | +::: |
| 338 | + |
| 339 | +## spa |
| 340 | + |
| 341 | +- **Type:** `boolean` |
| 342 | +- **Default:** `true` |
| 343 | + |
| 344 | +Whether your application is a Single Page Application (SPA). Set to `false` for other kinds of apps like MPAs. Learn more in Vite's [SSR guide](/guide/ssr#vite-cli). |
0 commit comments