shared options: fundamentals

42 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.

base configuration option for nested public paths

The `base` config option specifies the public base path for deployments under a nested path. All asset paths are rewritten accordingly during build. This can also be specified as a command line flag with `vite build --base=/my/public/path/`.

relative base path configuration

Setting `base` to `"./"` or `""` enables relative base paths. This makes all generated URLs relative to each file. Requires `import.meta` support, which is not available in older browsers without the legacy plugin.

import.meta.env.BASE_URL injection

The globally injected `import.meta.env.BASE_URL` variable contains the public base path and is statically replaced during build. It must appear exactly as-is; variations like `import.meta.env['BASE_URL']` will not work.

publicDir option configures public asset directory

The publicDir option configures the directory containing assets that are never referenced in source code or must retain exact file names without hashing. It defaults to <root>/public but can be customized.

Public directory assets served at root path

Assets in the public directory are served at root path / during development and copied to the root of the dist directory as-is during build. Public assets should always be referenced using root absolute paths, for example /icon.png.

envPrefix option default value

The envPrefix option controls which environment variables are exposed in client-side source code. The default prefix is 'VITE_', meaning only environment variables prefixed with 'VITE_' are exposed in client-side source code after Vite bundling.

mode shared option type and default value

The mode is a string shared option. By default, the dev server runs in 'development' mode and the build command runs in 'production' mode. The mode can be overridden by passing the --mode option flag to commands like 'vite build --mode staging'.

import.meta.env built-in constants

Vite exposes the following built-in constants in all cases: import.meta.env.MODE (string) - the mode the app is running in; import.meta.env.BASE_URL (string) - the base URL the app is being served from, determined by the base config option; import.meta.env.PROD (boolean) - whether the app is running in production; import.meta.env.DEV (boolean) - whether the app is running in development, always the opposite of PROD; import.meta.env.SSR (boolean) - whether the app is running in server-side rendering mode.

Environment variable exposure and prefix behavior

Variables prefixed with 'VITE_' are automatically exposed in client-side source code as strings after Vite bundling. Variables without this prefix are not exposed and return undefined when accessed in client code. For example, VITE_SOME_KEY='123' becomes accessible as import.meta.env.VITE_SOME_KEY with value '123', but DB_PASSWORD is not exposed.

Env file loading order and priority

Vite loads environment variables from files in this order: .env (loaded in all cases), .env.local (loaded in all cases, ignored by git), .env.[mode] (only loaded in specified mode), .env.[mode].local (only loaded in specified mode, ignored by git). Files for a specific mode take higher priority than generic files. Environment variables that already exist when Vite is executed have the highest priority and will not be overwritten by .env files.

NODE_ENV and modes are separate concepts

NODE_ENV (process.env.NODE_ENV) and modes are two different concepts. By default, 'vite build' sets NODE_ENV to 'production' and mode to 'production'. The --mode flag only changes the mode, not NODE_ENV. NODE_ENV can be set via command line (NODE_ENV=development vite build) or in .env files. The NODE_ENV command-line setting allows Vite to detect the value early and enables reading process.env.NODE_ENV in the Vite config.

NODE_ENV and mode behavior table

Command effects: vite build -> NODE_ENV='production', mode='production'; vite build --mode development -> NODE_ENV='production', mode='development'; NODE_ENV=development vite build -> NODE_ENV='development', mode='production'; NODE_ENV=development vite build --mode development -> NODE_ENV='development', mode='development'.

import.meta.env.PROD and DEV based on NODE_ENV

The import.meta.env.PROD and import.meta.env.DEV properties are determined by NODE_ENV value: when NODE_ENV=production, PROD is true and DEV is false; when NODE_ENV=development, PROD is false and DEV is true; when NODE_ENV=other (any other value), PROD is false and DEV is true.

import.meta.env.MODE values by mode flag

The import.meta.env.MODE value reflects the --mode flag: --mode production sets MODE to 'production'; --mode development sets MODE to 'development'; --mode staging sets MODE to 'staging'.

Environment variable expansion in .env files

Vite uses dotenv-expand to expand variables in .env files. Variables can reference other variables using syntax like NEW_KEY3=test$KEY which becomes test123 if KEY=123. To use a literal $ character, escape it with backslash: test\$foo becomes test$foo. Vite supports expanding variables in reverse order, so VITE_FOO=foo${VITE_BAR} with VITE_BAR=bar below it evaluates to VITE_FOO=foobar.

HTML constant replacement syntax

Vite supports replacing constants in HTML files using the %CONST_NAME% syntax. Any properties from import.meta.env can be used, such as %MODE% or %VITE_API_URL%. If an env variable does not exist in import.meta.env, the placeholder is ignored and not replaced, unlike JavaScript where it would be replaced as undefined.

TypeScript IntelliSense for env variables

To get TypeScript IntelliSense for custom VITE_-prefixed environment variables, create a vite-env.d.ts file in the src directory and augment the ImportMetaEnv interface with your custom env variable types. Do not include any import statements in vite-env.d.ts as imports will break type augmentation.

Example of import.meta.env usage with tree-shaking

Code wrapped in if (import.meta.env.DEV) { ... } will be tree-shaken in production builds. This allows writing development-only code that is completely removed from production bundles.

root option type and default

The root option is of type string with a default value of process.cwd(). It specifies the project root directory where index.html is located, and can be an absolute path or a path relative to the current working directory.

mode option type and default

The mode option is of type string with a default value of 'development' for serve and 'production' for build. Specifying it in config overrides the default mode for both serve and build, and can also be overridden via the command line --mode option.

envPrefix option type and default

The envPrefix option is of type string or string[] with a default value of 'VITE_'. It controls which environment variables are exposed to client source code via import.meta.env. Env variables starting with envPrefix are exposed to your client source code.

base option type and default

The base option is of type string with a default value of '/'. It specifies the 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/'), and empty string or './' for embedded deployment.

input option type

The input option is of type string, string[], or { [entryAlias: string]: string }. It specifies entry points of the application resolved relative to the project root, and works as the default value for build.rolldownOptions.input, build.lib.entry, build.ssr (if true), and optimizeDeps.entries when those are not set explicitly.

plugins option type

The plugins option is of type (Plugin | Plugin[] | Promise<Plugin | Plugin[]>)[]. It accepts an array of plugins to use. Falsy plugins are ignored and arrays of plugins are flattened. If a promise is returned, it is resolved before running.

publicDir option type and default

The publicDir option is of type string or false with a default value of 'public'. It specifies the directory to serve as plain static assets. Files are served at '/' during dev and copied to the root of outDir during build, and are always served or copied as-is without transform. Setting publicDir to false disables this feature.

cacheDir option type and default

The cacheDir option is of type string with a default value of 'node_modules/.vite'. It specifies the directory to save cache files for pre-bundled dependencies and other cache files generated by Vite. The value can be an absolute file system path or a path relative to project root, and defaults to '.vite' when no package.json is detected.

html.cspNonce option type

The html.cspNonce option is of type string. It specifies a nonce value placeholder that will be used when generating script and style tags. Setting this value also generates a meta tag with the nonce value.

html.additionalAssetSources option type

The html.additionalAssetSources option is of type Record<string, HtmlAssetSource>. It defines additional HTML elements and attributes to be treated as asset sources, extending the built-in list that includes standard elements like <img src>, <video src>, <link href>, etc.

json.namedExports option type and default

The json.namedExports option is of type boolean with a default value of true. It controls whether to support named imports from .json files.

json.stringify option type and default

The json.stringify option is of type boolean or 'auto' with a default value of 'auto'. When set to true, imported JSON is transformed into export default JSON.parse(...). When set to 'auto', data is stringified only if larger than 10kB.

oxc option type

The oxc option is of type OxcOptions or false. It extends Oxc Transformer's options, with the most common use case being customizing JSX. By default, transformation is applied to ts, jsx, and tsx files, and can be customized with oxc.include and oxc.exclude. Set to false to disable Oxc transformation.

esbuild option deprecated

The esbuild option is deprecated. It is converted to the oxc option internally. The oxc option should be used instead.

assetsInclude option type

The assetsInclude option is of type string or RegExp or (string | RegExp)[]. It specifies additional picomatch patterns to be treated as static assets, which excludes them from the plugin transform pipeline and returns their resolved URL string when imported from JS.

logLevel option type

The logLevel option is of type 'info' | 'warn' | 'error' | 'silent'. It adjusts console output verbosity, with a default of 'info'.

customLogger option type

The customLogger option is of type Logger interface with methods: 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, and property hasWarned: boolean. It allows using a custom logger to log messages.

clearScreen option type and default

The clearScreen option is of type boolean with a default value of true. When set to false, it prevents Vite from clearing the terminal screen when logging certain messages.

envDir option type and default

The envDir option is of type string or false with a default value of 'root'. It specifies the directory from which .env files are loaded. Setting it to false disables .env file loading.

appType option type and default

The appType option is of type 'spa' | 'mpa' | 'custom' with a default value of 'spa'. It specifies whether the application is a Single Page Application (SPA), Multi Page Application (MPA), or Custom Application (SSR and frameworks with custom HTML handling).

devtools option type and default

The devtools option is of type boolean or DevToolsConfig with a default value of false. It enables devtools integration for inspecting the dev server and analyzing builds. DevTools runs for both serve and build by default; use apply to limit it to either command.

tsconfig option type

The tsconfig option is of type string. It specifies the path to the TypeScript configuration file used by Vite, with relative paths resolved from the project root.

future option type

The future option is of type Record<string, 'warn' | undefined>. It enables future breaking changes to prepare for a smooth migration to the next major version of Vite.

define option type

The define option is of type Record<string, any>. It defines global constant replacements that are defined as globals during dev and statically replaced during build. Value expressions must be a string containing a JSON-serializable value or a single identifier.

Give your agent this brain