Guide

Environment API for Frameworks
:::info Release Candidate
The Environment API is generally in the release candidate phase. We'll maintain stability in the APIs between major releases to allow the ecosystem to experiment and build upon them. However, note that some specific APIs are still considered experimental.
We plan to stabilize these new APIs (with potential breaking changes) in a future major release once downstream projects have had time to experiment with the new features and validate them.
Resources:
Feedback discussion where we are gathering feedback about the new APIs.
Environment API PR where the new APIs were implemented and reviewed.
Please share your feedback with us.
:::
DevEnvironment Communication Levels
Since environments may run in different runtimes, communication against the environment may have constraints depending on the runtime. To allow frameworks to write runtime agnostic code easily, the Environment API provides three kinds of communication levels.
RunnableDevEnvironment
RunnableDevEnvironment is an environment that can communicate arbitrary JavaScript values with your application code. Importing a module returns its real, live exports (functions, class instances, and any other values), so frameworks can run their server entries directly. The implicit 
ssr environment and other non-client environments use a 
RunnableDevEnvironment by default during dev. You can guard access to the runner with the 
isRunnableDevEnvironment function.
Its 
runner is a 
ModuleRunner. You import modules through it with 
runner.import(url), which fetches, transforms, and evaluates a module from the Vite module graph (the 
url accepts a file path, server path, or id relative to the root) and returns the instantiated module with full HMR support. It is the modern replacement for 
server.ssrLoadModule, so frameworks can migrate to it to enable HMR for their SSR dev story.
:::info Why it can communicate arbitrary values
A 
RunnableDevEnvironment evaluates modules in the same runtime as the Vite server, so values cross the boundary in-process instead of being serialized. This is what distinguishes it from 
FetchableDevEnvironment, which can only communicate through serialized 
Request/
Response objects over the Fetch API. As a result, using a 
RunnableDevEnvironment requires the runner's runtime to be the same as the one the Vite server is running in.
:::
export class RunnableDevEnvironment extends DevEnvironment {
  public readonly runner: ModuleRunner
}
class ModuleRunner {
  /**
   * URL to execute.
   * Accepts file path, server path, or id relative to the root.
   * Returns an instantiated module (same as in ssrLoadModule)
   */
  public async import(url: string): Promise<Record<string, any>>
  /**
   * Other ModuleRunner methods...
   */
}
if (isRunnableDevEnvironment(server.environments.ssr)) {
  await server.environments.ssr.runner.import('/entry-point.js')
}
:::warning
The 
runner is evaluated lazily only when it's accessed for the first time. Beware that Vite enables source map support when the 
runner is created by calling 
process.setSourceMapsEnabled or by overriding 
Error.prepareStackTrace if it's not available.
:::
Given a Vite server configured in middleware mode as described by the SSR setup guide, let's implement the SSR middleware using the environment API. Remember that it doesn't have to be called 
ssr, so we'll name it 
server in this example. Error handling is omitted.
import fs from 'node:fs'
import path from 'node:path'
import { createServer } from 'vite'
const viteServer = await createServer({
  server: { middlewareMode: true },
  appType: 'custom',
  environments: {
    server: {
      // by default, modules are run in the same process as the vite server
    },
  },
})
// You might need to cast this to RunnableDevEnvironment in TypeScript or
// use isRunnableDevEnvironment to guard the access to the runner
const serverEnvironment = viteServer.environments.server
app.use('*', async (req, res, next) => {
  const url = req.originalUrl
  // 1. Read index.html
  const indexHtmlPath = path.resolve(import.meta.dirname, 'index.html')
  let template = fs.readFileSync(indexHtmlPath, 'utf-8')
  // 2. Apply Vite HTML transforms. This injects the Vite HMR client,
  //    and also applies HTML transforms from Vite plugins, e.g. global
  //    preambles from @vitejs/plugin-react
  template = await viteServer.transformIndexHtml(url, template)
  // 3. Load the server entry. import(url) automatically transforms
  //    ESM source code to be usable in Node.js! There is no bundling
  //    required, and provides full HMR support.
  const { render } = await serverEnvironment.runner.import(
    '/src/entry-server.js',
  )
  // 4. render the app HTML. This assumes entry-server.js's exported
  //     `render` function calls appropriate framework SSR APIs,
  //    e.g. ReactDOMServer.renderToString()
  const appHtml = await render(url)
  // 5. Inject the app-rendered HTML into the template.
  const html = template.replace(`<!--ssr-outlet-->`, appHtml)
  // 6. Send the rendered HTML back.
  res.status(200).set({ 'Content-Type': 'text/html' }).end(html)
})
When using environments that support HMR (such as 
RunnableDevEnvironment), you should add 
import.meta.hot.accept() in your server entry file for optimal behavior. Without this, server file changes will invalidate the entire server module graph:
// src/entry-server.js
export function render(...) { ... }
if (import.meta.hot) {
  import.meta.hot.accept()
}
FetchableDevEnvironment
:::info
We are looking for feedback on the 
FetchableDevEnvironment proposal.
:::
FetchableDevEnvironment is an environment that can communicate with its runtime via the Fetch API interface. Since the 
RunnableDevEnvironment is only possible to implement in a limited set of runtimes, we recommend to use the 
FetchableDevEnvironment instead of the 
RunnableDevEnvironment.
A common reason to reach for it is a framework that wants to support a runtime that can't run Vite directly (e.g. Cloudflare Workers). A 
RunnableDevEnvironment can't be used there, since it requires the runner to share the Vite server's runtime so values can cross the boundary in-process. Standardizing on the Fetch API lets the framework keep a single request-handling path across all of its target runtimes: its dev middleware forwards each incoming browser request as a 
Request and sends the returned 
Response back to the browser, mirroring how the app handles requests in production.
This environment provides a standardized way of handling requests via the 
handleRequest method:
import {
  createServer,
  createFetchableDevEnvironment,
  isFetchableDevEnvironment,
} from 'vite'
const server = await createServer({
  server: { middlewareMode: true },
  appType: 'custom',
  environments: {
    custom: {
      dev: {
        createEnvironment(name, config) {
          return createFetchableDevEnvironment(name, config, {
            handleRequest(request: Request): Promise<Response> | Response {
              // handle Request and return a Response
            },
          })
        },
      },
    },
  },
})
// Any consumer of the environment API can now call `dispatchFetch`
if (isFetchableDevEnvironment(server.environments.custom)) {
  const response: Response = await server.environments.custom.dispatchFetch(
    new Request('http://example.com/request-to-handle'),
  )
}
:::warning
Vite validates the input and output of the 
dispatchFetch method: the request must be an instance of the global 
Request class and the response must be the instance of the global 
Response class. Vite will throw a 
TypeError if this is not the case.
Note that although the 
FetchableDevEnvironment is implemented as a class, it is considered an implementation detail by the Vite team and might change at any moment.
:::
raw 
DevEnvironment
If the environment does not implement the 
RunnableDevEnvironment or 
FetchableDevEnvironment interfaces, you need to set up the communication manually.
If your code can run in the same runtime as the user modules (i.e., it does not rely on Node.js-specific APIs), you can use a virtual module. This approach eliminates the need to access the value from the code using Vite's APIs.
// code using the Vite's APIs
import { createServer } from 'vite'
const server = await createServer({
  plugins: [
    // a plugin that handles `virtual:entrypoint`
    {
      name: 'virtual-module',
      /* plugin implementation */
    },
  ],
})
const ssrEnvironment = server.environments.ssr
const input = {}
// use exposed functions by each environment factories that runs the code
// check for each environment factories what they provide
if (ssrEnvironment instanceof CustomDevEnvironment) {
  ssrEnvironment.runEntrypoint('virtual:entrypoint')
} else {
  throw new Error(`Unsupported runtime for ${ssrEnvironment.name}`)
}
// -------------------------------------
// virtual:entrypoint
const { createHandler } = await import('./entrypoint.js')
const handler = createHandler(input)
const response = handler(new Request('http://example.com/'))
// -------------------------------------
// ./entrypoint.js
export function createHandler(input) {
  return function handler(req) {
    return new Response('hello')
  }
}
For example, to call 
transformIndexHtml on the user module, the following plugin can be used:
function vitePluginVirtualIndexHtml(): Plugin {
  let server: ViteDevServer | undefined
  return {
    name: vitePluginVirtualIndexHtml.name,
    configureServer(server_) {
      server = server_
    },
    resolveId(source) {
      return source === 'virtual:index-html' ? '\0' + source : undefined
    },
    async load(id) {
      if (id === '\0' + 'virtual:index-html') {
        let html: string
        if (server) {
          this.addWatchFile('index.html')
          html = fs.readFileSync('index.html', 'utf-8')
          html = await server.transformIndexHtml('/', html)
        } else {
          html = fs.readFileSync('dist/client/index.html', 'utf-8')
        }
        return `export default ${JSON.stringify(html)}`
      }
      return
    },
  }
}
If your code requires Node.js APIs, you can use 
hot.send to communicate with the code that uses Vite's APIs from the user modules. However, be aware that this approach may not work the same way after the build process.
// code using the Vite's APIs
import { createServer } from 'vite'
const server = await createServer({
  plugins: [
    // a plugin that handles `virtual:entrypoint`
    {
      name: 'virtual-module',
      /* plugin implementation */
    },
  ],
})
const ssrEnvironment = server.environments.ssr
const input = {}
// use exposed functions by each environment factories that runs the code
// check for each environment factories what they provide
if (ssrEnvironment instanceof RunnableDevEnvironment) {
  await ssrEnvironment.runner.import('virtual:entrypoint')
} else if (ssrEnvironment instanceof CustomDevEnvironment) {
  ssrEnvironment.runEntrypoint('virtual:entrypoint')
} else {
  throw new Error(`Unsupported runtime for ${ssrEnvironment.name}`)
}
const req = new Request('http://example.com/')
const uniqueId = 'a-unique-id'
ssrEnvironment.hot.send('request', serialize({ req, uniqueId }))
const response = await new Promise((resolve) => {
  ssrEnvironment.hot.on('response', (data) => {
    data = deserialize(data)
    if (data.uniqueId === uniqueId) {
      resolve(data.res)
    }
  })
})
// -------------------------------------
// virtual:entrypoint
const { createHandler } = await import('./entrypoint.js')
const handler = createHandler(input)
import.meta.hot.on('request', (data) => {
  const { req, uniqueId } = deserialize(data)
  const res = handler(req)
  import.meta.hot.send('response', serialize({ res: res, uniqueId }))
})
// -------------------------------------
// ./entrypoint.js
export function createHandler(input) {
  return function handler(req) {
    return new Response('hello')
  }
}
Environments During Build
In the CLI, calling 
vite build and 
vite build --ssr will still build the client only and ssr only environments for backward compatibility.
When the 
builder option is set (even to an empty object 
{}, which is what 
vite build --app does), 
vite build opts in to building the entire app instead. This will become the default in a future major. In this mode, Vite creates a 
ViteBuilder instance (the build-time equivalent of a 
ViteDevServer) and uses it to build all configured environments for production. By default, environments are built in series, following the order of the 
environments record.
Configuring the app build with 
builder.buildApp
A framework or user can control how the environments are built through the 
builder.buildApp option. It receives the 
ViteBuilder instance (named 
builder in the example below) and is responsible for building each environment; for instance, to build some of them in parallel:
import { defineConfig } from 'vite'
export default defineConfig({
  builder: {
    buildApp: async (builder) => {
      const environments = Object.values(builder.environments)
      await Promise.all(
        environments.map((environment) => builder.build(environment)),
      )
    },
  },
})
The 
buildApp plugin hook
Type: 
(this: MinimalPluginContextWithoutEnvironment, builder: ViteBuilder) => Promise<void>
Kind: 
async, 
sequential
Scope: Global
Besides the 
builder.buildApp config option, plugins can define a 
buildApp hook to participate in the app build. The config option and the plugin hooks run in a defined order: hooks with order 
'pre' or 
null run first, then the configured 
builder.buildApp, then hooks with order 
'post'. Within a hook, 
environment.isBuilt tells you whether an environment has already been built, which lets a plugin avoid building it twice.
Building programmatically with 
createBuilder
To trigger an app build from your own code, use 
createBuilder instead of the standalone 
build function. 
createBuilder is the build-time equivalent of 
createServer: it resolves the config and returns a 
ViteBuilder, whose 
buildApp method builds every configured environment. You can also build a single environment with 
builder.build(environment).
import { createBuilder } from 'vite'
const builder = await createBuilder()
await builder.buildApp()
createBuilder supersedes the standalone 
build function for environment-aware builds. 
build still works as the simple entry point for the legacy client-only and ssr-only builds described above, but it cannot build arbitrary environments. Running 
builder.buildApp() is the programmatic equivalent of 
vite build --app.
Environment Agnostic Code
Most of the time, the current 
environment instance will be available as part of the context of the code being run so the need to access them through 
server.environments should be rare. For example, inside plugin hooks the environment is exposed as part of the 
PluginContext, so it can be accessed using 
this.environment. See Environment API for Plugins to learn about how to build environment aware plugins.

Using `Environment` Instances
:::info Release Candidate
The Environment API is generally in the release candidate phase. We'll maintain stability in the APIs between major releases to allow the ecosystem to experiment and build upon them. However, note that some specific APIs are still considered experimental.
We plan to stabilize these new APIs (with potential breaking changes) in a future major release once downstream projects have had time to experiment with the new features and validate them.
Resources:
Feedback discussion where we are gathering feedback about the new APIs.
Environment API PR where the new APIs were implemented and reviewed.
Please share your feedback with us.
:::
Accessing the Environments
During dev, the available environments in a dev server can be accessed using 
server.environments:
// create the server, or get it from the configureServer hook
const server = await createServer(/* options */)
const clientEnvironment = server.environments.client
clientEnvironment.transformRequest(url)
console.log(server.environments.ssr.moduleGraph)
You can also access the current environment from plugins. See the Environment API for Plugins for more details.
DevEnvironment class
During dev, each environment is an instance of the 
DevEnvironment class:
class DevEnvironment {
  /**
   * Unique identifier for the environment in a Vite server.
   * By default Vite exposes 'client' and 'ssr' environments.
   */
  name: string
  /**
   * Communication channel to send and receive messages from the
   * associated module runner in the target runtime.
   */
  hot: NormalizedHotChannel
  /**
   * Graph of module nodes, with the imported relationship between
   * processed modules and the cached result of the processed code.
   */
  moduleGraph: EnvironmentModuleGraph
  /**
   * Resolved plugins for this environment, including the ones
   * created using the per-environment `create` hook
   */
  plugins: Plugin[]
  /**
   * Allows to resolve, load, and transform code through the
   * environment plugins pipeline
   */
  pluginContainer: EnvironmentPluginContainer
  /**
   * Resolved config options for this environment. Options at the server
   * global scope are taken as defaults for all environments, and can
   * be overridden (resolve conditions, external, optimizedDeps)
   */
  config: ResolvedConfig & ResolvedDevEnvironmentOptions
  constructor(
    name: string,
    config: ResolvedConfig,
    context: DevEnvironmentContext,
  )
  /**
   * Resolve the URL to an id, load it, and process the code using the
   * plugins pipeline. The module graph is also updated.
   */
  async transformRequest(url: string): Promise<TransformResult | null>
  /**
   * Register a request to be processed with low priority. This is useful
   * to avoid waterfalls. The Vite server has information about the
   * imported modules by other requests, so it can warmup the module graph
   * so the modules are already processed when they are requested.
   */
  async warmupRequest(url: string): Promise<void>
  /**
   * Called by the module runner to retrieve information about the specified
   * module. Internally calls `transformRequest` and wraps the result in the
   * format that the module runner understands.
   * This method is not meant to be called manually.
   */
  async fetchModule(
    id: string,
    importer?: string,
    options?: FetchFunctionOptions,
  ): Promise<FetchResult>
}
With 
DevEnvironmentContext being:
interface DevEnvironmentContext {
  hot: boolean
  transport?: HotChannel | WebSocketServer
  options?: EnvironmentOptions
  remoteRunner?: {
    inlineSourceMap?: boolean
  }
  depsOptimizer?: DepsOptimizer
}
and with 
TransformResult being:
interface TransformResult {
  code: string
  map: SourceMap | { mappings: '' } | null
  etag?: string
  deps?: string[]
  dynamicDeps?: string[]
}
An environment instance in the Vite server lets you process a URL using the 
environment.transformRequest(url) method. This function will use the plugin pipeline to resolve the 
url to a module 
id, load it (reading the file from the file system or through a plugin that implements a virtual module), and then transform the code. While transforming the module, imports and other metadata will be recorded in the environment module graph by creating or updating the corresponding module node. When processing is done, the transform result is also stored in the module.
:::info transformRequest naming
We are using 
transformRequest(url) and 
warmupRequest(url) in the current version of this proposal so it is easier to discuss and understand for users used to Vite's current API. Before releasing, we can take the opportunity to review these names too. For example, it could be named 
environment.processModule(url) or 
environment.loadModule(url) taking a page from Rollup's 
context.load(id) in plugin hooks. For the moment, we think keeping the current names and delaying this discussion is better.
:::
Separate Module Graphs
Each environment has an isolated module graph. All module graphs have the same signature, so generic algorithms can be implemented to crawl or query the graph without depending on the environment. 
hotUpdate is a good example. When a file is modified, the module graph of each environment will be used to discover the affected modules and perform HMR for each environment independently.
::: info
Vite v5 had a mixed Client and SSR module graph. Given an unprocessed or invalidated node, it isn't possible to know if it corresponds to the Client, SSR, or both environments. Module nodes have some properties prefixed, like 
clientImportedModules and 
ssrImportedModules (and 
importedModules that returns the union of both). 
importers contains all importers from both the Client and SSR environment for each module node. A module node also has 
transformResult and 
ssrTransformResult. A backward compatibility layer allows the ecosystem to migrate from the deprecated 
server.moduleGraph.
:::
Each module is represented by a 
EnvironmentModuleNode instance. Modules may be registered in the graph without yet being processed (
transformResult would be 
null in that case). 
importers and 
importedModules are also updated after the module is processed.
class EnvironmentModuleNode {
  environment: string
  url: string
  id: string | null = null
  file: string | null = null
  type: 'js' | 'css'
  importers = new Set<EnvironmentModuleNode>()
  importedModules = new Set<EnvironmentModuleNode>()
  importedBindings: Map<string, Set<string>> | null = null
  info?: ModuleInfo
  meta?: Record<string, any>
  transformResult: TransformResult | null = null
  acceptedHmrDeps = new Set<EnvironmentModuleNode>()
  acceptedHmrExports: Set<string> | null = null
  isSelfAccepting?: boolean
  lastHMRTimestamp = 0
  lastInvalidationTimestamp = 0
}
environment.moduleGraph is an instance of 
EnvironmentModuleGraph:
export class EnvironmentModuleGraph {
  environment: string
  urlToModuleMap = new Map<string, EnvironmentModuleNode>()
  idToModuleMap = new Map<string, EnvironmentModuleNode>()
  etagToModuleMap = new Map<string, EnvironmentModuleNode>()
  fileToModulesMap = new Map<string, Set<EnvironmentModuleNode>>()
  constructor(
    environment: string,
    resolveId: (url: string) => Promise<PartialResolvedId | null>,
  )
  async getModuleByUrl(
    rawUrl: string,
  ): Promise<EnvironmentModuleNode | undefined>
  getModuleById(id: string): EnvironmentModuleNode | undefined
  getModulesByFile(file: string): Set<EnvironmentModuleNode> | undefined
  onFileChange(file: string): void
  onFileDelete(file: string): void
  invalidateModule(
    mod: EnvironmentModuleNode,
    seen: Set<EnvironmentModuleNode> = new Set(),
    timestamp: number = monotonicDateNow(),
    isHmr: boolean = false,
  ): void
  invalidateAll(): void
  async ensureEntryFromUrl(
    rawUrl: string,
    setIsSelfAccepting = true,
  ): Promise<EnvironmentModuleNode>
  createFileOnlyEntry(file: string): EnvironmentModuleNode
  async resolveUrl(url: string): Promise<ResolvedUrl>
  updateModuleTransformResult(
    mod: EnvironmentModuleNode,
    result: TransformResult | null,
  ): void
  getModuleByEtag(etag: string): EnvironmentModuleNode | undefined
}
FetchResult
The 
environment.fetchModule method returns a 
FetchResult that is meant to be consumed by the module runner. 
FetchResult is a union of 
CachedFetchResult, 
ExternalFetchResult, and 
ViteFetchResult.
CachedFetchResult is analogous to the 
304 (Not Modified) HTTP status code.
export interface CachedFetchResult {
  /**
   * If the module is cached in the runner, this confirms
   * it was not invalidated on the server side.
   */
  cache: true
}
ExternalFetchResult instructs the module runner to import the module using the 
runExternalModule method on the 
ModuleEvaluator. In this case, the default module evaluator will use the runtime's native 
import instead of processing the file through Vite.
export interface ExternalFetchResult {
  /**
   * The path to the externalized module starting with file://.
   * By default this will be imported via a dynamic "import"
   * instead of being transformed by Vite and loaded with the Vite runner.
   */
  externalize: string
  /**
   * Type of the module. Used to determine if the import statement is correct.
   * For example, if Vite needs to throw an error if a variable is not actually exported.
   */
  type: 'module' | 'commonjs' | 'builtin' | 'network'
}
ViteFetchResult returns information about the current module, including the 
code to execute and the module's 
id, 
file, and 
url.
The 
invalidate field instructs the module runner to invalidate the module before executing it again rather than serving it from cache. This is usually 
true when an HMR update was triggered.
export interface ViteFetchResult {
  /**
   * Code that will be evaluated by the Vite runner.
   * By default this will be wrapped in an async function.
   */
  code: string
  /**
   * File path of the module on disk.
   * This will be resolved as import.meta.url/filename.
   * Will be `null` for virtual modules.
   */
  file: string | null
  /**
   * Module ID in the server module graph.
   */
  id: string
  /**
   * Module URL used in the import.
   */
  url: string
  /**
   * Invalidate module on the client side.
   */
  invalidate: boolean
}

Environment API for Plugins
:::info Release Candidate
The Environment API is generally in the release candidate phase. We'll maintain stability in the APIs between major releases to allow the ecosystem to experiment and build upon them. However, note that some specific APIs are still considered experimental.
We plan to stabilize these new APIs (with potential breaking changes) in a future major release once downstream projects have had time to experiment with the new features and validate them.
Resources:
Feedback discussion where we are gathering feedback about the new APIs.
Environment API PR where the new APIs were implemented and reviewed.
Please share your feedback with us.
:::
Per-environment Hooks and Global Hooks
Plugins run on a shared pipeline, but their hooks fall into two categories depending on whether they run once for the whole server or once for each environment.
Global hooks are called a single time, independent of the configured environments. They handle app-wide concerns such as resolving the config or setting up the dev and preview servers, so 
this.environment is not relevant to them. Config resolution related hooks and server related hooks are global hooks.
Per-environment hooks are called once for each environment, and expose the current environment through 
this.environment in their context. All Rolldown hooks are per-environment, as are other Vite-specific hooks that handle modules. However, note that 
buildStart and 
buildEnd are only called for the client environment without the 
perEnvironmentStartEndDuringDev: true flag.
Accessing the Current Environment in Hooks
Given that there were only two Environments until Vite 6 (
client and 
ssr), a 
ssr boolean was enough to identify the current environment in Vite APIs. Plugin Hooks received a 
ssr boolean in the last options parameter, and several APIs expected an optional last 
ssr parameter to properly associate modules to the correct environment (for example 
server.moduleGraph.getModuleByUrl(url, { ssr })).
With the advent of configurable environments, we now have a uniform way to access their options and instance in plugins. Plugin hooks now expose 
this.environment in their context, and APIs that previously expected a 
ssr boolean are now scoped to the proper environment (for example 
environment.moduleGraph.getModuleByUrl(url)).
The Vite server has a shared plugin pipeline, but when a module is processed it is always done in the context of a given environment. The 
environment instance is available in the plugin context.
A plugin could use the 
environment instance to change how a module is processed depending on the configuration for the environment (which can be accessed using 
environment.config).
  transform(code, id) {
    console.log(this.environment.config.resolve.conditions)
  }
Registering New Environments Using Hooks
Plugins can add new environments in the 
config hook. For example, RSC support uses an additional environment to have a separate module graph with the 
react-server condition:
  config(config: UserConfig) {
    return {
      environments: {
        rsc: {
          resolve: {
            conditions: ['react-server', ...defaultServerConditions],
          },
        },
      },
    }
  }
An empty object is enough to register the environment, using default values from the root level environment config.
Configuring Environment Using the 
configEnvironment Hook
Type: 
(name: string, config: EnvironmentOptions, env: { mode: string, command: 'build' | 'serve', isSsrBuild?: boolean, isPreview?: boolean, isSsrTargetWebworker?: boolean }) => EnvironmentOptions | null | void
Kind: 
async, 
sequential
Scope: Per-environment
While the 
config hook is running, the complete list of environments isn't yet known and the environments can be affected by both the default values from the root level environment config or explicitly through the 
config.environments record.
Plugins should set default values using the 
config hook. To configure each environment, they can use the new 
configEnvironment hook. This hook is called for each environment with its partially resolved config including resolution of final defaults.
  configEnvironment(name: string, options: EnvironmentOptions) {
    // add "workerd" condition to the rsc environment
    if (name === 'rsc') {
      return {
        resolve: {
          conditions: ['workerd'],
        },
      }
    }
  }
The 
hotUpdate Hook
Type: 
(this: { environment: DevEnvironment }, options: HotUpdateOptions) => Array<EnvironmentModuleNode> | void | Promise<Array<EnvironmentModuleNode> | void>
Kind: 
async, 
sequential
Scope: Per-environment
See also: HMR API
The 
hotUpdate hook allows plugins to perform custom HMR update handling for a given environment. When a file changes, the HMR algorithm is run for each environment in series according to the order in 
server.environments, so the 
hotUpdate hook will be called multiple times. The hook receives a context object with the following signature:
interface HotUpdateOptions {
  type: 'create' | 'update' | 'delete'
  file: string
  timestamp: number
  modules: Array<EnvironmentModuleNode>
  read: () => string | Promise<string>
  server: ViteDevServer
}
this.environment is the module execution environment where a file update is currently being processed.
modules is an array of modules in this environment that are affected by the changed file. It's an array because a single file may map to multiple served modules (e.g. Vue SFCs).
read is an async read function that returns the content of the file. This is provided because on some systems, the file change callback may fire too fast before the editor finishes updating the file, and direct 
fs.readFile will return empty content. The read function passed in normalizes this behavior.
The hook can choose to:
Filter and narrow down the affected module list so that the HMR is more accurate.
Return an empty array and perform a full reload:
hotUpdate({ modules, timestamp }) {
  if (this.environment.name !== 'client')
    return
  // Invalidate modules manually
  const invalidatedModules = new Set()
  for (const mod of modules) {
    this.environment.moduleGraph.invalidateModule(
      mod,
      invalidatedModules,
      timestamp,
      true
    )
  }
  this.environment.hot.send({ type: 'full-reload' })
  return []
}
Return an empty array and perform complete custom HMR handling by sending custom events to the client:
hotUpdate() {
  if (this.environment.name !== 'client')
    return
  this.environment.hot.send({
    type: 'custom',
    event: 'special-update',
    data: {}
  })
  return []
}
Client code should register the corresponding handler using the HMR API (this could be injected by the same plugin's 
transform hook):
if (import.meta.hot) {
  import.meta.hot.on('special-update', (data) => {
    // perform custom update
  })
}
Per-environment State in Plugins
Given that the same plugin instance is used for different environments, the plugin state needs to be keyed with 
this.environment. This is the same pattern the ecosystem has already been using to keep state about modules using the 
ssr boolean as key to avoid mixing client and ssr modules state. A 
Map<Environment, State> can be used to keep the state for each environment separately. Note that for backward compatibility, 
buildStart and 
buildEnd are only called for the client environment without the 
perEnvironmentStartEndDuringDev: true flag. Same for 
watchChange and the 
perEnvironmentWatchChangeDuringDev: true flag.
function PerEnvironmentCountTransformedModulesPlugin() {
  const state = new Map<Environment, { count: number }>()
  return {
    name: 'count-transformed-modules',
    perEnvironmentStartEndDuringDev: true,
    buildStart() {
      state.set(this.environment, { count: 0 })
    },
    transform(id) {
      state.get(this.environment).count++
    },
    buildEnd() {
      console.log(this.environment.name, state.get(this.environment).count)
    }
  }
}
Per-environment Plugins Using the 
applyToEnvironment Hook
Type: 
(environment: PartialEnvironment) => boolean | PluginOption | Promise<boolean>
Kind: 
async, 
sequential
Scope: Per-environment
A plugin can define what are the environments it should apply to with the 
applyToEnvironment function.
const UnoCssPlugin = () => {
  // shared global state
  return {
    buildStart() {
      // init per-environment state with WeakMap<Environment,Data>
      // using this.environment
    },
    configureServer() {
      // use global hooks normally
    },
    applyToEnvironment(environment) {
      // return true if this plugin should be active in this environment,
      // or return a new plugin to replace it.
      // if the hook is not used, the plugin is active in all environments
    },
    resolveId(id, importer) {
      // only called for environments this plugin apply to
    },
  }
}
If a plugin isn't environment aware and has state that isn't keyed on the current environment, the 
applyToEnvironment hook allows to easily make it per-environment.
import { nonShareablePlugin } from 'non-shareable-plugin'
export default defineConfig({
  plugins: [
    {
      name: 'per-environment-plugin',
      applyToEnvironment(environment) {
        return nonShareablePlugin({ outputName: environment.name })
      },
    },
  ],
})
Vite exports a 
perEnvironmentPlugin helper to simplify these cases where no other hooks are required:
import { nonShareablePlugin } from 'non-shareable-plugin'
export default defineConfig({
  plugins: [
    perEnvironmentPlugin('per-environment-plugin', (environment) =>
      nonShareablePlugin({ outputName: environment.name }),
    ),
  ],
})
Note that the plugin returned from 
applyToEnvironment or 
perEnvironmentPlugin should not use Vite-specific hooks.
The 
applyToEnvironment hook is called at config time, currently after 
configResolved due to projects in the ecosystem modifying the plugins in it. Environment plugins resolution may be moved before 
configResolved in the future.
Application-Plugin Communication
environment.hot allows plugins to communicate with the code on the application side for a given environment. This is the equivalent of the Client-server Communication feature, but supports environments other than the client environment.
:::warning Note
Note that this feature is only available for environments that support HMR.
:::
Managing the Application Instances
Be aware that there might be multiple application instances running in the same environment. For example, if you have multiple tabs open in the browser, each tab is a separate application instance and has a separate connection to the server.
When a new connection is established, a 
vite:client:connect event is emitted on the environment's 
hot instance. When the connection is closed, a 
vite:client:disconnect event is emitted.
Each event handler receives the 
NormalizedHotChannelClient as the second argument. The client is an object with a 
send method that can be used to send messages to that specific application instance. The client reference is always the same for the same connection, so you can keep it to track the connection.
Example Usage
The plugin side:
configureServer(server) {
  server.environments.ssr.hot.on('my:greetings', (data, client) => {
    // do something with the data,
    // and optionally send a response to that application instance
    client.send('my:foo:reply', `Hello from server! You said: ${data}`)
  })
  // broadcast a message to all application instances
  server.environments.ssr.hot.send('my:foo', 'Hello from server!')
}
The application side is same with the Client-server Communication feature. You can use the 
import.meta.hot object to send messages to the plugin.
Environment in Build Hooks
In the same way as during dev, plugin hooks also receive the environment instance during build, replacing the 
ssr boolean.
This also works for 
renderChunk, 
generateBundle, and other build only hooks.
Shared Plugins During Build
Before Vite 6, the plugins pipelines worked in a different way during dev and build:
During dev: plugins are shared
During Build: plugins are isolated for each environment (in different processes: 
vite build then 
vite build --ssr).
This forced frameworks to share state between the 
client build and the 
ssr build through manifest files written to the file system. In Vite 6, we are now building all environments in a single process so the way the plugins pipeline and inter-environment communication can be aligned with dev.
In a future major, we could have complete alignment:
During both dev and build: plugins are shared, with per-environment filtering
There will also be a single 
ResolvedConfig instance shared during build, allowing for caching at entire app build process level in the same way as we have been doing with 
WeakMap<ResolvedConfig, CachedData> during dev.
For Vite 6, we need to do a smaller step to keep backward compatibility. Ecosystem plugins are currently using 
config.build instead of 
environment.config.build to access configuration, so we need to create a new 
ResolvedConfig per-environment by default. A project can opt-in into sharing the full config and plugins pipeline setting 
builder.sharedConfigBuild to 
true.
This option would only work of a small subset of projects at first, so plugin authors can opt-in for a particular plugin to be shared by setting the 
sharedDuringBuild flag to 
true. This allows for easily sharing state both for regular plugins:
function myPlugin() {
  // Share state among all environments in dev and build
  const sharedState = ...
  return {
    name: 'shared-plugin',
    transform(code, id) { ... },
    // Opt-in into a single instance for all environments
    sharedDuringBuild: true,
  }
}

Environment API for Runtimes
:::info Release Candidate
The Environment API is generally in the release candidate phase. We'll maintain stability in the APIs between major releases to allow the ecosystem to experiment and build upon them. However, note that some specific APIs are still considered experimental.
We plan to stabilize these new APIs (with potential breaking changes) in a future major release once downstream projects have had time to experiment with the new features and validate them.
Resources:
Feedback discussion where we are gathering feedback about the new APIs.
Environment API PR where the new APIs were implemented and reviewed.
Please share your feedback with us.
:::
This page is for runtime providers, authors who integrate a JavaScript runtime with Vite. A runtime here is the JavaScript engine where transformed code executes, such as Node.js, the browser, Cloudflare's workerd, or a Worker thread. A runtime provider packages the integration for one of these runtimes, so framework authors and end users (the developers building an app) don't have to set it up themselves.
Environment Factories
Environment factories are intended to be implemented by runtime providers, not by end users. Environment factories return an 
EnvironmentOptions for the most common case of using the target runtime for both dev and build environments. The default environment options can also be set so the user doesn't need to do it.
function createWorkerdEnvironment(
  userConfig: EnvironmentOptions,
): EnvironmentOptions {
  return mergeConfig(
    {
      resolve: {
        conditions: [/*...*/],
      },
      dev: {
        createEnvironment(name, config) {
          return createWorkerdDevEnvironment(name, config, {
            hot: true,
            transport: customHotChannel(),
          })
        },
      },
      build: {
        createEnvironment(name, config) {
          return createWorkerdBuildEnvironment(name, config)
        },
      },
    },
    userConfig,
  )
}
Then the config file can be written as:
import { createWorkerdEnvironment } from 'vite-environment-workerd'
export default {
  environments: {
    ssr: createWorkerdEnvironment({
      build: {
        outDir: '/dist/ssr',
      },
    }),
    rsc: createWorkerdEnvironment({
      build: {
        outDir: '/dist/rsc',
      },
    }),
  },
}
and frameworks can use an environment with the workerd runtime to do SSR using:
const ssrEnvironment = server.environments.ssr
Creating a New Environment Factory
A Vite dev server exposes two environments by default: a 
client environment and an 
ssr environment. The client environment is a browser environment by default, and the module runner is implemented by importing the virtual module 
/@vite/client to client apps. The SSR environment runs in the same Node runtime as the Vite server by default and allows application servers to be used to render requests during dev with full HMR support.
The transformed source code is called a module, and the relationships between the modules processed in each environment are kept in a module graph. The transformed code for these modules is sent to the runtimes associated with each environment to be executed. When a module is evaluated in the runtime, its imported modules will be requested triggering the processing of a section of the module graph.
A Vite Module Runner allows running any code by processing it with Vite plugins first. It is different from 
server.ssrLoadModule because the runner implementation is decoupled from the server. This allows library and framework authors to implement their layer of communication between the Vite server and the runner. The browser communicates with its corresponding environment using the server WebSocket and through HTTP requests. The Node Module runner can directly do function calls to process modules as it is running in the same process. Other environments could run modules connecting to a JS runtime like workerd, or a Worker Thread as Vitest does.
digraph module_runner {
  rankdir=LR
  node [shape=box style="rounded,filled" fontname="Arial" fontsize=11 margin="0.2,0.1" fontcolor="${#3c3c43|#ffffff}" color="${#c2c2c4|#3c3f44}"]
  edge [color="${#67676c|#98989f}" fontname="Arial" fontsize=10 fontcolor="${#67676c|#98989f}"]
  bgcolor="transparent"
  compound=true
  subgraph cluster_server {
    label="Vite Dev Server (Node.js)" labeljust=l fontname="Arial" fontsize=12
    style="rounded,filled" fillcolor="${#f6f6f7|#1a1a1f}" color="${#c2c2c4|#3c3f44}"
    fontcolor="${#3c3c43|#ffffff}"
    subgraph cluster_env {
      label="DevEnvironment" labeljust=l fontname="Arial" fontsize=11
      style="rounded,filled" fillcolor="${#f2ecfc|#2c273e}" color="${#c2c2c4|#3c3f44}"
      fontcolor="${#3c3c43|#ffffff}"
      plugins [label="Plugin\nPipeline" fillcolor="${#e9eaff|#222541}"]
      mg [label="Module\nGraph" fillcolor="${#e9eaff|#222541}"]
      hot [label="HotChannel" fillcolor="${#fcf4dc|#38301a}"]
      plugins -> mg [dir=both]
      mg -> hot [style=invis]
    }
  }
  subgraph cluster_runtime {
    label="Target Runtime" labeljust=l fontname="Arial" fontsize=12
    style="rounded,filled" fillcolor="${#f0fdf4|#131b15}" color="${#c2c2c4|#3c3f44}"
    fontcolor="${#3c3c43|#ffffff}"
    subgraph cluster_runner {
      label="ModuleRunner" labeljust=l fontname="Arial" fontsize=11
      style="rounded,filled" fillcolor="${#def5ed|#15312d}" color="${#c2c2c4|#3c3f44}"
      fontcolor="${#3c3c43|#ffffff}"
      evaluator [label="Module\nEvaluator" fillcolor="${#def5ed|#15312d}"]
      transport [label="Transport" fillcolor="${#fcf4dc|#38301a}"]
    }
  }
  hot -> transport [label="HMR / Module\nfetch & invoke" dir=both style=bold color="${#6f42c1|#c8abfa}"]
}
One of the goals of this feature is to provide a customizable API to process and run code. Users can create new environment factories using the exposed primitives.
import { DevEnvironment, HotChannel } from 'vite'
function createWorkerdDevEnvironment(
  name: string,
  config: ResolvedConfig,
  context: DevEnvironmentContext
) {
  const connection = /* ... */
  const transport: HotChannel = {
    on: (listener) => { connection.on('message', listener) },
    send: (data) => connection.send(data),
  }
  const workerdDevEnvironment = new DevEnvironment(name, config, {
    options: {
      resolve: { conditions: ['custom'] },
      ...context.options,
    },
    hot: true,
    transport,
  })
  return workerdDevEnvironment
}
By default, 
HotChannel transports have 
server.fs restrictions applied, meaning only files within the allowed directories can be served. If your transport is not exposed over the network (e.g., it communicates via worker threads or in-process calls), you can set 
skipFsCheck: true on the 
HotChannel to bypass these restrictions.
There are multiple communication levels for the 
DevEnvironment. To make it easier for frameworks to write runtime agnostic code, we recommend to implement the most flexible communication level possible.
ModuleRunner
A module runner is instantiated in the target runtime. All APIs in the next section are imported from 
vite/module-runner unless stated otherwise. This export entry point is kept as lightweight as possible, only exporting the minimal needed to create module runners.
Type Signature:
export class ModuleRunner {
  constructor(
    public options: ModuleRunnerOptions,
    public evaluator: ModuleEvaluator = new ESModulesEvaluator(),
    private debug?: ModuleRunnerDebugger,
  ) {}
  /**
   * URL to execute.
   * Accepts file path, server path, or id relative to the root.
   */
  public async import<T = any>(url: string): Promise<T>
  /**
   * Clear all caches including HMR listeners.
   */
  public clearCache(): void
  /**
   * Clear all caches, remove all HMR listeners, reset sourcemap support.
   * This method doesn't stop the HMR connection.
   */
  public async close(): Promise<void>
  /**
   * Returns `true` if the runner has been closed by calling `close()`.
   */
  public isClosed(): boolean
}
The module evaluator in 
ModuleRunner is responsible for executing the code. Vite exports 
ESModulesEvaluator out of the box, it uses 
new AsyncFunction to evaluate the code. You can provide your own implementation if your JavaScript runtime doesn't support unsafe evaluation.
Module runner exposes 
import method. When Vite server triggers 
full-reload HMR event, all affected modules will be re-executed. Be aware that Module Runner doesn't update 
exports object when this happens (it overrides it), you would need to run 
import or get the module from 
evaluatedModules again if you rely on having the latest 
exports object.
Example Usage:
import {
  ModuleRunner,
  ESModulesEvaluator,
  createNodeImportMeta,
} from 'vite/module-runner'
import { transport } from './rpc-implementation.js'
const moduleRunner = new ModuleRunner(
  {
    transport,
    createImportMeta: createNodeImportMeta, // if the module runner runs in Node.js
  },
  new ESModulesEvaluator(),
)
await moduleRunner.import('/src/entry-point.js')
ModuleRunnerOptions
import type { Debug } from '@type-challenges/utils'
import type {
  InterceptorOptions as InterceptorOptionsRaw,
  ModuleRunnerHmr as ModuleRunnerHmrRaw,
  EvaluatedModules,
} from 'vite/module-runner'
type InterceptorOptions = Debug<InterceptorOptionsRaw>
type ModuleRunnerHmr = Debug<ModuleRunnerHmrRaw>
/** see below */
type ModuleRunnerTransport = unknown
// ---cut---
interface ModuleRunnerOptions {
  /**
   * A set of methods to communicate with the server.
   */
  transport: ModuleRunnerTransport
  /**
   * Configure how source maps are resolved.
   * Prefers `node` if `process.setSourceMapsEnabled` is available.
   * Otherwise it will use `prepareStackTrace` by default which overrides
   * `Error.prepareStackTrace` method.
   * You can provide an object to configure how file contents and
   * source maps are resolved for files that were not processed by Vite.
   */
  sourcemapInterceptor?:
    | false
    | 'node'
    | 'prepareStackTrace'
    | InterceptorOptions
  /**
   * Disable HMR or configure HMR options.
   *
   * @default true
   */
  hmr?: boolean | ModuleRunnerHmr
  /**
   * Custom module cache. If not provided, it creates a separate module
   * cache for each module runner instance.
   */
  evaluatedModules?: EvaluatedModules
}
ModuleEvaluator
Type Signature:
import type { Debug } from '@type-challenges/utils'
import type { ModuleRunnerContext as ModuleRunnerContextRaw } from 'vite/module-runner'
type ModuleRunnerContext = Debug<ModuleRunnerContextRaw>
// ---cut---
export interface ModuleEvaluator {
  /**
   * Number of prefixed lines in the transformed code.
   */
  startOffset?: number
  /**
   * Evaluate code that was transformed by Vite.
   * @param context Function context
   * @param code Transformed code
   * @param id ID that was used to fetch the module
   */
  runInlinedModule(
    context: ModuleRunnerContext,
    code: string,
    id: string,
  ): Promise<any>
  /**
   * evaluate externalized module.
   * @param file File URL to the external module
   */
  runExternalModule(file: string): Promise<any>
}
Vite exports 
ESModulesEvaluator that implements this interface by default. It uses 
new AsyncFunction to evaluate code, so if the code has inlined source map it should contain an offset of 2 lines to accommodate for new lines added. This is done automatically by the 
ESModulesEvaluator. Custom evaluators will not add additional lines.
ModuleRunnerTransport
Type Signature:
import type { ModuleRunnerTransportHandlers } from 'vite/module-runner'
/** an object */
type HotPayload = unknown
// ---cut---
interface ModuleRunnerTransport {
  connect?(handlers: ModuleRunnerTransportHandlers): Promise<void> | void
  disconnect?(): Promise<void> | void
  send?(data: HotPayload): Promise<void> | void
  invoke?(data: HotPayload): Promise<{ result: any } | { error: any }>
  timeout?: number
}
Transport object that communicates with the environment via an RPC or by directly calling the function. When 
invoke method is not implemented, the 
send method and 
connect method is required to be implemented. Vite will construct the 
invoke internally.
You need to couple it with the 
HotChannel instance on the server like in this example where module runner is created in the worker thread:
::: code-group
import { fileURLToPath } from 'node:url'
import { parentPort } from 'node:worker_threads'
import {
  ESModulesEvaluator,
  ModuleRunner,
  createNodeImportMeta,
} from 'vite/module-runner'
/** @type {import('vite/module-runner').ModuleRunnerTransport} */
const transport = {
  connect({ onMessage, onDisconnection }) {
    parentPort.on('message', onMessage)
    parentPort.on('close', onDisconnection)
  },
  send(data) {
    parentPort.postMessage(data)
  },
}
const runner = new ModuleRunner(
  {
    transport,
    createImportMeta: createNodeImportMeta,
  },
  new ESModulesEvaluator(),
)
import { BroadcastChannel } from 'node:worker_threads'
import { createServer, DevEnvironment } from 'vite'
function createWorkerEnvironment(name, config, context) {
  const worker = new Worker('./worker.js')
  const handlerToWorkerListener = new WeakMap()
  const client = {
    send(payload: HotPayload) {
      worker.postMessage(payload)
    },
  }
  const workerHotChannel = {
    // Worker threads post messages are not exposed over the network, skip server.fs checks
    skipFsCheck: true,
    send: (data) => worker.postMessage(data),
    on: (event, handler) => {
      // client is already connected
      if (event === 'vite:client:connect') return
      if (event === 'vite:client:disconnect') {
        const listener = () => {
          handler(undefined, client)
        }
        handlerToWorkerListener.set(handler, listener)
        worker.on('exit', listener)
        return
      }
      const listener = (value) => {
        if (value.type === 'custom' && value.event === event) {
          handler(value.data, client)
        }
      }
      handlerToWorkerListener.set(handler, listener)
      worker.on('message', listener)
    },
    off: (event, handler) => {
      if (event === 'vite:client:connect') return
      if (event === 'vite:client:disconnect') {
        const listener = handlerToWorkerListener.get(handler)
        if (listener) {
          worker.off('exit', listener)
          handlerToWorkerListener.delete(handler)
        }
        return
      }
      const listener = handlerToWorkerListener.get(handler)
      if (listener) {
        worker.off('message', listener)
        handlerToWorkerListener.delete(handler)
      }
    },
  }
  return new DevEnvironment(name, config, {
    transport: workerHotChannel,
  })
}
await createServer({
  environments: {
    worker: {
      dev: {
        createEnvironment: createWorkerEnvironment,
      },
    },
  },
})
:::
Make sure to implement the 
vite:client:connect / 
vite:client:disconnect events in the 
on / 
off methods when those methods exist. 
vite:client:connect event should be emitted when the connection is established, and 
vite:client:disconnect event should be emitted when the connection is closed. The 
HotChannelClient object passed to the event handler must have the same reference for the same connection.
A different example using an HTTP request to communicate between the runner and the server:
import { ESModulesEvaluator, ModuleRunner } from 'vite/module-runner'
export const runner = new ModuleRunner(
  {
    transport: {
      async invoke(data) {
        const response = await fetch(`http://my-vite-server/invoke`, {
          method: 'POST',
          body: JSON.stringify(data),
        })
        return response.json()
      },
    },
    hmr: false, // disable HMR as HMR requires transport.connect
  },
  new ESModulesEvaluator(),
)
await runner.import('/entry.js')
In this case, the 
handleInvoke method in the 
NormalizedHotChannel can be used:
const customEnvironment = new DevEnvironment(name, config, context)
server.onRequest((request: Request) => {
  const url = new URL(request.url)
  if (url.pathname === '/invoke') {
    const payload = (await request.json()) as HotPayload
    const result = customEnvironment.hot.handleInvoke(payload)
    return new Response(JSON.stringify(result))
  }
  return Response.error()
})
But note that for HMR support, 
send and 
connect methods are required. The 
send method is usually called when the custom event is triggered (like, 
import.meta.hot.send("my-event")).
For an SSR environment running in the same Node.js process as the Vite server, Vite exports 
createServerHotChannel as a ready-made 
HotChannel:
import { createServerHotChannel, DevEnvironment } from 'vite'
new DevEnvironment(name, config, {
  hot: true,
  transport: createServerHotChannel(),
})

Environment API
:::info Release Candidate
The Environment API is generally in the release candidate phase. We'll maintain stability in the APIs between major releases to allow the ecosystem to experiment and build upon them. However, note that some specific APIs are still considered experimental.
We plan to stabilize these new APIs (with potential breaking changes) in a future major release once downstream projects have had time to experiment with the new features and validate them.
Resources:
Feedback discussion where we are gathering feedback about the new APIs.
Environment API PR where the new APIs were implemented and reviewed.
Please share your feedback with us.
:::
Formalizing Environments
Vite 6 formalizes the concept of Environments. Until Vite 5, there were two implicit Environments (
client, and optionally 
ssr). The new Environment API allows users and framework authors to create as many environments as needed to map the way their apps work in production. This new capability required a big internal refactoring, but a lot of effort has been placed on backward compatibility. The initial goal of Vite 6 is to move the ecosystem to the new major as smoothly as possible, delaying the adoption of the APIs until enough users have migrated and frameworks and plugin authors have validated the new design.
Closing the Gap Between Build and Dev
For a simple SPA/MPA, no new APIs around environments are exposed to the config. Internally, Vite will apply the options to a 
client environment, but it's not necessary to know of this concept when configuring Vite. The config and behavior from Vite 5 should work seamlessly here.
When we move to a typical server-side rendered (SSR) app, we'll have two environments:
client: runs the app in the browser.
ssr: runs the app in node (or other server runtimes) which renders pages before sending them to the browser.
In dev, Vite executes the server code in the same Node process as the Vite dev server, giving a close approximation to the production environment. However, it is also possible for servers to run in other JS runtimes, like Cloudflare's workerd which have different constraints. Modern apps may also run in more than two environments, e.g. a browser, a node server, and an edge server. Vite 5 didn't allow these environments to be properly represented.
Vite 6 allows users to configure their app during build and dev to map all of its environments. During dev, a single Vite dev server can now be used to run code in multiple different environments concurrently. The app source code is still transformed by Vite dev server. On top of the shared HTTP server, middlewares, resolved config, and plugins pipeline, the Vite dev server now has a set of independent dev environments. Each of them is configured to match the production environment as closely as possible, and is connected to a dev runtime where the code is executed (for workerd, the server code can now run in miniflare locally). In the client, the browser imports and executes the code. In other environments, a module runner fetches and evaluates the transformed code.
Environments Configuration
For an SPA/MPA, the configuration will look similar to Vite 5. Internally these options are used to configure the 
client environment.
export default defineConfig({
  build: {
    sourcemap: false,
  },
  optimizeDeps: {
    include: ['lib'],
  },
})
This is important because we'd like to keep Vite approachable and avoid exposing new concepts until they are needed.
If the app is composed of several environments, then these environments can be configured explicitly with the 
environments config option.
export default {
  build: {
    sourcemap: false,
  },
  optimizeDeps: {
    include: ['lib'],
  },
  environments: {
    server: {},
    edge: {
      resolve: {
        noExternal: true,
      },
    },
  },
}
When not explicitly documented, environment inherits the configured top-level config options (for example, the new 
server and 
edge environments will inherit the 
build.sourcemap: false option). A small number of top-level options, like 
optimizeDeps, only apply to the 
client environment, as they don't work well when applied as a default to server environments. Those options have  badge in the reference. The 
client environment can also be configured explicitly through 
environments.client, but we recommend to do it with the top-level options so the client config remains unchanged when adding new environments.
The 
EnvironmentOptions interface exposes all the per-environment options. There are environment options that apply to both 
build and 
dev, like 
resolve. And there are 
DevEnvironmentOptions and 
BuildEnvironmentOptions for dev and build specific options (like 
dev.warmup or 
build.outDir). Some options like 
optimizeDeps only applies to dev, but is kept as top level instead of nested in 
dev for backward compatibility.
interface EnvironmentOptions {
  define?: Record<string, any>
  resolve?: EnvironmentResolveOptions
  optimizeDeps: DepOptimizationOptions
  consumer?: 'client' | 'server'
  dev: DevOptions
  build: BuildOptions
}
The 
UserConfig interface extends from the 
EnvironmentOptions interface, allowing to configure the client and defaults for other environments, configured through the 
environments option. The 
client and a server environment named 
ssr are always present during dev. This allows backward compatibility with 
server.ssrLoadModule(url) and 
server.moduleGraph. During build, the 
client environment is always present, and the 
ssr environment is only present if it is explicitly configured (using 
environments.ssr or for backward compatibility 
build.ssr). An app doesn't need to use the 
ssr name for its SSR environment, it could name it 
server for example.
interface UserConfig extends EnvironmentOptions {
  environments: Record<string, EnvironmentOptions>
  // other options
}
Note that the 
ssr top-level property is going to be deprecated once the Environment API is stable. This option has the same role as 
environments, but for the default 
ssr environment and only allowed configuring of a small set of options.
Custom Environment Instances
Low level configuration APIs are available so runtime providers can provide environments with proper defaults for their runtimes. These environments can also spawn other processes or threads to run the modules during dev in a closer runtime to the production environment.
For example, the Cloudflare Vite plugin uses the Environment API to run code in the Cloudflare Workers runtime (
workerd) during development.
import { customEnvironment } from 'vite-environment-provider'
export default {
  build: {
    outDir: '/dist/client',
  },
  environments: {
    ssr: customEnvironment({
      build: {
        outDir: '/dist/ssr',
      },
    }),
  },
}
Backward Compatibility
The current Vite server API is not yet deprecated and is backward compatible with Vite 5.
The 
server.moduleGraph returns a mixed view of the client and ssr module graphs. Backward compatible mixed module nodes will be returned from all its methods. The same scheme is used for the module nodes passed to 
handleHotUpdate.
We don't recommend switching to Environment API yet. We are aiming for a good portion of the user base to adopt Vite 6 before so plugins don't need to maintain two versions. Checkout the future breaking changes section for information on future deprecations and upgrade path:
this.environment in Hooks
HMR 
hotUpdate Plugin Hook
Move to Per-environment APIs
SSR Using 
ModuleRunner API
Shared Plugins During Build
Target Users
This guide provides the basic concepts about environments for end users.
Plugin authors have a more consistent API available to interact with the current environment configuration. If you're building on top of Vite, the Environment API Plugins Guide guide describes the way extended plugin APIs available to support multiple custom environments.
Frameworks could decide to expose environments at different levels. If you're a framework author, continue reading the Environment API Frameworks Guide to learn about the Environment API programmatic side.
For Runtime providers, the Environment API Runtimes Guide explains how to offer custom environments to be consumed by frameworks and users.

HMR API
:::tip Note
This is the client HMR API. For handling HMR update in plugins, see handleHotUpdate.
The manual HMR API is primarily intended for framework and tooling authors. As an end user, HMR is likely already handled for you in the framework specific starter templates.
:::
Vite exposes its manual HMR API via the special 
import.meta.hot object:
import type {
  CustomEventName,
  InferCustomEventPayload,
} from 'vite/types/customEvent.d.ts'
import type { ModuleNamespace } from 'vite/types/hot.d.ts'
// ---cut---
interface ImportMeta {
  readonly hot?: ViteHotContext
}
interface ViteHotContext {
  readonly data: any
  accept(): void
  accept(cb: (mod: ModuleNamespace | undefined) => void): void
  accept(dep: string, cb: (mod: ModuleNamespace | undefined) => void): void
  accept(
    deps: readonly string[],
    cb: (mods: Array<ModuleNamespace | undefined>) => void,
  ): void
  dispose(cb: (data: any) => void): void
  prune(cb: (data: any) => void): void
  invalidate(message?: string): void
  on<T extends CustomEventName>(
    event: T,
    cb: (payload: InferCustomEventPayload<T>) => void,
  ): void
  off<T extends CustomEventName>(
    event: T,
    cb: (payload: InferCustomEventPayload<T>) => void,
  ): void
  send<T extends CustomEventName>(
    event: T,
    data?: InferCustomEventPayload<T>,
  ): void
}
Required Conditional Guard
First of all, make sure to guard all HMR API usage with a conditional block so that the code can be tree-shaken in production:
if (import.meta.hot) {
  // HMR code
}
IntelliSense for TypeScript
Vite provides type definitions for 
import.meta.hot in 
vite/client.d.ts. You can add "vite/client" in the 
tsconfig.json so TypeScript picks up the type definitions:
{
  "compilerOptions": {
    "types": ["vite/client"]
  }
}
hot.accept(cb)
For a module to self-accept, use 
import.meta.hot.accept with a callback which receives the updated module:
import 'vite/client'
// ---cut---
export const count = 1
if (import.meta.hot) {
  import.meta.hot.accept((newModule) => {
    if (newModule) {
      // newModule is undefined when SyntaxError happened
      console.log('updated: count is now ', newModule.count)
    }
  })
}
A module that "accepts" hot updates is considered an HMR boundary.
digraph hmr_boundary {
  rankdir=RL
  ranksep=0.3
  node [shape=box style="rounded,filled" fontname="Arial" fontsize=11 margin="0.2,0.1" fontcolor="${#3c3c43|#ffffff}" color="${#c2c2c4|#3c3f44}"]
  edge [color="${#67676c|#98989f}" fontname="Arial" fontsize=10 fontcolor="${#67676c|#98989f}"]
  bgcolor="transparent"
  root [label="main.js" fillcolor="${#f6f6f7|#2e2e32}"]
  parent [label="App.vue" fillcolor="${#f6f6f7|#2e2e32}"]
  boundary [label="Component.vue\n(HMR boundary)\nhot.accept()" fillcolor="${#def5ed|#15312d}" color="${#18794e|#3dd68c}" penwidth=2]
  edited [label="utils.js\n(edited)" fillcolor="${#fcf4dc|#38301a}" color="${#915930|#f9b44e}" penwidth=2]
  boundary -> edited [label="imports" color="${#915930|#f9b44e}" style=bold]
  parent -> boundary [label="imports" style=dashed]
  root -> parent [label="imports" style=dashed]
}
Vite's HMR does not actually swap the originally imported module: if an HMR boundary module re-exports imports from a dep, then it is responsible for updating those re-exports (and these exports must be using 
let). In addition, importers up the chain from the boundary module will not be notified of the change. This simplified HMR implementation is sufficient for most dev use cases, while allowing us to skip the expensive work of generating proxy modules.
Vite requires that the call to this function appears as 
import.meta.hot.accept( (whitespace-sensitive) in the source code in order for the module to accept update. This is a requirement of the static analysis that Vite does to enable HMR support for a module.
hot.accept(deps, cb)
A module can also accept updates from direct dependencies without reloading itself:
// @filename: /foo.d.ts
export declare const foo: () => void
// @filename: /example.js
import 'vite/client'
// ---cut---
import { foo } from './foo.js'
foo()
if (import.meta.hot) {
  import.meta.hot.accept('./foo.js', (newFoo) => {
    // the callback receives the updated './foo.js' module
    newFoo?.foo()
  })
  // Can also accept an array of dep modules:
  import.meta.hot.accept(
    ['./foo.js', './bar.js'],
    ([newFooModule, newBarModule]) => {
      // The callback receives an array where only the updated module is
      // non null. If the update was not successful (syntax error for ex.),
      // the array is empty
    },
  )
}
hot.dispose(cb)
A self-accepting module or a module that expects to be accepted by others can use 
hot.dispose to clean-up any persistent side effects created by its updated copy:
import 'vite/client'
// ---cut---
function setupSideEffect() {}
setupSideEffect()
if (import.meta.hot) {
  import.meta.hot.dispose((data) => {
    // cleanup side effect
  })
}
hot.prune(cb)
Register a callback that will be called when the module is no longer imported on the page. Compared to 
hot.dispose, this can be used if the source code cleans up side-effects by itself on updates and you only need to clean-up when it's removed from the page. Vite currently uses this for 
.css imports.
import 'vite/client'
// ---cut---
function setupOrReuseSideEffect() {}
setupOrReuseSideEffect()
if (import.meta.hot) {
  import.meta.hot.prune((data) => {
    // cleanup side effect
  })
}
hot.data
Vite creates one 
import.meta.hot.data object for each module path. The object is persisted across successive instances of the same module during HMR. Mutations made during module execution or through the 
data argument passed to 
hot.dispose are visible to the next instance of the module.
When a module is pruned, its 
hot.dispose and 
hot.prune callbacks receive the current data object. Vite clears the data after those callbacks complete. If the module is imported again later, it receives a new empty data object.
Note that re-assignment of 
data itself is not supported. Instead, you should mutate properties of the 
data object so information added from other handlers are preserved.
import 'vite/client'
// ---cut---
// ok
import.meta.hot.data.someValue = 'hello'
// not supported
import.meta.hot.data = { someValue: 'hello' }
hot.decline()
This is currently a noop and is there for backward compatibility. This could change in the future if there is a new usage for it. To indicate that the module is not hot-updatable, use 
hot.invalidate().
hot.invalidate(message?: string)
A self-accepting module may realize during runtime that it can't handle a HMR update, and so the update needs to be forcefully propagated to importers. By calling 
import.meta.hot.invalidate(), the HMR server will invalidate the importers of the caller, as if the caller wasn't self-accepting. This will log a message both in the browser console and in the terminal. You can pass a message to give some context on why the invalidation happened.
Note that you should always call 
import.meta.hot.accept even if you plan to call 
invalidate immediately afterwards, or else the HMR client won't listen for future changes to the self-accepting module. To communicate your intent clearly, we recommend calling 
invalidate within the 
accept callback like so:
import 'vite/client'
// ---cut---
import.meta.hot.accept((module) => {
  // You may use the new module instance to decide whether to invalidate.
  if (cannotHandleUpdate(module)) {
    import.meta.hot.invalidate()
  }
})
hot.on(event, cb)
Listen to an HMR event.
The following HMR events are dispatched by Vite automatically:
'vite:beforeUpdate' when an update is about to be applied (e.g. a module will be replaced)
'vite:afterUpdate' when an update has just been applied (e.g. a module has been replaced)
'vite:beforeFullReload' when a full reload is about to occur
'vite:beforePrune' when modules that are no longer needed are about to be pruned
'vite:invalidate' when a module is invalidated with 
import.meta.hot.invalidate()
'vite:error' when an error occurs (e.g. syntax error)
'vite:ws:disconnect' when the WebSocket connection is lost
'vite:ws:connect' when the WebSocket connection is (re-)established
Custom HMR events can also be sent from plugins. See handleHotUpdate for more details.
hot.off(event, cb)
Remove callback from the event listeners.
hot.send(event, data)
Send custom events back to Vite's dev server.
If called before connected, the data will be buffered and sent once the connection is established.
See Client-server Communication for more details, including a section on Typing Custom Events.
Further Reading
If you'd like to learn more about how to use the HMR API and how it works under-the-hood. Check out these resources:
Hot Module Replacement is Easy

JavaScript API
Vite's JavaScript APIs are fully typed, and it's recommended to use TypeScript or enable JS type checking in VS Code to leverage the IntelliSense and validation.
createServer
Type Signature:
async function createServer(inlineConfig?: InlineConfig): Promise<ViteDevServer>
Example Usage:
import { createServer } from 'vite'
const server = await createServer({
  // any valid user config options, plus `mode` and `configFile`
  configFile: false,
  root: import.meta.dirname,
  server: {
    port: 1337,
  },
})
await server.listen()
server.printUrls()
server.bindCLIShortcuts({ print: true })
::: tip NOTE
When using 
createServer and 
build in the same Node.js process, both functions rely on 
process.env.NODE_ENV to work properly, which also depends on the 
mode config option. To prevent conflicting behavior, set 
process.env.NODE_ENV or the 
mode of the two APIs to 
development. Otherwise, you can spawn a child process to run the APIs separately.
:::
::: tip NOTE
When using middleware mode combined with proxy config for WebSocket, the parent http server should be provided in 
middlewareMode to bind the proxy correctly.
Example
import http from 'http'
import { createServer } from 'vite'
const parentServer = http.createServer() // or express, koa, etc.
const vite = await createServer({
  server: {
    // Enable middleware mode
    middlewareMode: {
      // Provide the parent http server for proxy WebSocket
      server: parentServer,
    },
    proxy: {
      '/ws': {
        target: 'ws://localhost:3000',
        // Proxying WebSocket
        ws: true,
      },
    },
  },
})
// @noErrors: 2339
parentServer.use(vite.middlewares)
:::
InlineConfig
The 
InlineConfig interface extends 
UserConfig with additional properties:
configFile: specify config file to use. If not set, Vite will try to automatically resolve one from project root. Set to 
false to disable auto resolving.
ResolvedConfig
The 
ResolvedConfig interface has all the same properties of a 
UserConfig, except most properties are resolved and non-undefined. It also contains utilities like:
config.assetsInclude: A function to check if an 
id is considered an asset.
config.logger: Vite's internal logger object.
ViteDevServer
interface ViteDevServer {
  /**
   * The resolved Vite config object.
   */
  config: ResolvedConfig
  /**
   * A connect app instance
   * - Can be used to attach custom middlewares to the dev server.
   * - Can also be used as the handler function of a custom http server
   *   or as a middleware in any connect-style Node.js frameworks.
   *
   * https://github.com/senchalabs/connect#use-middleware
   */
  middlewares: Connect.Server
  /**
   * Native Node http server instance.
   * Will be null in middleware mode.
   */
  httpServer: http.Server | null
  /**
   * Chokidar watcher instance. If `config.server.watch` is set to `null`,
   * it will not watch any files and calling `add` or `unwatch` will have no effect.
   * https://github.com/paulmillr/chokidar/tree/3.6.0#api
   */
  watcher: FSWatcher
  /**
   * WebSocket server with `send(payload)` method.
   */
  ws: WebSocketServer
  /**
   * Rollup plugin container that can run plugin hooks on a given file.
   */
  pluginContainer: PluginContainer
  /**
   * Module graph that tracks the import relationships, url to file mapping
   * and hmr state.
   */
  moduleGraph: ModuleGraph
  /**
   * The resolved urls Vite prints on the CLI (URL-encoded). Returns `null`
   * in middleware mode or if the server is not listening on any port.
   */
  resolvedUrls: ResolvedServerUrls | null
  /**
   * Programmatically resolve, load and transform a URL and get the result
   * without going through the http request pipeline.
   */
  transformRequest(
    url: string,
    options?: TransformOptions,
  ): Promise<TransformResult | null>
  /**
   * Apply Vite built-in HTML transforms and any plugin HTML transforms.
   */
  transformIndexHtml(
    url: string,
    html: string,
    originalUrl?: string,
  ): Promise<string>
  /**
   * Load a given URL as an instantiated module for SSR.
   */
  ssrLoadModule(
    url: string,
    options?: { fixStacktrace?: boolean },
  ): Promise<Record<string, any>>
  /**
   * Fix ssr error stacktrace.
   */
  ssrFixStacktrace(e: Error): void
  /**
   * Triggers HMR for a module in the module graph. You can use the `server.moduleGraph`
   * API to retrieve the module to be reloaded. If `hmr` is false, this is a no-op.
   */
  reloadModule(module: ModuleNode): Promise<void>
  /**
   * Start the server.
   */
  listen(port?: number, isRestart?: boolean): Promise<ViteDevServer>
  /**
   * Restart the server.
   *
   * @param forceOptimize - force the optimizer to re-bundle, same as --force cli flag
   */
  restart(forceOptimize?: boolean): Promise<void>
  /**
   * Stop the server.
   */
  close(): Promise<void>
  /**
   * Bind CLI shortcuts
   */
  bindCLIShortcuts(options?: BindCLIShortcutsOptions<ViteDevServer>): void
  /**
   * Calling `await server.waitForRequestsIdle(id)` will wait until all static imports
   * are processed. If called from a load or transform plugin hook, the id needs to be
   * passed as a parameter to avoid deadlocks. Calling this function after the first
   * static imports section of the module graph has been processed will resolve immediately.
   * @experimental
   */
  waitForRequestsIdle: (ignoredId?: string) => Promise<void>
}
:::info
waitForRequestsIdle is meant to be used as an escape hatch to improve DX for features that can't be implemented following the on-demand nature of the Vite dev server. It can be used during startup by tools like Tailwind to delay generating the app CSS classes until the app code has been seen, avoiding flashes of style changes. When this function is used in a load or transform hook, and the default HTTP1 server is used, one of the six http channels will be blocked until the server processes all static imports. Vite's dependency optimizer currently uses this function to avoid full-page reloads on missing dependencies by delaying loading of pre-bundled dependencies until all imported dependencies have been collected from static imported sources. Vite may switch to a different strategy in a future major release, setting 
optimizeDeps.holdUntilCrawlEnd: false by default to avoid the performance hit in large applications during cold start.
:::
build
Type Signature:
async function build(
  inlineConfig?: InlineConfig,
): Promise<RolldownOutput | RolldownOutput[] | RolldownWatcher>
Example Usage:
import path from 'node:path'
import { build } from 'vite'
await build({
  root: path.resolve(import.meta.dirname, './project'),
  base: '/foo/',
  build: {
    rolldownOptions: {
      // ...
    },
  },
})
preview
Type Signature:
async function preview(inlineConfig?: InlineConfig): Promise<PreviewServer>
Example Usage:
import { preview } from 'vite'
const previewServer = await preview({
  // any valid user config options, plus `mode` and `configFile`
  preview: {
    port: 8080,
    open: true,
  },
})
previewServer.printUrls()
previewServer.bindCLIShortcuts({ print: true })
PreviewServer
interface PreviewServer {
  /**
   * The resolved vite config object
   */
  config: ResolvedConfig
  /**
   * A connect app instance.
   * - Can be used to attach custom middlewares to the preview server.
   * - Can also be used as the handler function of a custom http server
   *   or as a middleware in any connect-style Node.js frameworks
   *
   * https://github.com/senchalabs/connect#use-middleware
   */
  middlewares: Connect.Server
  /**
   * native Node http server instance
   */
  httpServer: http.Server
  /**
   * The resolved urls Vite prints on the CLI (URL-encoded). Returns `null`
   * if the server is not listening on any port.
   */
  resolvedUrls: ResolvedServerUrls | null
  /**
   * Print server urls
   */
  printUrls(): void
  /**
   * Bind CLI shortcuts
   */
  bindCLIShortcuts(options?: BindCLIShortcutsOptions<PreviewServer>): void
}
resolveConfig
Type Signature:
async function resolveConfig(
  inlineConfig: InlineConfig,
  command: 'build' | 'serve',
  defaultMode = 'development',
  defaultNodeEnv = 'development',
  isPreview = false,
): Promise<ResolvedConfig>
The 
command value is 
serve in dev and preview, and 
build in build.
mergeConfig
Type Signature:
function mergeConfig(
  defaults: Record<string, any>,
  overrides: Record<string, any>,
  isRoot = true,
): Record<string, any>
Deeply merge two Vite configs. 
isRoot represents the level within the Vite config which is being merged. For example, set 
false if you're merging two 
build options.
Note that 
null and 
undefined values in 
overrides are skipped and not merged. If you need to explicitly clear a value from 
defaults, modify the result of 
mergeConfig directly.
::: tip NOTE
mergeConfig accepts only config in object form. If you have a config in callback form, you should call it before passing into 
mergeConfig.
You can use the 
defineConfig helper to merge a config in callback form with another config:
import {
  defineConfig,
  mergeConfig,
  type UserConfigFnObject,
  type UserConfig,
} from 'vite'
declare const configAsCallback: UserConfigFnObject
declare const configAsObject: UserConfig
// ---cut---
export default defineConfig((configEnv) =>
  mergeConfig(configAsCallback(configEnv), configAsObject),
)
:::
searchForWorkspaceRoot
Type Signature:
function searchForWorkspaceRoot(
  current: string,
  root = searchForPackageRoot(current),
): string
Related: server.fs.allow
Search for the root of the potential workspace if it meets the following conditions, otherwise it would fallback to 
root:
contains 
workspaces field in 
package.json
contains one of the following file
lerna.json
pnpm-workspace.yaml
loadEnv
Type Signature:
function loadEnv(
  mode: string,
  envDir: string,
  prefixes: string | string[] = 'VITE_',
): Record<string, string>
Related: 
.env Files
Load 
.env files within the 
envDir and merge them with the matching variables already present in 
process.env. By default, only env variables prefixed with 
VITE_ are loaded, unless 
prefixes is changed.
normalizePath
Type Signature:
function normalizePath(id: string): string
Related: Path Normalization
Normalizes a path to interoperate between Vite plugins.
transformWithOxc
Type Signature:
async function transformWithOxc(
  code: string,
  filename: string,
  options?: OxcTransformOptions,
  inMap?: object,
): Promise<Omit<OxcTransformResult, 'errors'> & { warnings: string[] }>
Transform JavaScript or TypeScript with Oxc Transformer. Useful for plugins that prefer matching Vite's internal Oxc Transformer transform.
transformWithEsbuild
Type Signature:
async function transformWithEsbuild(
  code: string,
  filename: string,
  options?: EsbuildTransformOptions,
  inMap?: object,
): Promise<ESBuildTransformResult>
Deprecated: Use 
transformWithOxc instead.
Transform JavaScript or TypeScript with esbuild. Useful for plugins that prefer matching Vite's internal esbuild transform.
loadConfigFromFile
Type Signature:
async function loadConfigFromFile(
  configEnv: ConfigEnv,
  configFile?: string,
  configRoot: string = process.cwd(),
  logLevel?: LogLevel,
  customLogger?: Logger,
): Promise<{
  path: string
  config: UserConfig
  dependencies: string[]
} | null>
Load a Vite config file manually with Rolldown.
preprocessCSS
Experimental: Give Feedback
Type Signature:
async function preprocessCSS(
  code: string,
  filename: string,
  config: ResolvedConfig,
): Promise<PreprocessCSSResult>
interface PreprocessCSSResult {
  code: string
  map?: SourceMapInput
  modules?: Record<string, string>
  deps?: Set<string>
}
Pre-processes 
.css, 
.scss, 
.sass, 
.less, 
.styl and 
.stylus files to plain CSS so it can be used in browsers or parsed by other tools. Similar to the built-in CSS pre-processing support, the corresponding pre-processor must be installed if used.
The pre-processor used is inferred from the 
filename extension. If the 
filename ends with 
.module.{ext}, it is inferred as a CSS module and the returned result will include a 
modules object mapping the original class names to the transformed ones.
Note that pre-processing will not resolve URLs in 
url() or 
image-set().
version
Type: 
string
The current version of Vite as a string (e.g. 
"8.0.0").
rolldownVersion
Type: 
string
The version of Rolldown used by Vite as a string (e.g. 
"1.0.0"). A re-export of 
VERSION from 
rolldown.
esbuildVersion
Type: 
string
Only kept for backward compatibility.
rollupVersion
Type: 
string
Only kept for backward compatibility.

Plugin API
Vite plugins extends Rolldown's plugin interface with a few extra Vite-specific options. As a result, you can write a Vite plugin once and have it work for both dev and build.
It is recommended to go through Rolldown's plugin documentation first before reading the sections below.
Authoring a Plugin
Vite strives to offer established patterns out of the box, so before creating a new plugin make sure that you check the Features guide to see if your need is covered. Also review available community plugins, both in the form of a compatible Rollup plugin and Vite Specific plugins.
When creating a plugin, you can inline it in your 
vite.config.js. There is no need to create a new package for it. Once you see that a plugin was useful in your projects, consider sharing it to help others in the ecosystem.
::: tip
When learning, debugging, or authoring plugins, we suggest including vite-plugin-inspect in your project. It allows you to inspect the intermediate state of Vite plugins. After installing, you can visit 
localhost:5173/__inspect/ to inspect the modules and transformation stack of your project. Check out install instructions in the vite-plugin-inspect docs.
:::
Conventions
If the plugin doesn't use Vite specific hooks and can be implemented as a Compatible Rolldown Plugin, then it is recommended to use the Rolldown Plugin naming conventions.
Rolldown Plugins should have a clear name with 
rolldown-plugin- prefix.
Include 
rolldown-plugin and 
vite-plugin keywords in package.json 
keywords field.
This exposes the plugin to be also used in pure Rolldown or Rollup based projects.
For Vite only plugins
Vite Plugins should have a clear name with 
vite-plugin- prefix.
Include 
vite-plugin keyword in package.json 
keywords field.
Include a section in the plugin docs detailing why it is a Vite only plugin (for example, it uses Vite specific plugin hooks).
If your plugin is only going to work for a particular framework, its name should be included as part of the prefix.
vite-plugin-vue- prefix for Vue Plugins
vite-plugin-react- prefix for React Plugins
vite-plugin-svelte- prefix for Svelte Plugins
See also Virtual Modules Convention.
Plugins Config
Users will add plugins to the project 
devDependencies and configure them using the 
plugins array option.
import rollupPlugin from 'rollup-plugin-feature'
import vitePlugin from 'vite-plugin-feature'
export default defineConfig({
  plugins: [vitePlugin(), rollupPlugin()],
})
Falsy plugins will be ignored, which can be used to easily activate or deactivate plugins.
plugins also accepts presets including several plugins as a single element. This is useful for complex features (like framework integration) that are implemented using several plugins. The array will be flattened internally.
import frameworkDevTools from 'vite-plugin-framework-devtools'
import frameworkRefresh from 'vite-plugin-framework-refresh'
export default function framework(config) {
  return [frameworkRefresh(config), frameworkDevTools(config)]
}
import { defineConfig } from 'vite'
import framework from 'vite-plugin-framework'
export default defineConfig({
  plugins: [framework()],
})
Simple Examples
:::tip
It is common convention to author a Vite/Rolldown/Rollup plugin as a factory function that returns the actual plugin object. The function can accept options which allows users to customize the behavior of the plugin.
:::
Transforming Custom File Types
const fileRegex = /\.(my-file-ext)$/
export default function myPlugin() {
  return {
    name: 'transform-file',
    transform: {
      filter: {
        id: fileRegex,
      },
      handler(src, id) {
        return {
          code: compileFileToJS(src),
          map: null, // provide source map if available
        }
      },
    },
  }
}
Importing a Virtual File
Virtual modules allow you to pass build time information to the source files using normal ESM import syntax. See Virtual Modules Convention for the full convention.
import { exactRegex } from '@rolldown/pluginutils'
export default function myPlugin() {
  const virtualModuleId = 'virtual:my-module'
  const resolvedVirtualModuleId = '\0' + virtualModuleId
  return {
    name: 'my-plugin', // required, will show up in warnings and errors
    resolveId: {
      filter: { id: exactRegex(virtualModuleId) },
      handler() {
        return resolvedVirtualModuleId
      },
    },
    load: {
      filter: { id: exactRegex(resolvedVirtualModuleId) },
      handler() {
        return `export const msg = "from virtual module"`
      },
    },
  }
}
Which allows importing the module in JavaScript:
import { msg } from 'virtual:my-module'
console.log(msg)
In Vite, since 
\0 is not a permitted char in import URLs, a 
\0{id} virtual id ends up encoded as 
/@id/__x00__{id} during dev in the browser. The id is decoded back before entering the plugins pipeline, so this is not seen by plugin hooks code.
Rolldown Hooks
During dev, the Vite dev server creates a plugin container that invokes Rolldown Build Hooks the same way Rolldown does it.
All rolldown hooks are per-environment hooks.
The following hooks are called once on server start:
options
buildStart
The following hooks are called on each incoming module request:
resolveId
load
transform
These hooks also have an extended 
options parameter with additional Vite-specific properties. You can read more in the SSR documentation.
Some 
resolveId calls' 
importer value may be an absolute path for a generic 
index.html at root as it's not always possible to derive the actual importer due to Vite's unbundled dev server pattern. For imports handled within Vite's resolve pipeline, the importer can be tracked during the import analysis phase, providing the correct 
importer value.
The following hooks are called when the server is closed:
buildEnd
closeBundle
Note that the 
moduleParsed hook is not called during dev, because Vite avoids full AST parses for better performance.
Output Generation Hooks (except 
closeBundle) are not called during dev.
Vite Specific Hooks
Vite plugins can also provide hooks that serve Vite-specific purposes. These hooks are ignored by Rollup.
config
Type: 
(config: UserConfig, env: { mode: 'build' | 'serve', command: string, isSsrBuild?: boolean, isPreview?: boolean }) => UserConfig | null | void
Kind: 
async, 
sequential
Scope: Global
Modify Vite config before it's resolved. The hook receives the raw user config (CLI options merged with config file) and the current config env which exposes the 
mode and 
command being used. It can return a partial config object that will be deeply merged into existing config, or directly mutate the config (if the default merging cannot achieve the desired result).
Example:
// return partial config (recommended)
const partialConfigPlugin = () => ({
  name: 'return-partial',
  config: () => ({
    resolve: {
      alias: {
        foo: 'bar',
      },
    },
  }),
})
// mutate the config directly (use only when merging doesn't work)
const mutateConfigPlugin = () => ({
  name: 'mutate-config',
  config(config, { command }) {
    if (command === 'build') {
      config.root = 'foo'
    }
  },
})
::: warning Note
User plugins are resolved before running this hook so injecting other plugins inside the 
config hook will have no effect.
:::
configResolved
Type: 
(config: ResolvedConfig) => void | Promise<void>
Kind: 
async, 
parallel
Scope: Global
Called after the Vite config is resolved. Use this hook to read and store the final resolved config. It is also useful when the plugin needs to do something different based on the command being run.
Example:
const examplePlugin = () => {
  let config
  return {
    name: 'read-config',
    configResolved(resolvedConfig) {
      // store the resolved config
      config = resolvedConfig
    },
    // use stored config in other hooks
    transform(code, id) {
      if (config.command === 'serve') {
        // dev: plugin invoked by dev server
      } else {
        // build: plugin invoked by Rollup
      }
    },
  }
}
Note that the 
command value is 
serve in dev (in the cli 
vite, 
vite dev, and 
vite serve are aliases).
configureServer
Type: 
(server: ViteDevServer) => (() => void) | void | Promise<(() => void) | void>
Kind: 
async, 
sequential
See also: ViteDevServer
Scope: Global
Hook for configuring the dev server. The most common use case is adding custom middlewares to the internal connect app:
const myPlugin = () => ({
  name: 'configure-server',
  configureServer(server) {
    server.middlewares.use((req, res, next) => {
      // custom handle request...
    })
  },
})
Injecting Post Middleware
The 
configureServer hook is called before internal middlewares are installed, so the custom middlewares will run before internal middlewares by default. If you want to inject a middleware after internal middlewares, you can return a function from 
configureServer, which will be called after internal middlewares are installed:
const myPlugin = () => ({
  name: 'configure-server',
  configureServer(server) {
    // return a post hook that is called after internal middlewares are
    // installed
    return () => {
      server.middlewares.use((req, res, next) => {
        // custom handle request...
      })
    }
  },
})
Storing Server Access
In some cases, other plugin hooks may need access to the dev server instance (e.g. accessing the WebSocket server, the file system watcher, or the module graph). This hook can also be used to store the server instance for access in other hooks:
const myPlugin = () => {
  let server
  return {
    name: 'configure-server',
    configureServer(_server) {
      server = _server
    },
    transform(code, id) {
      if (server) {
        // use server...
      }
    },
  }
}
Note 
configureServer is not called when running the production build so your other hooks need to guard against its absence.
configurePreviewServer
Type: 
(server: PreviewServer) => (() => void) | void | Promise<(() => void) | void>
Kind: 
async, 
sequential
See also: PreviewServer
Scope: Global
Same as 
configureServer but for the preview server. Similarly to 
configureServer, the 
configurePreviewServer hook is called before other middlewares are installed. If you want to inject a middleware after other middlewares, you can return a function from 
configurePreviewServer, which will be called after internal middlewares are installed:
const myPlugin = () => ({
  name: 'configure-preview-server',
  configurePreviewServer(server) {
    // return a post hook that is called after other middlewares are
    // installed
    return () => {
      server.middlewares.use((req, res, next) => {
        // custom handle request...
      })
    }
  },
})
closeServer
Type: 
(context: { reason: 'restart' | 'close' }) => void | Promise<void>
Kind: 
async, 
parallel
Scope: Global
Called when the dev server is restarted or closed, after the server has been torn down. Typically used to dispose resources created in 
configureServer.
The 
context.reason distinguishes the two cases:
'restart': the server is restarting (e.g. a config file change or a call to 
server.restart()).
'close': the server is shutting down (e.g. the 
q shortcut, or a call to 
server.close()).
const myPlugin = () => {
  let resource
  return {
    name: 'close-server',
    configureServer(server) {
      resource = createResource()
    },
    async closeServer({ reason }) {
      if (reason === 'close') {
        await resource.dispose()
      }
    },
  }
}
closePreviewServer
Type: 
() => void | Promise<void>
Kind: 
async, 
parallel
Scope: Global
Same as 
closeServer but for the preview server. The preview server never restarts, so there is no 
reason.
const myPlugin = () => {
  let resource
  return {
    name: 'close-preview-server',
    configurePreviewServer(server) {
      resource = createResource()
    },
    async closePreviewServer() {
      await resource.dispose()
    },
  }
}
transformIndexHtml
Type: 
IndexHtmlTransformHook | { order?: 'pre' | 'post', handler: IndexHtmlTransformHook }
Kind: 
async, 
sequential
Scope: Per-environment
Dedicated hook for transforming HTML entry point files such as 
index.html. The hook receives the current HTML string and a transform context. The context exposes the 
ViteDevServer instance during dev, and exposes the Rollup output bundle during build.
The hook can be async and can return one of the following:
Transformed HTML string
An array of tag descriptor objects (
{ tag, attrs, children }) to inject to the existing HTML. Each tag can also specify where it should be injected to (default is prepending to 
<head>)
An object containing both as 
{ html, tags }
By default 
order is 
undefined, with this hook applied after the HTML has been transformed. In order to inject a script that should go through the Vite plugins pipeline, 
order: 'pre' will apply the hook before processing the HTML. 
order: 'post' applies the hook after all hooks with 
order undefined are applied.
Basic Example:
const htmlPlugin = () => {
  return {
    name: 'html-transform',
    transformIndexHtml(html) {
      return html.replace(
        /<title>(.*?)<\/title>/,
        `<title>Title replaced!</title>`,
      )
    },
  }
}
Full Hook Signature:
type IndexHtmlTransformHook = (
  html: string,
  ctx: {
    path: string
    filename: string
    server?: ViteDevServer
    bundle?: import('rolldown').OutputBundle
    chunk?: import('rolldown').OutputChunk
    originalUrl?: string
  },
) =>
  | IndexHtmlTransformResult
  | void
  | Promise<IndexHtmlTransformResult | void>
type IndexHtmlTransformResult =
  | string
  | HtmlTagDescriptor[]
  | {
      html: string
      tags: HtmlTagDescriptor[]
    }
interface HtmlTagDescriptor {
  tag: string
  /**
   * attribute values will be escaped automatically if needed
   */
  attrs?: Record<string, string | boolean>
  children?: string | HtmlTagDescriptor[]
  /**
   * default: 'head-prepend'
   */
  injectTo?: 'head' | 'body' | 'head-prepend' | 'body-prepend'
}
::: warning Note
This hook won't be called if you are using a framework that has custom handling of entry files (for example SvelteKit).
:::
handleHotUpdate
Type: 
(ctx: HmrContext) => Array<ModuleNode> | void | Promise<Array<ModuleNode> | void>
Kind: 
async, 
sequential
See also: HMR API
Scope: Per-environment
Perform custom HMR update handling. The hook receives a context object with the following signature:
interface HmrContext {
  file: string
  timestamp: number
  modules: Array<ModuleNode>
  read: () => string | Promise<string>
  server: ViteDevServer
}
modules is an array of modules that are affected by the changed file. It's an array because a single file may map to multiple served modules (e.g. Vue SFCs).
read is an async read function that returns the content of the file. This is provided because on some systems, the file change callback may fire too fast before the editor finishes updating the file and direct 
fs.readFile will return empty content. The read function passed in normalizes this behavior.
The hook can choose to:
Filter and narrow down the affected module list so that the HMR is more accurate.
Return an empty array and perform a full reload:
handleHotUpdate({ server, modules, timestamp }) {
  // Invalidate modules manually
  const invalidatedModules = new Set()
  for (const mod of modules) {
    server.moduleGraph.invalidateModule(
      mod,
      invalidatedModules,
      timestamp,
      true
    )
  }
  server.ws.send({ type: 'full-reload' })
  return []
}
Return an empty array and perform complete custom HMR handling by sending custom events to the client:
handleHotUpdate({ server }) {
  server.ws.send({
    type: 'custom',
    event: 'special-update',
    data: {}
  })
  return []
}
Client code should register corresponding handler using the HMR API (this could be injected by the same plugin's 
transform hook):
if (import.meta.hot) {
  import.meta.hot.on('special-update', (data) => {
    // perform custom update
  })
}
Plugin Context Meta
For plugin hooks that have access to the plugin context, Vite exposes additional properties on 
this.meta:
this.meta.viteVersion: The current Vite version string (e.g. 
"8.0.0").
::: tip Detecting Rolldown powered Vite
this.meta.rolldownVersion is only available for Rolldown powered Vite (i.e. Vite 8+). You can use it to detect whether the current Vite instance is powered by Rolldown:
function versionCheckPlugin(): Plugin {
  return {
    name: 'version-check',
    buildStart() {
      if (this.meta.rolldownVersion) {
        // only do something if running on a Rolldown powered Vite
      } else {
        // do something else if running on a Rollup powered Vite
      }
    },
  }
}
:::
Output Bundle Metadata
During build, Vite augments Rolldown's build output objects with a Vite-specific 
viteMetadata field.
This is available through:
RenderedChunk (for example in 
renderChunk and 
augmentChunkHash)
OutputChunk and 
OutputAsset (for example in 
generateBundle and 
writeBundle)
viteMetadata provides:
viteMetadata.importedCss: Set<string>
viteMetadata.importedAssets: Set<string>
This is useful when writing plugins that need to inspect emitted CSS and static assets without relying on 
build.manifest.
Example:
function outputMetadataPlugin(): Plugin {
  return {
    name: 'output-metadata-plugin',
    enforce: 'post',
    generateBundle(_, bundle) {
      for (const output of Object.values(bundle)) {
        const css = output.viteMetadata?.importedCss
        const assets = output.viteMetadata?.importedAssets
        if (!css?.size && !assets?.size) continue
        console.log(output.fileName, {
          css: css ? [...css] : [],
          assets: assets ? [...assets] : [],
        })
      }
    },
  }
}
Referencing Emitted Assets
To emit an asset from a plugin, call 
this.emitFile({ type: 'asset', ... }). It returns a 
referenceId that you can use to generate the asset's URL, since its final file name isn't known until the bundle is generated.
In JavaScript
Use 
import.meta.ROLLDOWN_FILE_URL_<referenceId>:
const referenceId = this.emitFile({
  type: 'asset',
  name: 'icon.png',
  source: fileContent,
})
// it's a JavaScript expression, so append any query or hash with string concatenation
return `export default import.meta.ROLLDOWN_FILE_URL_${referenceId} + '#frag'`
In CSS or HTML
import.meta.ROLLDOWN_FILE_URL_<referenceId> only works in JavaScript expression position. In CSS or HTML, use the 
__VITE_ASSET__<referenceId>__ token instead, appending any query or hash right after it:
background: url(__VITE_ASSET__<referenceId>__#frag);
Plugin Ordering
A Vite plugin can additionally specify an 
enforce property (similar to webpack loaders) to adjust its application order. The value of 
enforce can be either 
"pre" or 
"post". The resolved plugins will be in the following order:
Alias
User plugins with 
enforce: 'pre'
Vite core plugins
User plugins without enforce value
Vite build plugins
User plugins with 
enforce: 'post'
Vite post build plugins (minify, manifest, reporting)
Note that this is separate from hooks ordering, those are still separately subject to their 
order attribute as usual for Rolldown hooks.
Conditional Application
By default plugins are invoked for both serve and build. In cases where a plugin needs to be conditionally applied only during serve or build, use the 
apply property to only invoke them during 
'build' or 
'serve':
function myPlugin() {
  return {
    name: 'build-only',
    apply: 'build', // or 'serve'
  }
}
A function can also be used for more precise control:
apply(config, { command }) {
  // apply only on build but not for SSR
  return command === 'build' && !config.build.ssr
}
Rolldown Plugin Compatibility
A fair number of Rolldown / Rollup plugins will work directly as a Vite plugin (e.g. 
@rollup/plugin-alias or 
@rollup/plugin-json), but not all of them, since some plugin hooks do not make sense in an unbundled dev server context.
In general, as long as a Rolldown / Rollup plugin fits the following criteria then it should just work as a Vite plugin:
It doesn't use the 
moduleParsed hook.
It doesn't rely on the Rolldown specific options like 
transform.inject
It doesn't have strong coupling between bundle-phase hooks and output-phase hooks.
If a Rolldown / Rollup plugin only makes sense for the build phase, then it can be specified under 
build.rolldownOptions.plugins instead. It will work the same as a Vite plugin with 
enforce: 'post' and 
apply: 'build'.
You can also augment an existing Rolldown / Rollup plugin with Vite-only properties:
import example from 'rolldown-plugin-example'
import { defineConfig } from 'vite'
export default defineConfig({
  plugins: [
    {
      ...example(),
      enforce: 'post',
      apply: 'build',
    },
  ],
})
Path Normalization
Vite normalizes paths while resolving ids to use POSIX separators ( / ) while preserving the volume in Windows. On the other hand, Rollup keeps resolved paths untouched by default, so resolved ids have win32 separators ( \ ) in Windows. However, Rollup plugins use a 
normalizePath utility function from 
@rollup/pluginutils internally, which converts separators to POSIX before performing comparisons. This means that when these plugins are used in Vite, the 
include and 
exclude config pattern and other similar paths against resolved ids comparisons work correctly.
So, for Vite plugins, when comparing paths against resolved ids it is important to first normalize the paths to use POSIX separators. An equivalent 
normalizePath utility function is exported from the 
vite module.
import { normalizePath } from 'vite'
normalizePath('foo\\bar') // 'foo/bar'
normalizePath('foo/bar') // 'foo/bar'
Filtering, include/exclude pattern
Vite exposes 
@rollup/pluginutils's 
createFilter function to encourage Vite specific plugins and integrations to use the standard include/exclude filtering pattern, which is also used in Vite core itself.
Hook Filters
Rolldown introduced a hook filter feature to reduce the communication overhead between the Rust and JavaScript runtimes. This feature allows plugins to specify patterns that determine when hooks should be called, improving performance by avoiding unnecessary hook invocations.
This is also supported by Rollup 4.38.0+ and Vite 6.3.0+. To make your plugin backward compatible with older versions, make sure to also run the filter inside the hook handlers.
export default function myPlugin() {
  const jsFileRegex = /\.js$/
  return {
    name: 'my-plugin',
    // Example: only call transform for .js files
    transform: {
      filter: {
        id: jsFileRegex,
      },
      handler(code, id) {
        // Additional check for backward compatibility
        if (!jsFileRegex.test(id)) return null
        return {
          code: transformCode(code),
          map: null,
        }
      },
    },
  }
}
::: tip
@rolldown/pluginutils exports some utilities for hook filters like 
exactRegex and 
prefixRegex. These are also re-exported from 
rolldown/filter for convenience.
:::
Chunk Import Map Information
:::info Experimental
This feature is experimental and may change in the future.
:::
When 
build.chunkImportMap option is enabled, the import statements in the generated chunks will use a unique ID for each chunk instead of the file path.
To get the mapping from the chunk ID to the file path, you can access the import map emitted to the bundle in the 
generateBundle hook or the 
writeBundle hook. The import map has the name specified by 
build.rolldownOptions.experimental.chunkImportMap.fileName (defaults to 
importmap.json).
function accessImportMap() {
  let config: ResolvedConfig
  return {
    name: 'access-import-map',
    configResolved(resolvedConfig) {
      config = resolvedConfig
    },
    generateBundle(options, bundle) {
      const chunkImportMap =
        config.build.rolldownOptions.experimental?.chunkImportMap
      if (chunkImportMap) {
        const importMapFilename =
          typeof chunkImportMap === 'object' && chunkImportMap.fileName
            ? chunkImportMap.fileName
            : 'importmap.json'
        const importMap = bundle[importMapFilename]! as OutputAsset
        const mapping = JSON.parse(importMap.source).imports
        console.log(mapping)
        // { "./entry.hash1.js": "./entry.hash2.js" }
      }
    },
  }
}
Client-server Communication
Since Vite 2.9, we provide some utilities for plugins to help handle the communication with clients.
Server to Client
On the plugin side, we could use 
server.ws.send to broadcast events to the client:
export default defineConfig({
  plugins: [
    {
      // ...
      configureServer(server) {
        server.ws.on('connection', () => {
          server.ws.send('my:greetings', { msg: 'hello' })
        })
      },
    },
  ],
})
::: tip NOTE
We recommend always prefixing your event names to avoid collisions with other plugins.
:::
On the client side, use 
hot.on to listen to the events:
import 'vite/client'
// ---cut---
// client side
if (import.meta.hot) {
  import.meta.hot.on('my:greetings', (data) => {
    console.log(data.msg) // hello
  })
}
Client to Server
To send events from the client to the server, we can use 
hot.send:
// client side
if (import.meta.hot) {
  import.meta.hot.send('my:from-client', { msg: 'Hey!' })
}
Then use 
server.ws.on and listen to the events on the server side:
export default defineConfig({
  plugins: [
    {
      // ...
      configureServer(server) {
        server.ws.on('my:from-client', (data, client) => {
          console.log('Message from client:', data.msg) // Hey!
          // reply only to the client (if needed)
          client.send('my:ack', { msg: 'Hi! I got your message!' })
        })
      },
    },
  ],
})
TypeScript for Custom Events
Internally, vite infers the type of a payload from the 
CustomEventMap interface, it is possible to type custom events by extending the interface:
:::tip Note
Make sure to include the 
.d.ts extension when specifying TypeScript declaration files. Otherwise, TypeScript may not know which file the module is trying to extend.
:::
import 'vite/types/customEvent.d.ts'
declare module 'vite/types/customEvent.d.ts' {
  interface CustomEventMap {
    'custom:foo': { msg: string }
    // 'event-key': payload
  }
}
This interface extension is utilized by 
InferCustomEventPayload<T> to infer the payload type for event 
T. For more information on how this interface is utilized, refer to the HMR API Documentation.
import 'vite/client'
import type { InferCustomEventPayload } from 'vite/types/customEvent.d.ts'
declare module 'vite/types/customEvent.d.ts' {
  interface CustomEventMap {
    'custom:foo': { msg: string }
  }
}
// ---cut---
type CustomFooPayload = InferCustomEventPayload<'custom:foo'>
import.meta.hot?.on('custom:foo', (payload) => {
  // The type of payload will be { msg: string }
})
import.meta.hot?.on('unknown:event', (payload) => {
  // The type of payload will be any
})

Static Asset Handling
Related: Public Base Path
Related: 
assetsInclude config option
Importing Asset as URL
Importing a static asset will return the resolved public URL when it is served:
import 'vite/client'
// ---cut---
import imgUrl from './img.png'
document.getElementById('hero-img').src = imgUrl
For example, 
imgUrl will be 
/src/img.png during development, and become 
/assets/img.2d8efhg.png in the production build.
The behavior is similar to webpack's 
file-loader. The difference is that the import can be either using absolute public paths (based on project root during dev) or relative paths.
url() references in CSS are handled the same way.
If using the Vue plugin, asset references in Vue SFC templates are automatically converted into imports.
Common image, media, and font filetypes are detected as assets automatically. You can extend the internal list using the 
assetsInclude option.
Referenced assets are included as part of the build assets graph, will get hashed file names, and can be processed by plugins for optimization.
Assets smaller in bytes than the 
assetsInlineLimit option will be inlined as base64 data URLs.
Git LFS placeholders are automatically excluded from inlining because they do not contain the content of the file they represent. To get inlining, make sure to download the file contents via Git LFS before building.
TypeScript, by default, does not recognize static asset imports as valid modules. To fix this, include 
vite/client.
::: tip Inlining SVGs through 
url()
When passing a URL of SVG to a manually constructed 
url() by JS, the variable should be wrapped within double quotes.
import 'vite/client'
// ---cut---
import imgUrl from './img.svg'
document.getElementById('hero-img').style.background = `url("${imgUrl}")`
:::
Explicit URL Imports
Assets that are not included in the internal list or in 
assetsInclude can be explicitly imported as a URL using the 
?url suffix. This is useful, for example, to import Houdini Paint Worklets.
import 'vite/client'
// ---cut---
import workletURL from 'extra-scalloped-border/worklet.js?url'
CSS.paintWorklet.addModule(workletURL)
Explicit Inline Handling
Assets can be explicitly imported with inlining or no inlining using the 
?inline or 
?no-inline suffix respectively.
import 'vite/client'
// ---cut---
// prettier-ignore
import imgUrl1 from './img.svg?no-inline'
import imgUrl2 from './img.png?inline'
Importing Asset as String
Assets can be imported as strings using the 
?raw suffix.
import 'vite/client'
// ---cut---
import shaderString from './shader.glsl?raw'
Importing Script as a Worker
Scripts can be imported as web workers with the 
?worker or 
?sharedworker suffix.
import 'vite/client'
// ---cut---
// Separate chunk in the production build
import Worker from './shader.js?worker'
const worker = new Worker()
import 'vite/client'
// ---cut---
// sharedworker
import SharedWorker from './shader.js?sharedworker'
const sharedWorker = new SharedWorker()
import 'vite/client'
// ---cut---
// Inlined as base64 strings
import InlineWorker from './shader.js?worker&inline'
Check out the Web Worker section for more details.
The 
public Directory
If you have assets that are:
Never referenced in source code (e.g. 
robots.txt)
Must retain the exact same file name (without hashing)
...or you simply don't want to have to import an asset first just to get its URL
Then you can place the asset in a special 
public directory under your project root. Assets in this directory will be served at root path 
/ during dev, and copied to the root of the dist directory as-is.
The directory defaults to 
<root>/public, but can be configured via the 
publicDir option.
Note that you should always reference 
public assets using root absolute path - for example, 
public/icon.png should be referenced in source code as 
/icon.png.
::: tip Choosing between imports and the 
public directory
In general, prefer importing assets unless you specifically need the guarantees provided by the 
public directory.
:::
new URL(url, import.meta.url)
import.meta.url is a native ESM feature that exposes the current module's URL. Combining it with the native URL constructor, we can obtain the full, resolved URL of a static asset using relative path from a JavaScript module:
const imgUrl = new URL('./img.png', import.meta.url).href
document.getElementById('hero-img').src = imgUrl
This works natively in modern browsers - in fact, Vite doesn't need to process this code at all during development!
This pattern also supports dynamic URLs via template literals:
function getImageUrl(name) {
  // note that this does not include files in subdirectories
  return new URL(`./dir/${name}.png`, import.meta.url).href
}
During the production build, Vite will perform necessary transforms so that the URLs still point to the correct location even after bundling and asset hashing. However, the URL string must be static so it can be analyzed, otherwise the code will be left as is, which can cause runtime errors if 
build.target does not support 
import.meta.url.
// Vite will not transform this
const imgUrl = new URL(imagePath, import.meta.url).href
::: details How it works
Vite will transform the 
getImageUrl function to:
import __img0png from './dir/img0.png'
import __img1png from './dir/img1.png'
function getImageUrl(name) {
  const modules = {
    './dir/img0.png': __img0png,
    './dir/img1.png': __img1png,
  }
  return new URL(modules[`./dir/${name}.png`], import.meta.url).href
}
:::
::: warning Does not work with SSR
This pattern does not work if you are using Vite for Server-Side Rendering, because 
import.meta.url has different semantics in browsers vs. Node.js. The server bundle also cannot determine the client host URL ahead of time.
:::

Backend Integration
:::tip Note
If you want to serve the HTML using a traditional backend (e.g. Rails, Laravel) but use Vite for serving assets, check for existing integrations listed in Awesome Vite.
If you need a custom integration, you can follow the steps in this guide to configure it manually.
:::
In your Vite config, configure the entry and enable build manifest:
import { defineConfig } from 'vite'
// ---cut---
export default defineConfig({
  // overwrite default .html entry
  input: '/path/to/main.js',
  server: {
    cors: {
      // the origin you will be accessing via browser
      origin: 'http://my-backend.example.com',
    },
  },
  build: {
    // generate .vite/manifest.json in outDir
    manifest: true,
  },
})
If you haven't disabled the module preload polyfill, you also need to import the polyfill in your entry
// add the beginning of your app entry
import 'vite/modulepreload-polyfill'
For development, inject the following in your server's HTML template (substitute 
http://localhost:5173 with the local URL Vite is running at):
<!-- if development -->
<script type="module" src="http://localhost:5173/@vite/client"></script>
<script type="module" src="http://localhost:5173/main.js"></script>
In order to properly serve assets, you have two options:
Make sure the server is configured to proxy static assets requests to the Vite server
Set 
server.origin so that generated asset URLs will be resolved using the back-end server URL instead of a relative path
This is needed for assets such as images to load properly.
Note if you are using React with 
@vitejs/plugin-react, you'll also need to add this before the above scripts, since the plugin is not able to modify the HTML you are serving (substitute 
http://localhost:5173 with the local URL Vite is running at):
<script type="module">
  import RefreshRuntime from 'http://localhost:5173/@react-refresh'
  RefreshRuntime.injectIntoGlobalHook(window)
  window.$RefreshReg$ = () => {}
  window.$RefreshSig$ = () => (type) => type
  window.__vite_plugin_react_preamble_installed__ = true
</script>
For production, after running 
vite build, a 
.vite/manifest.json file will be generated alongside other asset files. An example manifest file looks like this:
{
  "_shared-B7PI925R.js": {
    "file": "assets/shared-B7PI925R.js",
    "name": "shared",
    "css": ["assets/shared-ChJ_j-JJ.css"]
  },
  "_shared-ChJ_j-JJ.css": {
    "file": "assets/shared-ChJ_j-JJ.css",
    "src": "_shared-ChJ_j-JJ.css"
  },
  "logo.svg": {
    "file": "assets/logo-BuPIv-2h.svg",
    "src": "logo.svg"
  },
  "baz.js": {
    "file": "assets/baz-B2H3sXNv.js",
    "name": "baz",
    "src": "baz.js",
    "isDynamicEntry": true
  },
  "views/bar.js": {
    "file": "assets/bar-gkvgaI9m.js",
    "name": "bar",
    "src": "views/bar.js",
    "isEntry": true,
    "imports": ["_shared-B7PI925R.js"],
    "dynamicImports": ["baz.js"]
  },
  "views/foo.js": {
    "file": "assets/foo-BRBmoGS9.js",
    "name": "foo",
    "src": "views/foo.js",
    "isEntry": true,
    "imports": ["_shared-B7PI925R.js"],
    "css": ["assets/foo-5UjPuW-k.css"]
  }
}
The manifest maps source files to their build outputs and dependencies:
digraph manifest {
  rankdir=TB
  node [shape=box style="rounded,filled" fontname="Arial" fontsize=10 margin="0.2,0.1" fontcolor="${#3c3c43|#ffffff}" color="${#c2c2c4|#3c3f44}"]
  edge [color="${#67676c|#98989f}" fontname="Arial" fontsize=9 fontcolor="${#67676c|#98989f}"]
  bgcolor="transparent"
  foo [label="views/foo.js\n(entry)" fillcolor="${#e9eaff|#222541}"]
  bar [label="views/bar.js\n(entry)" fillcolor="${#e9eaff|#222541}"]
  shared [label="_shared-B7PI925R.js\n(common chunk)" fillcolor="${#f2ecfc|#2c273e}"]
  baz [label="baz.js\n(dynamic import)" fillcolor="${#fcf4dc|#38301a}"]
  foocss [label="foo.css" shape=ellipse fillcolor="${#fde4e8|#3a1d27}"]
  sharedcss [label="shared.css" shape=ellipse fillcolor="${#fde4e8|#3a1d27}"]
  logo [label="logo.svg\n(asset)" shape=ellipse fillcolor="${#def5ed|#15312d}"]
  foo -> shared [label="imports"]
  bar -> shared [label="imports"]
  bar -> baz [label="dynamicImports" style=dashed]
  foo -> foocss [label="css"]
  shared -> sharedcss [label="css"]
}
The manifest has a 
Record<name, chunk> structure where each chunk follows the 
ManifestChunk interface:
interface ManifestChunk {
  /**
   * The input file name of this chunk / asset if known
   */
  src?: string
  /**
   * The output file name of this chunk / asset
   */
  file: string
  /**
   * The list of CSS files imported by this chunk
   */
  css?: string[]
  /**
   * The list of asset files imported by this chunk, excluding CSS files
   */
  assets?: string[]
  /**
   * Whether this chunk or asset is an entry point
   */
  isEntry?: boolean
  /**
   * The name of this chunk / asset if known
   */
  name?: string
  /**
   * Whether this chunk is a dynamic entry point
   *
   * This field is only present in JS chunks.
   */
  isDynamicEntry?: boolean
  /**
   * The list of statically imported chunks by this chunk
   *
   * The values are the keys of the manifest. This field is only present in JS chunks.
   */
  imports?: string[]
  /**
   * The list of dynamically imported chunks by this chunk
   *
   * The values are the keys of the manifest. This field is only present in JS chunks.
   */
  dynamicImports?: string[]
}
Each entry in the manifest represents one of the following:
Entry chunks: Generated from files specified in 
build.rolldownOptions.input. These chunks have 
isEntry: true and their key is the relative src path from project root.
Dynamic entry chunks: Generated from dynamic imports. These chunks have 
isDynamicEntry: true and their key is the relative src path from project root.
Non-entry chunks: Their key is the base name of the generated file prefixed with 
_.
Asset chunks: Generated from imported assets like images, fonts. Their key is the relative src path from project root.
CSS files: When 
build.cssCodeSplit is 
false, a single CSS file is generated with the key 
style.css. When 
build.cssCodeSplit is not 
false, the key is generated similar to JS chunks (i.e. entry chunks will not have 
_ prefix and non-entry chunks will have 
_ prefix).
JS chunks (chunks other than assets or CSS) will contain information on their static and dynamic imports (both are keys that map to the corresponding chunk in the manifest). Chunks also list their corresponding CSS and asset files if they have any.
You can use this file to render links or preload directives with hashed filenames.
Here is an example HTML template to render the proper links. The syntax here is for
explanation only, substitute with your server templating language. The 
importedChunks
function is for illustration and isn't provided by Vite.
<!-- if production -->
<!-- for cssFile of manifest[name].css -->
<link rel="stylesheet" href="/{{ cssFile }}" />
<!-- for chunk of importedChunks(manifest, name) -->
<!-- for cssFile of chunk.css -->
<link rel="stylesheet" href="/{{ cssFile }}" />
<script type="module" src="/{{ manifest[name].file }}"></script>
<!-- for chunk of importedChunks(manifest, name) -->
<link rel="modulepreload" href="/{{ chunk.file }}" />
Specifically, a backend generating HTML should include the following tags given a manifest
file and an entry point. Note that following this order is recommended for optimal performance:
A 
<link rel="stylesheet"> tag for each file in the entry point chunk's 
css list (if it exists)
Recursively follow all chunks in the entry point's 
imports list and include a
<link rel="stylesheet"> tag for each CSS file of each imported chunk's 
css list (if it exists).
A tag for the 
file key of the entry point chunk. This can be 
<script type="module"> for JavaScript, 
<link rel="stylesheet"> for CSS.
Optionally, 
<link rel="modulepreload"> tag for the 
file of each imported JavaScript
chunk, again recursively following the imports starting from the entry point chunk.
Following the above example manifest, for the entry point 
views/foo.js the following tags should be included in production:
<link rel="stylesheet" href="assets/foo-5UjPuW-k.css" />
<link rel="stylesheet" href="assets/shared-ChJ_j-JJ.css" />
<script type="module" src="assets/foo-BRBmoGS9.js"></script>
<!-- optional -->
<link rel="modulepreload" href="assets/shared-B7PI925R.js" />
While the following should be included for the entry point 
views/bar.js:
<link rel="stylesheet" href="assets/shared-ChJ_j-JJ.css" />
<script type="module" src="assets/bar-gkvgaI9m.js"></script>
<!-- optional -->
<link rel="modulepreload" href="assets/shared-B7PI925R.js" />
::: details Pseudo implementation of 
importedChunks
An example pseudo implementation of 
importedChunks in TypeScript (This will
need to be adapted for your programming language and templating language):
import type { Manifest, ManifestChunk } from 'vite'
export default function importedChunks(
  manifest: Manifest,
  name: string,
): ManifestChunk[] {
  const seen = new Set<string>()
  function getImportedChunks(chunk: ManifestChunk): ManifestChunk[] {
    const chunks: ManifestChunk[] = []
    for (const file of chunk.imports ?? []) {
      const importee = manifest[file]
      if (seen.has(file)) {
        continue
      }
      seen.add(file)
      chunks.push(...getImportedChunks(importee))
      chunks.push(importee)
    }
    return chunks
  }
  return getImportedChunks(manifest[name])
}
:::
:::info Chunk Import Maps Support (Experimental)
If you are using the experimental 
build.chunkImportMap option, you also need to inject the import map into the HTML.
The import map is output to 
importmap.json in the output directory. Make sure to inject the 
<script type="importmap"> tag before any 
<script type="module"> tags or 
<link rel="modulepreload"> tags.
:::

Building for Production
When it is time to deploy your app for production, simply run the 
vite build command. By default, it uses 
<root>/index.html as the build entry point, and produces an application bundle that is suitable to be served over a static hosting service. Check out the Deploying a Static Site for guides about popular services.
Watch an interactive lesson on Scrimba
Browser Compatibility
By default, the production bundle targets the minimum browser versions compatible with Baseline Widely Available as of a date fixed for each major release. The default browser support range for this major is:
Chrome >=111
Edge >=111
Firefox >=114
Safari >=16.4
You can specify custom targets via the 
build.target config option, where the lowest target is 
es2015. If a lower target is set, Vite will still require these minimum browser support ranges as it relies on native ESM dynamic import, and 
import.meta:
Chrome >=64
Firefox >=67
Safari >=11.1
Edge >=79
Note that by default, Vite only handles syntax transforms and does not cover polyfills. You can check out https://cdnjs.cloudflare.com/polyfill/ which automatically generates polyfill bundles based on the user's browser UserAgent string.
Legacy browsers can be supported via @vitejs/plugin-legacy, which will automatically generate legacy chunks and corresponding ES language feature polyfills. The legacy chunks are conditionally loaded only in browsers that do not have native ESM support.
Public Base Path
Related: Asset Handling
If you are deploying your project under a nested public path, simply specify the 
base config option and all asset paths will be rewritten accordingly. This option can also be specified as a command line flag, e.g. 
vite build --base=/my/public/path/.
JS-imported asset URLs, CSS 
url() references, and asset references in your 
.html files are all automatically adjusted to respect this option during build.
The exception is when you need to dynamically concatenate URLs on the fly. In this case, you can use the globally injected 
import.meta.env.BASE_URL variable which will be the public base path. Note this variable is statically replaced during build so it must appear exactly as-is (i.e. 
import.meta.env['BASE_URL'] won't work).
For advanced base path control, check out Advanced Base Options.
Relative base
If you don't know the base path in advance, you may set a relative base path with 
"base": "./" or 
"base": "". This will make all generated URLs to be relative to each file.
:::warning Support for older browsers when using relative bases
import.meta support is required for relative bases. If you need to support browsers that do not support 
import.meta, you can use the 
legacy plugin.
:::
Customizing the Build
The build can be customized via various build config options. Specifically, you can directly adjust the underlying Rolldown options via 
build.rolldownOptions:
export default defineConfig({
  build: {
    rolldownOptions: {
      // https://rolldown.rs/reference/
    },
  },
})
For example, you can specify multiple Rolldown outputs with plugins that are only applied during build.
Chunking Strategy
You can configure how chunks are split using 
build.rolldownOptions.output.codeSplitting (see Rolldown docs). If you use a framework, refer to their documentation for configuring how chunks are split.
Load Error Handling
Vite emits 
vite:preloadError event when it fails to load dynamic imports. 
event.payload contains the original import error. If you call 
event.preventDefault(), the error will not be thrown.
window.addEventListener('vite:preloadError', (event) => {
  window.location.reload() // for example, refresh the page
})
Browsers that support retriable module loading allow an application or framework to retry the original dynamic import after a transient network or HTTP error. Older browsers require a page reload because they cache the failure in the module map.
When a new deployment occurs, the hosting service may delete the assets from previous deployments. As a result, a user who visited your site before the new deployment might encounter an import error. This error happens because the assets running on that user's device are outdated and the code tries to import the corresponding old chunk, which is deleted. This event is useful for addressing this situation. In this case, make sure to set 
Cache-Control: no-cache on the HTML file, otherwise the old assets will be still referenced.
Rebuild on Files Changes
You can enable Rolldown watcher with 
vite build --watch. Or, you can directly adjust the underlying 
WatcherOptions via 
build.watch:
export default defineConfig({
  build: {
    watch: {
      // https://rolldown.rs/reference/InputOptions.watch
    },
  },
})
With the 
--watch flag enabled, changes to files to be bundled will trigger a rebuild. Note that changes to the config and its dependencies require restarting the build command.
Multi-Page App
Suppose you have the following source code structure:
├── package.json
├── vite.config.js
├── index.html
├── main.js
└── nested
    ├── index.html
    └── nested.js
During dev, simply navigate or link to 
/nested/ - it works as expected, just like for a normal static file server.
During build, all you need to do is to specify multiple 
.html files as entry points:
import { resolve } from 'node:path'
import { defineConfig } from 'vite'
export default defineConfig({
  input: {
    main: resolve(import.meta.dirname, 'index.html'),
    nested: resolve(import.meta.dirname, 'nested/index.html'),
  },
})
If you specify a different root, remember that 
import.meta.dirname will still be the folder of your 
vite.config.js file when resolving the input paths. Therefore, you will need to add your 
root entry to the arguments for 
resolve.
Note that for HTML files, Vite ignores the name given to the entry in the 
rolldownOptions.input object and instead respects the resolved id of the file when generating the HTML asset in the dist folder. This ensures a consistent structure with the way the dev server works.
Library Mode
When you are developing a browser-oriented library, you are likely spending most of the time on a test/demo page that imports your actual library. With Vite, you can use your 
index.html for that purpose to get the smooth development experience.
When it is time to bundle your library for distribution, use the 
build.lib config option. Make sure to also externalize any dependencies that you do not want to bundle into your library, e.g. 
vue or 
react:
::: code-group
import { resolve } from 'node:path'
import { defineConfig } from 'vite'
export default defineConfig({
  build: {
    lib: {
      entry: resolve(import.meta.dirname, 'lib/main.js'),
      name: 'MyLib',
      // the proper extensions will be added
      fileName: 'my-lib',
    },
    rolldownOptions: {
      // make sure to externalize deps that shouldn't be bundled
      // into your library
      external: ['vue'],
      output: {
        // Provide global variables to use in the UMD build
        // for externalized deps
        globals: {
          vue: 'Vue',
        },
      },
    },
  },
})
import { resolve } from 'node:path'
import { defineConfig } from 'vite'
export default defineConfig({
  build: {
    lib: {
      entry: {
        'my-lib': resolve(import.meta.dirname, 'lib/main.js'),
        secondary: resolve(import.meta.dirname, 'lib/secondary.js'),
      },
      name: 'MyLib',
    },
    rolldownOptions: {
      // make sure to externalize deps that shouldn't be bundled
      // into your library
      external: ['vue'],
      output: {
        // Provide global variables to use in the UMD build
        // for externalized deps
        globals: {
          vue: 'Vue',
        },
      },
    },
  },
})
:::
The entry file would contain exports that can be imported by users of your package:
import Bar from './Bar.vue'
import Foo from './Foo.vue'
export { Foo, Bar }
Running 
vite build with this config uses a Rollup preset that is oriented towards shipping libraries and produces two bundle formats:
es and 
umd (for single entry)
es and 
cjs (for multiple entries)
The formats can be configured with the 
build.lib.formats option.
$ vite build
building for production...
dist/my-lib.js      0.08 kB / gzip: 0.07 kB
dist/my-lib.umd.cjs 0.30 kB / gzip: 0.16 kB
Recommended 
package.json for your lib:
::: code-group
{
  "name": "my-lib",
  "type": "module",
  "files": ["dist"],
  "main": "./dist/my-lib.umd.cjs",
  "module": "./dist/my-lib.js",
  "exports": {
    ".": {
      "import": "./dist/my-lib.js",
      "require": "./dist/my-lib.umd.cjs"
    }
  }
}
{
  "name": "my-lib",
  "type": "module",
  "files": ["dist"],
  "main": "./dist/my-lib.cjs",
  "module": "./dist/my-lib.js",
  "exports": {
    ".": {
      "import": "./dist/my-lib.js",
      "require": "./dist/my-lib.cjs"
    },
    "./secondary": {
      "import": "./dist/secondary.js",
      "require": "./dist/secondary.cjs"
    }
  }
}
:::
CSS support
If your library imports any CSS, it will be bundled as a single CSS file besides the built JS files, e.g. 
dist/my-lib.css. The name defaults to 
build.lib.fileName, but can also be changed with 
build.lib.cssFileName.
You can export the CSS file in your 
package.json to be imported by users:
{
  "name": "my-lib",
  "type": "module",
  "files": ["dist"],
  "main": "./dist/my-lib.umd.cjs",
  "module": "./dist/my-lib.js",
  "exports": {
    ".": {
      "import": "./dist/my-lib.js",
      "require": "./dist/my-lib.umd.cjs"
    },
    "./style.css": "./dist/my-lib.css"
  }
}
::: tip File Extensions
If the 
package.json does not contain 
"type": "module", Vite will generate different file extensions for Node.js compatibility. 
.js will become 
.mjs and 
.cjs will become 
.js.
:::
::: tip Environment Variables
In library mode, all 
import.meta.env.* usage are statically replaced when building for production. However, 
process.env.* usage are not, so that consumers of your library can dynamically change it. If this is undesirable, you can use 
define: { 'process.env.NODE_ENV': '"production"' } for example to statically replace them, or use 
esm-env for better compatibility with bundlers and runtimes.
:::
::: warning Advanced Usage
Library mode includes a simple and opinionated configuration for browser-oriented and JS framework libraries. If you are building non-browser libraries, or require advanced build flows, you can use tsdown or Rolldown directly.
:::
Advanced Base Options
::: warning
This feature is experimental. Give Feedback.
:::
For advanced use cases, the deployed assets and public files may be in different paths, for example to use different cache strategies.
A user may choose to deploy in three different paths:
The generated entry HTML files (which may be processed during SSR)
The generated hashed assets (JS, CSS, and other file types like images)
The copied public files
A single static base isn't enough in these scenarios. Vite provides experimental support for advanced base options during build, using 
experimental.renderBuiltUrl.
import type { UserConfig } from 'vite'
// prettier-ignore
const config: UserConfig = {
// ---cut-before---
experimental: {
  renderBuiltUrl(filename, { hostType }) {
    if (hostType === 'js') {
      return { runtime: `window.__toCdnUrl(${JSON.stringify(filename)})` }
    } else {
      return { relative: true }
    }
  },
},
// ---cut-after---
}
If the hashed assets and public files aren't deployed together, options for each group can be defined independently using asset 
type included in the second 
context param given to the function.
import path from 'node:path'
import type { UserConfig } from 'vite'
// prettier-ignore
const config: UserConfig = {
// ---cut-before---
experimental: {
  renderBuiltUrl(filename, { hostId, hostType, type }) {
    if (type === 'public') {
      return 'https://www.domain.com/' + filename
    } else if (path.extname(hostId) === '.js') {
      return {
        runtime: `window.__assetsPath(${JSON.stringify(filename)})`
      }
    } else {
      return 'https://cdn.domain.com/assets/' + filename
    }
  },
},
// ---cut-after---
}
Note that the 
filename passed is a decoded URL, and if the function returns a URL string, it should also be decoded. Vite will handle the encoding automatically when rendering the URLs. If an object with 
runtime is returned, encoding should be handled yourself where needed as the runtime code will be rendered as is.

Command Line Interface
Dev server
vite
Start Vite dev server in the current directory. 
vite dev and 
vite serve are aliases for 
vite.
Usage
vite [root]
Options
Options
--host [host]
Specify hostname (
string)
--port <port>
Specify port (
number)
--open [path]
Open browser on startup (
boolean | string)
--cors
Enable CORS (
boolean)
--strictPort
Exit if specified port is already in use (
boolean)
--force
Force the optimizer to ignore the cache and re-bundle (
boolean)
--experimentalBundle
Use experimental full bundle mode (this is highly experimental) (
boolean)
-c, --config <file>
Use specified config file (
string)
--base <path>
Public base path (default: 
/) (
string)
-l, --logLevel <level>
info | warn | error | silent (
string)
--clearScreen
Allow/disable clear screen when logging (
boolean)
--configLoader <loader>
Use 
bundle to bundle the config with Rolldown, or 
runner (experimental) to process it on the fly, or 
native (experimental) to load using the native runtime (default: 
bundle)
--profile [name]
Start built-in Node.js inspector and write the profile to 
<name>.cpuprofile (check Performance bottlenecks) (
boolean | string)
-d, --debug [feat]
Show debug logs (
string | boolean)
-f, --filter <filter>
Filter debug logs (
string)
-m, --mode <mode>
Set env mode (
string)
-h, --help
Display available CLI options
-v, --version
Display version number
Build
vite build
Build for production.
Usage
vite build [root]
Options
Options
--target <target>
Transpile target (default: 
"baseline-widely-available") (
string)
--outDir <dir>
Output directory (default: 
dist) (
string)
--assetsDir <dir>
Directory under outDir to place assets in (default: 
"assets") (
string)
--assetsInlineLimit <number>
Static asset base64 inline threshold in bytes (default: 
4096) (
number)
--ssr [entry]
Build specified entry for server-side rendering (
string)
--sourcemap [output]
Output source maps for build (default: 
false) (
boolean | "inline" | "hidden")
--minify [minifier]
Enable/disable minification, or specify minifier to use (default: 
"oxc") (
boolean | "oxc" | "terser" | "esbuild")
--manifest [name]
Emit build manifest json (
boolean | string)
--ssrManifest [name]
Emit ssr manifest json (
boolean | string)
--emptyOutDir
Force empty outDir when it's outside of root (
boolean)
-w, --watch
Rebuilds when modules have changed on disk (
boolean)
-c, --config <file>
Use specified config file (
string)
--base <path>
Public base path (default: 
/) (
string)
-l, --logLevel <level>
info | warn | error | silent (
string)
--clearScreen
Allow/disable clear screen when logging (
boolean)
--configLoader <loader>
Use 
bundle to bundle the config with Rolldown, or 
runner (experimental) to process it on the fly, or 
native (experimental) to load using the native runtime (default: 
bundle)
--profile [name]
Start built-in Node.js inspector and write the profile to 
<name>.cpuprofile (check Performance bottlenecks) (
boolean | string)
-d, --debug [feat]
Show debug logs (
string | boolean)
-f, --filter <filter>
Filter debug logs (
string)
-m, --mode <mode>
Set env mode (
string)
-h, --help
Display available CLI options
--app
Build all environments, same as 
builder: {} (
boolean, experimental)
Others
vite optimize
Pre-bundle dependencies.
Deprecated: the pre-bundle process runs automatically and does not need to be called.
Usage
vite optimize [root]
Options
Options
--force
Force the optimizer to ignore the cache and re-bundle (
boolean)
-c, --config <file>
Use specified config file (
string)
--base <path>
Public base path (default: 
/) (
string)
-l, --logLevel <level>
info | warn | error | silent (
string)
--clearScreen
Allow/disable clear screen when logging (
boolean)
--configLoader <loader>
Use 
bundle to bundle the config with Rolldown, or 
runner (experimental) to process it on the fly, or 
native (experimental) to load using the native runtime (default: 
bundle)
-d, --debug [feat]
Show debug logs (
string | boolean)
-f, --filter <filter>
Filter debug logs (
string)
-m, --mode <mode>
Set env mode (
string)
-h, --help
Display available CLI options
vite preview
Locally preview the production build. Do not use this as a production server as it's not designed for it.
This command starts a server in the build directory (by default 
dist). Run 
vite build beforehand to ensure that the build directory is up-to-date. Depending on the project's configured 
appType, it makes use of certain middleware.
Usage
vite preview [root]
Options
Options
--host [host]
Specify hostname (
string)
--port <port>
Specify port (
number)
--strictPort
Exit if specified port is already in use (
boolean)
--open [path]
Open browser on startup (
boolean | string)
--outDir <dir>
Output directory (default: 
dist) (
string)
-c, --config <file>
Use specified config file (
string)
--base <path>
Public base path (default: 
/) (
string)
-l, --logLevel <level>
info | warn | error | silent (
string)
--clearScreen
Allow/disable clear screen when logging (
boolean)
--configLoader <loader>
Use 
bundle to bundle the config with Rolldown, or 
runner (experimental) to process it on the fly, or 
native (experimental) to load using the native runtime (default: 
bundle)
-d, --debug [feat]
Show debug logs (
string | boolean)
-f, --filter <filter>
Filter debug logs (
string)
-m, --mode <mode>
Set env mode (
string)
-h, --help
Display available CLI options

Dependency Pre-Bundling
When you run 
vite for the first time, Vite prebundles your project dependencies before loading your site locally. It is done automatically and transparently by default.
The Why
This is Vite performing what we call "dependency pre-bundling". This process serves two purposes:
CommonJS and UMD compatibility: During development, Vite serves all code as native ESM. Therefore, Vite must convert dependencies that are shipped as CommonJS or UMD into ESM first.
When converting CommonJS dependencies, Vite performs smart import analysis so that named imports to CommonJS modules will work as expected even if the exports are dynamically assigned (e.g. React):
// works as expected
import React, { useState } from 'react'
Performance: Vite converts ESM dependencies with many internal modules into a single module to improve subsequent page load performance.
Some packages ship their ES modules builds as many separate files importing one another. For example, 
lodash-es has over 600 internal modules! When we do 
import { debounce } from 'lodash-es', the browser fires off 600+ HTTP requests at the same time! Even though the server has no problem handling them, the large number of requests creates network congestion on the browser side, causing the page to load noticeably slower.
By pre-bundling 
lodash-es into a single module, we now only need one HTTP request instead!
::: tip NOTE
Dependency pre-bundling only applies in development mode.
:::
Automatic Dependency Discovery
If an existing cache is not found, Vite will crawl your source code and automatically discover dependency imports (i.e. "bare imports" that expect to be resolved from 
node_modules) and use these found imports as entry points for the pre-bundle. The pre-bundling is performed with Rolldown, so it's typically very fast.
After the server has already started, if a new dependency import is encountered that isn't already in the cache, Vite will re-run the dep bundling process and reload the page if needed.
Monorepos and Linked Dependencies
In a monorepo setup, a dependency may be a linked package from the same repo. Vite automatically detects dependencies that are not resolved from 
node_modules and treats the linked dep as source code. It will not attempt to bundle the linked dep, and will analyze the linked dep's dependency list instead.
However, this requires the linked dep to be exported as ESM. If not, you can add the dependency to 
optimizeDeps.include in your config.
import { defineConfig } from 'vite'
// ---cut---
export default defineConfig({
  optimizeDeps: {
    include: ['linked-dep'],
  },
})
When making changes to the linked dep, restart the dev server with the 
--force command line option for the changes to take effect.
Customizing the Behavior
The default dependency discovery heuristics may not always be desirable. In cases where you want to explicitly include/exclude dependencies from the list, use the 
optimizeDeps config options.
A typical use case for 
optimizeDeps.include or 
optimizeDeps.exclude is when you have an import that is not directly discoverable in the source code. For example, maybe the import is created as a result of a plugin transform. This means Vite won't be able to discover the import on the initial scan - it can only discover it after the file is requested by the browser and transformed. This will cause the server to immediately re-bundle after server start.
Both 
include and 
exclude can be used to deal with this. If the dependency is large (with many internal modules) or is CommonJS, then you should include it; If the dependency is small and is already valid ESM, you can exclude it and let the browser load it directly.
You can further customize Rolldown too with the 
optimizeDeps.rolldownOptions option. For example, adding a Rolldown plugin to handle special files in dependencies or changing the build 
target.
Caching
File System Cache
Vite caches the pre-bundled dependencies in 
node_modules/.vite. It determines whether it needs to re-run the pre-bundling step based on a few sources:
Package manager lockfile content, e.g. 
package-lock.json, 
yarn.lock, 
pnpm-lock.yaml, 
bun.lock, 
aube-lock.yaml or 
nub.lock.
Patches folder modification time.
Relevant fields in your 
vite.config.js, if present.
NODE_ENV value.
The pre-bundling step will only need to be re-run when one of the above has changed.
If for some reason you want to force Vite to re-bundle deps, you can either start the dev server with the 
--force command line option, or manually delete the 
node_modules/.vite cache directory.
Browser Cache
Resolved dependency requests are strongly cached with HTTP headers 
max-age=31536000,immutable to improve page reload performance during dev. Once cached, these requests will never hit the dev server again. They are auto invalidated by the appended version query if a different version is installed (as reflected in your package manager lockfile). If you want to debug your dependencies by making local edits, you can:
Temporarily disable cache via the Network tab of your browser devtools.
Restart Vite dev server with the 
--force flag to re-bundle the deps.
Reload the page.

Env Variables and Modes
Vite exposes certain constants under the special 
import.meta.env object. These constants are defined as global variables during dev and statically replaced at build time to make tree-shaking effective.
:::details Example
if (import.meta.env.DEV) {
  // code inside here will be tree-shaken in production builds
  console.log('Dev mode')
}
:::
Watch an interactive lesson on Scrimba
Built-in Constants
Some built-in constants are available 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. This is determined by the 
base config option.
import.meta.env.PROD: {boolean} whether the app is running in production (running the dev server with 
NODE_ENV='production' or running an app built with 
NODE_ENV='production').
import.meta.env.DEV: {boolean} whether the app is running in development (always the opposite of 
import.meta.env.PROD)
import.meta.env.SSR: {boolean} whether the app is running in the server.
Env Variables
Vite exposes env variables under the 
import.meta.env object as strings automatically.
Variables prefixed with 
VITE_ will be exposed in client-side source code after Vite bundling. To prevent accidentally leaking env variables to the client, avoid using this prefix. As an example, consider the following:
VITE_SOME_KEY=123
DB_PASSWORD=foobar
The parsed value of 
VITE_SOME_KEY – 
"123" – will be exposed on the client, but the value of 
DB_PASSWORD will not. You can test this by adding the following to your code:
console.log(import.meta.env.VITE_SOME_KEY) // "123"
console.log(import.meta.env.DB_PASSWORD) // undefined
If you want to customize the env variables prefix, see the envPrefix option.
:::tip Env parsing
As shown above, 
VITE_SOME_KEY is a number but returns a string when parsed. The same would also happen for boolean env variables. Make sure to convert to the desired type when using it in your code.
:::
:::warning Protecting secrets
VITE_* variables should not contain sensitive information such as API keys. The values of these variables are bundled into your source code at build time. For production deployments, consider a backend server or serverless/edge functions to properly secure secrets.
:::
.env Files
Vite uses dotenv to load additional environment variables from the following files in your environment directory:
.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
:::tip Env Loading Priorities
An env file for a specific mode (e.g. 
.env.production) will take higher priority than a generic one (e.g. 
.env).
Vite will always load 
.env and 
.env.local in addition to the mode-specific 
.env.[mode] file. Variables declared in mode-specific files will take precedence over those in generic files, but variables defined only in 
.env or 
.env.local will still be available in the environment.
In addition, environment variables that already exist when Vite is executed have the highest priority and will not be overwritten by 
.env files. For example, when running 
VITE_SOME_KEY=123 vite build.
.env files are loaded at the start of Vite. Restart the server after making changes.
:::
:::warning Bun users
When using Bun, be aware that Bun automatically loads 
.env files before your script runs. This built-in behavior loads environment variables directly into 
process.env and can interfere with Vite's feature, as it respects existing 
process.env values. See oven-sh/bun#5515 for workarounds.
:::
Also, Vite uses dotenv-expand to expand variables written in env files out of the box. To learn more about the syntax, check out their docs.
Note that if you want to use 
$ inside your environment value, you have to escape it with 
\.
KEY=123
NEW_KEY1=test$foo   # test
NEW_KEY2=test\$foo  # test$foo
NEW_KEY3=test$KEY   # test123
::: details Expanding variables in reverse order
Vite supports expanding variables in reverse order.
For example, the 
.env below will be evaluated as 
VITE_FOO=foobar, 
VITE_BAR=bar.
VITE_FOO=foo${VITE_BAR}
VITE_BAR=bar
This does not work in shell scripts and other tools like 
docker compose.
That said, Vite supports this behavior as this has been supported by 
dotenv-expand for a long time and other tools in JavaScript ecosystem use older versions that support this behavior.
To avoid interop issues, it is recommended to avoid relying on this behavior. Vite may start emitting warnings for this behavior in the future.
:::
:::warning Ignoring local 
.env files
.env.*.local files are local-only and can contain sensitive variables. You should add 
*.local to your 
.gitignore to avoid them being checked into git.
:::
IntelliSense for TypeScript
By default, Vite provides type definitions for 
import.meta.env in 
vite/client.d.ts. While you can define more custom env variables in 
.env.[mode] files, you may want to get TypeScript IntelliSense for user-defined env variables that are prefixed with 
VITE_.
To achieve this, you can create a 
vite-env.d.ts in the 
src directory, then augment 
ImportMetaEnv like this:
interface ViteTypeOptions {
  // By adding this line, you can make the type of ImportMetaEnv strict
  // to disallow unknown keys.
  // strictImportMetaEnv: unknown
}
interface ImportMetaEnv {
  readonly VITE_APP_TITLE: string
  // more env variables...
}
interface ImportMeta {
  readonly env: ImportMetaEnv
}
If your code relies on types from browser environments such as DOM and WebWorker, you can update the lib field in 
tsconfig.json.
{
  "lib": ["WebWorker"]
}
:::warning Imports will break type augmentation
If the 
ImportMetaEnv augmentation does not work, make sure you do not have any 
import statements in 
vite-env.d.ts. See the TypeScript documentation for more information.
:::
HTML Constant Replacement
Vite also supports replacing constants in HTML files. Any properties in 
import.meta.env can be used in HTML files with a special 
%CONST_NAME% syntax:
<h1>Vite is running in %MODE%</h1>
<p>Using data from %VITE_API_URL%</p>
If the env doesn't exist in 
import.meta.env, e.g. 
%NON_EXISTENT%, it will be ignored and not replaced, unlike 
import.meta.env.NON_EXISTENT in JS where it's replaced as 
undefined.
Given that Vite is used by many frameworks, it is intentionally unopinionated about complex replacements like conditionals. Vite can be extended using an existing userland plugin or a custom plugin that implements the 
transformIndexHtml hook.
Modes
By default, the dev server (
dev command) runs in 
development mode and the 
build command runs in 
production mode.
This means when running 
vite build, it will load the env variables from 
.env.production if there is one:
VITE_APP_TITLE=My App
In your app, you can render the title using 
import.meta.env.VITE_APP_TITLE.
In some cases, you may want to run 
vite build with a different mode to render a different title. You can overwrite the default mode used for a command by passing the 
--mode option flag. For example, if you want to build your app for a staging mode:
vite build --mode staging
And create a 
.env.staging file:
VITE_APP_TITLE=My App (staging)
As 
vite build runs a production build by default, you can also change this and run a development build by using a different mode and 
.env file configuration:
NODE_ENV=development
NODE_ENV and Modes
It's important to note that 
NODE_ENV (
process.env.NODE_ENV) and modes are two different concepts. Here's how different commands affect the 
NODE_ENV and mode:
Command
NODE_ENV
Mode
vite build
"production"
"production"
vite build --mode development
"production"
"development"
NODE_ENV=development vite build
"development"
"production"
NODE_ENV=development vite build --mode development
"development"
"development"
The different values of 
NODE_ENV and mode also reflect on its corresponding 
import.meta.env properties:
Command
import.meta.env.PROD
import.meta.env.DEV
NODE_ENV=production
true
false
NODE_ENV=development
false
true
NODE_ENV=other
false
true
Command
import.meta.env.MODE
--mode production
"production"
--mode development
"development"
--mode staging
"staging"
:::tip 
NODE_ENV in 
.env files
NODE_ENV=... can be set in the command, and also in your 
.env file. If 
NODE_ENV is specified in a 
.env.[mode] file, the mode can be used to control its value. However, both 
NODE_ENV and modes remain as two different concepts.
The main benefit with 
NODE_ENV=... in the command is that it allows Vite to detect the value early. It also allows you to read 
process.env.NODE_ENV in your Vite config as Vite can only load the env files once the config is evaluated.
:::

Features
At the very basic level, developing using Vite is not that different from using a static file server. However, Vite provides many enhancements over native ESM imports to support various features that are typically seen in bundler-based setups.
npm Dependency Resolving and Pre-Bundling
Native ES imports do not support bare module imports like the following:
import { someMethod } from 'my-dep'
The above import will throw an error in the browser. Vite will detect such bare module imports in all served source files and perform the following:
Pre-bundle them to improve page loading speed and convert CommonJS / UMD modules to ESM. The pre-bundling step is performed with Rolldown and makes Vite's cold start time significantly faster than any JavaScript-based bundler.
Rewrite the imports to valid URLs like 
/node_modules/.vite/deps/my-dep.js?v=f3sf2ebd so that the browser can import them properly.
Dependencies are Strongly Cached
Vite caches dependency requests via HTTP headers, so if you wish to locally edit/debug a dependency, follow the steps here.
Hot Module Replacement
Vite provides an HMR API over native ESM. Frameworks with HMR capabilities can leverage the API to provide instant, precise updates without reloading the page or blowing away application state. Vite provides first-party HMR integrations for Vue Single File Components and React Fast Refresh. There are also official integrations for Preact via @prefresh/vite.
Note you don't need to manually set these up - when you create an app via 
create-vite, the selected templates would have these pre-configured for you already.
TypeScript
Vite supports importing 
.ts files out of the box.
Transpile Only
Note that Vite only performs transpilation on 
.ts files and does NOT perform type checking. It assumes type checking is taken care of by your IDE and build process.
The reason Vite does not perform type checking as part of the transform process is because the two jobs work fundamentally differently. Transpilation can work on a per-file basis and aligns perfectly with Vite's on-demand compile model. In comparison, type checking requires knowledge of the entire module graph. Shoe-horning type checking into Vite's transform pipeline will inevitably compromise Vite's speed benefits.
Vite's job is to get your source modules into a form that can run in the browser as fast as possible. To that end, we recommend separating static analysis checks from Vite's transform pipeline. This principle applies to other static analysis checks such as ESLint.
For production builds, you can run 
tsc --noEmit in addition to Vite's build command.
During development, if you need more than IDE hints, we recommend running 
tsc --noEmit --watch in a separate process, or use vite-plugin-checker if you prefer having type errors directly reported in the browser.
Vite uses Oxc Transformer to transpile TypeScript into JavaScript which is faster than vanilla 
tsc, and HMR updates can reflect in the browser in under 50ms.
Use the Type-Only Imports and Export syntax to avoid potential problems like type-only imports being incorrectly bundled, for example:
import type { T } from 'only/types'
export type { T }
TypeScript Compiler Options
Vite respects some of the options in 
tsconfig.json and sets the corresponding Oxc Transformer options. By default, Vite uses the closest parent 
tsconfig.json that matches each file. A config referenced by that config's 
references field is used when it matches the file. Vite treats a config as matching the file when the file satisfies the config's 
files, 
include, and 
exclude fields.
When the options are set in both the Vite config and the 
tsconfig.json, the value in the Vite config takes precedence.
Some configuration fields under 
compilerOptions in 
tsconfig.json require special attention.
isolatedModules
TypeScript documentation
Should be set to 
true.
It is because Oxc transformer only performs transpilation without type information, it doesn't support certain features like const enum and implicit type-only imports.
You must set 
"isolatedModules": true in your 
tsconfig.json under 
compilerOptions, so that TS will warn you against the features that do not work with isolated transpilation.
If a dependency doesn't work well with 
"isolatedModules": true, you can use 
"skipLibCheck": true to temporarily suppress the errors until it is fixed upstream.
useDefineForClassFields
TypeScript documentation
The default value will be 
true if the TypeScript target is 
ES2022 or newer including 
ESNext. It is consistent with the behavior of TypeScript 4.3.2+.
Other TypeScript targets will default to 
false.
true is the standard ECMAScript runtime behavior.
If you are using a library that heavily relies on class fields, please be careful about the library's intended usage of it.
While most libraries expect 
"useDefineForClassFields": true, you can explicitly set 
useDefineForClassFields to 
false if your library doesn't support it.
target
TypeScript documentation
Vite ignores the 
target value in the 
tsconfig.json, following the same behavior as esbuild.
To specify the target in dev, the 
oxc.target option can be used, which defaults to 
esnext for minimal transpilation. In builds, the 
build.target option takes higher priority over 
oxc.target and can also be set if needed.
emitDecoratorMetadata
TypeScript documentation
This option is only partially supported. Full support requires type inference by the TypeScript compiler, which is not supported. See Oxc Transformer's documentation for details.
paths
TypeScript documentation
resolve.tsconfigPaths: true can be specified to tell Vite to use the 
paths option in 
tsconfig.json to resolve imports.
Note that this feature has a performance cost and is discouraged by the TypeScript team to use this option to change the behavior of the external tools.
Other Compiler Options Affecting the Build Result
extends
importsNotUsedAsValues
preserveValueImports
verbatimModuleSyntax
jsx
jsxFactory
jsxFragmentFactory
jsxImportSource
experimentalDecorators
::: tip 
skipLibCheck
Vite starter templates have 
"skipLibCheck": true by default to avoid typechecking dependencies, as they may choose to only support specific versions and configurations of TypeScript. You can learn more at vuejs/vue-cli#5688.
:::
Client Types
Vite's default types are for its Node.js API. To shim the environment of client-side code in a Vite application, you can add 
vite/client to 
compilerOptions.types inside 
tsconfig.json:
{
  "compilerOptions": {
    "types": ["vite/client", "some-other-global-lib"]
  }
}
Note that if 
compilerOptions.types is specified, only these packages will be included in the global scope (instead of all visible ”@types” packages). This is recommended since TS 5.9.
::: details Using triple-slash directive
Alternatively, you can add a 
d.ts declaration file:
/// <reference types="vite/client" />
:::
vite/client provides the following type shims:
Asset imports (e.g. importing an 
.svg file)
Types for the Vite-injected constants on 
import.meta.env
Types for the HMR API on 
import.meta.hot
::: tip
To override the default typing, add a type definition file that contains your typings. Then, add the type reference before 
vite/client.
For example, to make the default import of 
*.svg a React component:
vite-env-override.d.ts (the file that contains your typings):
declare module '*.svg' {
  const content: React.FC<React.SVGProps<SVGElement>>
  export default content
}
If you are using 
compilerOptions.types, ensure the file is included in 
tsconfig.json:
{
  "include": ["src", "./vite-env-override.d.ts"]
}
If you are using triple-slash directives, update the file containing the reference to 
vite/client (normally 
vite-env.d.ts):
/// <reference types="./vite-env-override.d.ts" />
/// <reference types="vite/client" />
:::
HTML
HTML files stand front-and-center of a Vite project, serving as the entry points for your application, making it simple to build single-page and multi-page applications.
Any HTML files in your project root can be directly accessed by its respective directory path:
<root>/index.html -> 
http://localhost:5173/
<root>/about.html -> 
http://localhost:5173/about.html
<root>/blog/index.html -> 
http://localhost:5173/blog/index.html
Assets referenced by HTML elements such as 
<script type="module" src> and 
<link href> are processed and bundled as part of the app. The full list of supported elements is as below:
<audio src>
<embed src>
<img src> and 
<img srcset>
<image href> and 
<image xlink:href>
<input src>
<link href> and 
<link imagesrcset>
<object data>
<script type="module" src>
<source src> and 
<source srcset>
<track src>
<use href> and 
<use xlink:href>
<video src> and 
<video poster>
<meta content>
Only if 
name attribute matches 
msapplication-tileimage, 
msapplication-square70x70logo, 
msapplication-square150x150logo, 
msapplication-wide310x150logo, 
msapplication-square310x310logo, 
msapplication-config, or 
twitter:image
Or only if 
property attribute matches 
og:image, 
og:image:url, 
og:image:secure_url, 
og:audio, 
og:audio:secure_url, 
og:video, or 
og:video:secure_url
<!doctype html>
<html>
  <head>
    <link rel="icon" href="/favicon.ico" />
    <link rel="stylesheet" href="/src/styles.css" />
  </head>
  <body>
    <img src="/src/images/logo.svg" alt="logo" />
    <script type="module" src="/src/main.js"></script>
  </body>
</html>
To opt-out of HTML processing on certain elements, you can add the 
vite-ignore attribute on the element, which can be useful when referencing external assets or CDN.
Frameworks
All modern frameworks maintain integrations with Vite. Most framework plugins are maintained by each framework team, with the exception of the official Vue and React Vite plugins that are maintained in the vite org:
Vue support via @vitejs/plugin-vue
Vue JSX support via @vitejs/plugin-vue-jsx
React support via @vitejs/plugin-react
React using SWC support via @vitejs/plugin-react-swc
React Server Components (RSC) support via @vitejs/plugin-rsc
Check out the Plugins Guide for more information.
JSX
.jsx and 
.tsx files are also supported out of the box. JSX transpilation is also handled via Oxc Transformer.
Your framework of choice will already configure JSX out of the box (for example, Vue users should use the official @vitejs/plugin-vue-jsx plugin, which provides Vue 3 specific features including HMR, global component resolving, directives and slots).
If using JSX with your own framework, custom 
jsxFactory and 
jsxFragment can be configured using the 
oxc option. For example, the Preact plugin would use:
import { defineConfig } from 'vite'
export default defineConfig({
  oxc: {
    jsx: {
      importSource: 'preact',
    },
  },
})
More details in Oxc Transformer docs.
You can inject the JSX helpers using 
jsxInject (which is a Vite-only option) to avoid manual imports:
import { defineConfig } from 'vite'
export default defineConfig({
  oxc: {
    jsxInject: `import React from 'react'`,
  },
})
CSS
Importing 
.css files will inject its content to the page via a 
<style> tag with HMR support.
@import Inlining and Rebasing
Vite is pre-configured to support CSS 
@import inlining via 
postcss-import. Vite aliases are also respected for CSS 
@import. In addition, all CSS 
url() references, even if the imported files are in different directories, are always automatically rebased to ensure correctness.
@import aliases and URL rebasing are also supported for Sass and Less files (see CSS Pre-processors).
PostCSS
If the project contains valid PostCSS config (any format supported by postcss-load-config, e.g. 
postcss.config.js), it will be automatically applied to all imported CSS.
Note that CSS minification will run after PostCSS and will use the 
build.cssTarget option.
CSS Modules
Any CSS file ending with 
.module.css is considered a CSS modules file. Importing such a file will return the corresponding module object:
.red {
  color: red;
}
import 'vite/client'
// ---cut---
import classes from './example.module.css'
document.getElementById('foo').className = classes.red
CSS modules behavior can be configured via the 
css.modules option.
If 
css.modules.localsConvention is set to enable camelCase locals (e.g. 
localsConvention: 'camelCaseOnly'), you can also use named imports:
import 'vite/client'
// ---cut---
// .apply-color -> applyColor
import { applyColor } from './example.module.css'
document.getElementById('foo').className = applyColor
CSS Pre-processors
Because Vite targets modern browsers only, it is recommended to use native CSS variables with PostCSS plugins that implement CSSWG drafts (e.g. postcss-nesting) and author plain, future-standards-compliant CSS.
That said, Vite does provide built-in support for 
.scss, 
.sass, 
.less, 
.styl and 
.stylus files. There is no need to install Vite-specific plugins for them, but the corresponding pre-processor itself must be installed:
# .scss and .sass
npm add -D sass-embedded # or sass
# .less
npm add -D less
# .styl and .stylus
npm add -D stylus
If using Vue single file components, this also automatically enables 
<style lang="sass"> et al.
Vite improves 
@import resolving for Sass and Less so that Vite aliases are also respected. In addition, relative 
url() references inside imported Sass/Less files that are in different directories from the root file are also automatically rebased to ensure correctness. Rebasing 
url() references that start with a variable or an interpolation is not supported due to its API constraints.
@import alias and url rebasing are not supported for Stylus due to its API constraints.
You can also use CSS modules combined with pre-processors by prepending 
.module to the file extension, for example 
style.module.scss.
Disabling CSS injection into the page
The automatic injection of CSS contents can be turned off via the 
?inline query parameter. In this case, the processed CSS string is returned as the module's default export as usual, but the styles aren't injected to the page.
import 'vite/client'
// ---cut---
import './foo.css' // will be injected into the page
import otherStyles from './bar.css?inline' // will not be injected
::: tip NOTE
Default and named imports from CSS files (e.g 
import style from './foo.css') are removed since Vite 5. Use the 
?inline query instead.
:::
Lightning CSS
Vite uses Lightning CSS to minify CSS in production builds by default. However, PostCSS is still used for other CSS processing.
There is experimental support for using Lightning CSS for CSS processing entirely. You can opt into it by adding 
css.transformer: 'lightningcss'.
To configure it, you can pass Lightning CSS options to the 
css.lightningcss config option. To configure CSS Modules, you should use 
css.lightningcss.cssModules instead of 
css.modules (which configures the way PostCSS handles CSS modules).
Static Assets
Watch an interactive lesson on Scrimba
Importing a static asset will return the resolved public URL when it is served:
import 'vite/client'
// ---cut---
import imgUrl from './img.png'
document.getElementById('hero-img').src = imgUrl
Special queries can modify how assets are loaded:
import 'vite/client'
// ---cut---
// Explicitly load assets as URL (automatically inlined depending on the file size)
import assetAsURL from './asset.js?url'
import 'vite/client'
// ---cut---
// Load assets as strings
import assetAsString from './shader.glsl?raw'
import 'vite/client'
// ---cut---
// Load Web Workers
import Worker from './worker.js?worker'
import 'vite/client'
// ---cut---
// Web Workers inlined as base64 strings at build time
import InlineWorker from './worker.js?worker&inline'
More details in Static Asset Handling.
JSON
JSON files can be directly imported - named imports are also supported:
import 'vite/client'
// ---cut---
// import the entire object
import json from './example.json'
// import a root field as named exports - helps with tree-shaking!
import { field } from './example.json'
Glob Import
Vite supports importing multiple modules from the file system via the special 
import.meta.glob function:
import 'vite/client'
// ---cut---
const modules = import.meta.glob('./dir/*.js')
The above will be transformed into the following:
// code produced by vite
const modules = {
  './dir/bar.js': () => import('./dir/bar.js'),
  './dir/foo.js': () => import('./dir/foo.js'),
}
You can then iterate over the keys of the 
modules object to access the corresponding modules:
for (const path in modules) {
  modules[path]().then((mod) => {
    console.log(path, mod)
  })
}
Matched files are by default lazy-loaded via dynamic import and will be split into separate chunks during build. If you'd rather import all the modules directly (e.g. relying on side-effects in these modules to be applied first), you can pass 
{ eager: true } as the second argument:
import 'vite/client'
// ---cut---
const modules = import.meta.glob('./dir/*.js', { eager: true })
The above will be transformed into the following:
// code produced by vite
import * as __vite_glob_0_0 from './dir/bar.js'
import * as __vite_glob_0_1 from './dir/foo.js'
const modules = {
  './dir/bar.js': __vite_glob_0_0,
  './dir/foo.js': __vite_glob_0_1,
}
Multiple Patterns
The first argument can be an array of globs, for example
import 'vite/client'
// ---cut---
const modules = import.meta.glob(['./dir/*.js', './another/*.js'])
Negative Patterns
Negative glob patterns are also supported (prefixed with 
!). To ignore some files from the result, you can add exclude glob patterns to the first argument:
import 'vite/client'
// ---cut---
const modules = import.meta.glob(['./dir/*.js', '!**/bar.js'])
// code produced by vite
const modules = {
  './dir/foo.js': () => import('./dir/foo.js'),
}
Named Imports
It's possible to only import parts of the modules with the 
import options.
import 'vite/client'
// ---cut---
const modules = import.meta.glob('./dir/*.js', { import: 'setup' })
// code produced by vite
const modules = {
  './dir/bar.js': () => import('./dir/bar.js').then((m) => m.setup),
  './dir/foo.js': () => import('./dir/foo.js').then((m) => m.setup),
}
When combined with 
eager it's even possible to have tree-shaking enabled for those modules.
import 'vite/client'
// ---cut---
const modules = import.meta.glob('./dir/*.js', {
  import: 'setup',
  eager: true,
})
// code produced by vite:
import { setup as __vite_glob_0_0 } from './dir/bar.js'
import { setup as __vite_glob_0_1 } from './dir/foo.js'
const modules = {
  './dir/bar.js': __vite_glob_0_0,
  './dir/foo.js': __vite_glob_0_1,
}
Set 
import to 
default to import the default export.
import 'vite/client'
// ---cut---
const modules = import.meta.glob('./dir/*.js', {
  import: 'default',
  eager: true,
})
// code produced by vite:
import { default as __vite_glob_0_0 } from './dir/bar.js'
import { default as __vite_glob_0_1 } from './dir/foo.js'
const modules = {
  './dir/bar.js': __vite_glob_0_0,
  './dir/foo.js': __vite_glob_0_1,
}
Custom Queries
You can also use the 
query option to provide queries to imports, for example, to import assets as a string or as a url:
import 'vite/client'
// ---cut---
const moduleStrings = import.meta.glob('./dir/*.svg', {
  query: '?raw',
  import: 'default',
})
const moduleUrls = import.meta.glob('./dir/*.svg', {
  query: '?url',
  import: 'default',
})
// code produced by vite:
const moduleStrings = {
  './dir/bar.svg': () => import('./dir/bar.svg?raw').then((m) => m['default']),
  './dir/foo.svg': () => import('./dir/foo.svg?raw').then((m) => m['default']),
}
const moduleUrls = {
  './dir/bar.svg': () => import('./dir/bar.svg?url').then((m) => m['default']),
  './dir/foo.svg': () => import('./dir/foo.svg?url').then((m) => m['default']),
}
You can also provide custom queries for other plugins to consume:
import 'vite/client'
// ---cut---
const modules = import.meta.glob('./dir/*.js', {
  query: { foo: 'bar', bar: true },
})
Base Path
You can also use the 
base option to provide base path for the imports:
import 'vite/client'
// ---cut---
const modulesWithBase = import.meta.glob('./**/*.js', {
  base: './base',
})
// code produced by vite:
const modulesWithBase = {
  './dir/foo.js': () => import('./base/dir/foo.js'),
  './dir/bar.js': () => import('./base/dir/bar.js'),
}
The base option can only be a directory path relative to the importer file or absolute against the project root. Aliases and virtual modules aren't supported.
Only the globs that are relative paths are interpreted as relative to the resolved base.
All the resulting module keys are modified to be relative to the base if provided.
Case Sensitive Matching
By default, glob pattern matching is case-sensitive. You can use the 
caseSensitive option to change this behavior:
import 'vite/client'
// ---cut---
const modules = import.meta.glob('./dir/module*.js', {
  caseSensitive: false,
})
With 
caseSensitive: false, the glob will match files regardless of case (e.g., 
Module.js, 
module.js, 
MODULE.js will all be matched by 
module*.js).
Glob Import Caveats
Note that:
This is a Vite-only feature and is not a web or ES standard.
The glob patterns are treated like import specifiers: they must be either relative (start with 
./) or absolute (start with 
/, resolved relative to project root) or an alias path (see 
resolve.alias option).
The glob matching is done via 
tinyglobby - check out its documentation for supported glob patterns.
You should also be aware that all the arguments in the 
import.meta.glob must be passed as literals. You can NOT use variables or expressions in them.
Dynamic Import
Similar to glob import, Vite also supports dynamic import with variables.
const module = await import(`./dir/${file}.js`)
Note that variables only represent file names one level deep. If 
file is 
'foo/bar', the import would fail. For more advanced usage, you can use the glob import feature.
Also note that the dynamic import must match the following rules to be bundled:
Imports must start with 
./ or 
../ or 
#: 
import(`./dir/${foo}.js`) is valid, but 
import(`${foo}.js`) is not.
Imports must end with a file extension: 
import(`./dir/${foo}.js`) is valid, but 
import(`./dir/${foo}`) is not.
Imports to the own directory must specify a file name pattern: 
import(`./prefix-${foo}.js`) is valid, but 
import(`./${foo}.js`) is not.
These rules are enforced to prevent accidentally importing files that are not intended to be bundled. For example, without these rules, 
import(foo) would bundle everything in the file system.
WebAssembly
Vite supports importing pre-compiled 
.wasm files in two ways: directly as an ES module when you only need the module's exports, or with 
?init when you need explicit control over instantiation.
ESM Integration
A 
.wasm file can be imported directly. Vite reads the module's imports and exports from the binary, instantiates it, and re-exposes its exports as named ES module exports:
import { add } from './add.wasm'
console.log(add(1, 2)) // 3
If the WebAssembly module declares imports of its own, Vite resolves them from JavaScript modules. Each import's module name is treated as an import specifier (resolved relative to the 
.wasm file) and the requested members are wired into the instance automatically.
This follows the WebAssembly/ES Module Integration proposal. Because a WebAssembly module is instantiated asynchronously, a directly imported 
.wasm file behaves as an async module and requires top-level 
await support.
::: tip TypeScript support
Since the types of 
.wasm files are unknown, TypeScript will report errors like 
Module '"*.wasm"' has no exported member 'add'. To fix this, enable 
allowArbitraryExtensions in your 
tsconfig.json and create a declaration file next to your 
.wasm file. With 
allowArbitraryExtensions enabled, TypeScript will look for a declaration file named 
{filename}.d.wasm.ts when resolving a 
.wasm import. For example, for 
add.wasm, create 
add.d.wasm.ts:
export function add(a: number, b: number): number
:::
Manual Initialization
When you need control over when and how the module is instantiated, import it with 
?init. The default export will be an initialization function that returns a Promise of the 
WebAssembly.Instance:
import 'vite/client'
// ---cut---
import init from './example.wasm?init'
init().then((instance) => {
  instance.exports.test()
})
The init function can also take an importObject which is passed along to 
WebAssembly.instantiate as its second argument:
import 'vite/client'
import init from './example.wasm?init'
// ---cut---
init({
  imports: {
    someFunc: () => {
      /* ... */
    },
  },
}).then(() => {
  /* ... */
})
In the production build, 
.wasm files smaller than 
assetsInlineLimit will be inlined as base64 strings. Otherwise, they will be treated as a static asset and fetched on-demand.
::: warning For SSR build, Node.js compatible runtimes are only supported
Due to the lack of a universal way to load a file, the internal implementation for both direct 
.wasm imports and 
.wasm?init relies on the 
node:fs module. This means that these features will only work in Node.js compatible runtimes for SSR builds.
:::
Accessing the WebAssembly Module
If you need access to the 
Module object, e.g. to instantiate it multiple times, use an explicit URL import to resolve the asset, and then perform the instantiation:
import 'vite/client'
// ---cut---
import wasmUrl from 'foo.wasm?url'
const main = async () => {
  const responsePromise = fetch(wasmUrl)
  const { module, instance } =
    await WebAssembly.instantiateStreaming(responsePromise)
  /* ... */
}
main()
Web Workers
Import with Constructors
A web worker script can be imported using 
new Worker() and 
new SharedWorker(). Compared to the worker suffixes, this syntax leans closer to the standards and is the recommended way to create workers.
const worker = new Worker(new URL('./worker.js', import.meta.url))
The worker constructor also accepts options, which can be used to create "module" workers:
const worker = new Worker(new URL('./worker.js', import.meta.url), {
  type: 'module',
})
The worker detection will only work if the 
new URL() constructor is used directly inside the 
new Worker() declaration. Otherwise it is handled as a static asset URL instead. Additionally, all options parameters must be static values (i.e. string literals).
Import with Query Suffixes
A web worker script can be directly imported by appending 
?worker or 
?sharedworker to the import request. The default export will be a custom worker constructor:
import 'vite/client'
// ---cut---
import MyWorker from './worker?worker'
const worker = new MyWorker()
The worker script can also use ESM 
import statements instead of 
importScripts(). Note: During development this relies on browser native support, but for the production build it is compiled away.
By default, the worker script will be emitted as a separate chunk in the production build. If you wish to inline the worker as base64 strings, add the 
inline query:
import 'vite/client'
// ---cut---
import MyWorker from './worker?worker&inline'
If you wish to retrieve the worker as a URL, add the 
url query:
import 'vite/client'
// ---cut---
import MyWorker from './worker?worker&url'
See Worker Options for details on configuring the bundling of all workers.
Content Security Policy (CSP)
To deploy CSP, certain directives or configs must be set due to Vite's internals.
'nonce-{RANDOM}'
When 
html.cspNonce is set, Vite adds a nonce attribute with the specified value to any 
<script> and 
<style> tags, as well as 
<link> tags for stylesheets and module preloading. Additionally, when this option is set, Vite will inject a meta tag (
<meta property="csp-nonce" nonce="PLACEHOLDER" />).
The nonce value of a meta tag with 
property="csp-nonce" will be used by Vite whenever necessary during both dev and after build.
:::warning
Ensure that you replace the placeholder with a unique value for each request. This is important to prevent bypassing a resource's policy, which can otherwise be easily done.
:::
data:
By default, during build, Vite inlines small assets as data URIs. Allowing 
data: for related directives (e.g. 
img-src, 
font-src), or, disabling it by setting 
build.assetsInlineLimit: 0 is necessary.
:::warning
Do not allow 
data: for 
script-src. It will allow injection of arbitrary scripts.
:::
License
Vite can generate a file of all the dependencies' licenses used in the build with the 
build.license option. It can be hosted to display and acknowledge the dependencies used by the app.
import { defineConfig } from 'vite'
export default defineConfig({
  build: {
    license: true,
  },
})
This will generate a 
.vite/license.md file with an output that may look like this:
# Licenses
The app bundles dependencies which contain the following licenses:
## dep-1 - 1.2.3 (CC0-1.0)
CC0 1.0 Universal
...
## dep-2 - 4.5.6 (MIT)
MIT License
...
To serve the file at a different path, you can pass 
{ fileName: 'license.md' } for example, so that it's served at 
https://example.com/license.md. See the 
build.license docs for more information.
Build Optimizations
Features listed below are automatically applied (except for the experimental chunk import map feature) as part of the build process and there is no need for explicit configuration unless you want to disable them.
CSS Code Splitting
Vite automatically extracts the CSS used by modules in an async chunk and generates a separate file for it. The CSS file is automatically loaded via a 
<link> tag when the associated async chunk is loaded, and the async chunk is guaranteed to only be evaluated after the CSS is loaded to avoid FOUC.
If you'd rather have all the CSS extracted into a single file, you can disable CSS code splitting by setting 
build.cssCodeSplit to 
false.
Preload Directives Generation
Vite automatically generates 
<link rel="modulepreload"> directives for entry chunks and their direct imports in the built HTML.
Async Chunk Loading Optimization
In real world applications, Rollup often generates "common" chunks - code that is shared between two or more other chunks. Combined with dynamic imports, it is quite common to have the following scenario:
In the non-optimized scenarios, when async chunk 
A is imported, the browser will have to request and parse 
A before it can figure out that it also needs the common chunk 
C. This results in an extra network roundtrip:
Entry ---> A ---> C
Vite automatically rewrites code-split dynamic import calls with a preload step so that when 
A is requested, 
C is fetched in parallel:
Entry ---> (A + C)
It is possible for 
C to have further imports, which will result in even more roundtrips in the un-optimized scenario. Vite's optimization will trace all the direct imports to completely eliminate the roundtrips regardless of import depth.
Chunk Import Map Optimization
To improve the cache hit rate of chunks, Vite can create an import map for chunks. This prevents the cascading cache invalidation issue, which is a problem with ES Modules.
For example, consider the following scenario:
Entry --> A ---> C
If 
C is updated, the only chunk that inherently needs to be invalidated is 
C. However, if 
A references 
C via a normal URL in a static import (i.e. the hash of 
C is included in the URL), the content of 
A is changed, thus 
A would also need to be invalidated. The same applies to 
Entry.
By utilizing the import maps feature, this issue can be avoided. When this optimization is enabled, Vite will create an import map that maps each chunk's ID to its URL and uses the chunk ID in the import statements instead of the URL. This way, when a chunk is updated, only the updated chunk needs to be invalidated, while the chunks that reference it will not be invalidated.
Note that this optimization currently does not apply to CSS and assets. If you update an asset, the chunks that reference it will be invalidated. That said, the invalidation would not cascade and the chunk importing the invalidated chunk would not be invalidated.
To enable this feature, set 
build.chunkImportMap to 
true.

Getting Started
Overview
Vite (French word for "quick", pronounced 
/viːt/, like "veet") is a build tool that aims to provide a faster and leaner development experience for modern web projects. It consists of two major parts:
A dev server that provides rich feature enhancements over native ES modules, for example extremely fast Hot Module Replacement (HMR).
A build command that bundles your code with Rolldown, pre-configured to output highly optimized static assets for production.
Vite is opinionated and comes with sensible defaults out of the box. Read about what's possible in the Features Guide. Support for frameworks or integration with other tools is possible through Plugins. The Config Section explains how to adapt Vite to your project if needed.
Vite is also highly extensible via its Plugin API and JavaScript API with full typing support.
You can learn more about the rationale behind the project in the Why Vite section.
Learn Vite through interactive tutorials on Scrimba
Browser Support
During development, Vite assumes that a modern browser is used. This means the browser supports most of the latest JavaScript and CSS features. For that reason, Vite sets 
esnext as the transform target. This prevents syntax lowering, letting Vite serve modules as close as possible to the original source code. Vite injects some runtime code to make the development server work. This code uses features included in Baseline Newly Available at the time of each major release (2026-01-01 for this major).
For production builds, Vite by default targets Baseline Widely Available browser versions as of a date fixed for each major release. For this major, that corresponds to browser versions released around mid-2023. The target can be lowered via configuration. Additionally, legacy browsers can be supported via the official @vitejs/plugin-legacy. See the Building for Production section for more details.
Trying Vite Online
You can try Vite online on StackBlitz. It runs the Vite-based build setup directly in the browser, so it is almost identical to the local setup but doesn't require installing anything on your machine. You can navigate to 
vite.new/{template} to select which framework to use.
The supported template presets are:
JavaScript
TypeScript
vanilla
vanilla-ts
vue
vue-ts
react
react-ts
preact
preact-ts
lit
lit-ts
svelte
svelte-ts
solid
solid-ts
qwik
qwik-ts
Scaffolding Your First Vite Project
::: code-group
$ npm create vite@latest
$ yarn create vite
$ pnpm create vite
$ bun create vite
$ deno init --npm vite
:::
Then follow the prompts!
Watch an interactive lesson on Scrimba
::: tip Compatibility Note
Vite requires Node.js version 20.19+, 22.12+. However, some templates require a higher Node.js version to work, please upgrade if your package manager warns about it.
:::
:::: details Using create vite with command line options
You can also directly specify the project name and the template you want to use via additional command line options. For example, to scaffold a Vite + Vue project, run:
::: code-group
# npm 7+, extra double-dash is needed:
$ npm create vite@latest my-vue-app -- --template vue
$ yarn create vite my-vue-app --template vue
$ pnpm create vite my-vue-app --template vue
$ bun create vite my-vue-app --template vue
$ deno init --npm vite my-vue-app --template vue
:::
See create-vite for more details on each supported template: 
vanilla, 
vanilla-ts, 
vue, 
vue-ts, 
react, 
react-compiler, 
react-ts, 
react-compiler-ts, 
preact, 
preact-ts, 
lit, 
lit-ts, 
svelte, 
svelte-ts, 
solid, 
solid-ts, 
qwik, 
qwik-ts.
You can use 
. for the project name to scaffold in the current directory.
To create a project without interactive prompts, you can use the 
--no-interactive flag.
::::
Community Templates
create-vite is a tool to quickly start a project from a basic template for popular frameworks. Check out Awesome Vite for community maintained templates that include other tools or target different frameworks.
For a template at 
https://github.com/user/project, you can try it out online using 
https://github.stackblitz.com/user/project (adding 
.stackblitz after 
github to the URL of the project).
You can also use a tool like tiged to scaffold your project with one of the templates. Assuming the project is on GitHub and uses 
main as the default branch, you can create a local copy using:
npx tiged user/project my-project
cd my-project
npm install
npm run dev
Manual Installation
In your project, you can install the 
vite CLI using:
::: code-group
$ npm install -D vite
$ yarn add -D vite
$ pnpm add -D vite
$ bun add -D vite
$ deno add -D npm:vite
:::
And create an 
index.html file like this:
<p>Hello Vite!</p>
Then run the appropriate CLI command in your terminal:
::: code-group
$ npx vite
$ yarn vite
$ pnpm vite
$ bunx vite
$ deno run -A npm:vite
:::
The 
index.html will be served on 
http://localhost:5173.
index.html and Project Root
One thing you may have noticed is that in a Vite project, 
index.html is front-and-central instead of being tucked away inside 
public. This is intentional: during development Vite is a server, and 
index.html is the entry point to your application.
Vite treats 
index.html as source code and part of the module graph. It resolves 
<script type="module" src="..."> that references your JavaScript source code. Even inline 
<script type="module"> and CSS referenced via 
<link href> also enjoy Vite-specific features. In addition, URLs inside 
index.html are automatically rebased so there's no need for special 
%PUBLIC_URL% placeholders.
Similar to static http servers, Vite has the concept of a "root directory" which your files are served from. You will see it referenced as 
<root> throughout the rest of the docs. Absolute URLs in your source code will be resolved using the project root as base, so you can write code as if you are working with a normal static file server (except way more powerful!). Vite is also capable of handling dependencies that resolve to out-of-root file system locations, which makes it usable even in a monorepo-based setup.
Vite also supports multi-page apps with multiple 
.html entry points.
Specifying Alternative Root
Running 
vite starts the dev server using the current working directory as root. You can specify an alternative root with 
vite serve some/sub/dir.
Note that Vite will also resolve its config file (i.e. 
vite.config.js) inside the project root, so you'll need to move it if the root is changed.
Command Line Interface
In a project where Vite is installed, you can use the 
vite binary in your npm scripts, or run it directly with 
npx vite. Here are the default npm scripts in a scaffolded Vite project:
{
  "scripts": {
    "dev": "vite", // start dev server, aliases: `vite dev`, `vite serve`
    "build": "vite build", // build for production
    "preview": "vite preview" // locally preview production build
  }
}
You can specify additional CLI options like 
--port or 
--open. For a full list of CLI options, run 
npx vite --help in your project.
Learn more about the Command Line Interface.
Using Unreleased Commits
If you can't wait for a new release to test the latest features, you can install a specific commit of Vite with https://pkg.pr.new:
::: code-group
$ npm install -D https://pkg.pr.new/vite@SHA
$ yarn add -D https://pkg.pr.new/vite@SHA
$ pnpm add -D https://pkg.pr.new/vite@SHA
$ bun add -D https://pkg.pr.new/vite@SHA
:::
Replace 
SHA with any of Vite's commit SHAs. Note that only commits within the last month will work, as older commit releases are purged.
Alternatively, you can also clone the vite repo to your local machine and then build and link it yourself (pnpm is required):
git clone https://github.com/vitejs/vite.git
cd vite
pnpm install
cd packages/vite
pnpm run build
pnpm link # use your preferred package manager for this step
Then go to your Vite based project and run 
pnpm link vite (or the package manager that you used to link 
vite globally). Now restart the development server to ride on the bleeding edge!
To learn more about how and when Vite does releases, check out the Releases documentation.
::: tip Dependencies using Vite
To replace the Vite version used by dependencies transitively, you should use npm overrides or pnpm overrides.
:::
Community
If you have questions or need help, reach out to the community at Discord and GitHub Discussions.

Migration from v7
If you are migrating from 
rolldown-vite, the technical preview release for Rolldown integrated Vite for v6 & v7, only the sections with  in the title are applicable.
Default Browser Target Change 
The default browser values of 
build.target and 
'baseline-widely-available' are updated to newer browser versions:
Chrome 107 → 111
Edge 107 → 111
Firefox 104 → 114
Safari 16.0 → 16.4
These browser versions align with Baseline Widely Available feature sets as of 2026-01-01. In other words, they were all released about two and a half years ago.
Rolldown
Vite 8 uses Rolldown and Oxc based tools instead of esbuild and Rollup.
Gradual Migration
The 
rolldown-vite package implements Vite 7 with Rolldown, without other Vite 8 changes. This can be used as an intermediate step to migrate to Vite 8. See the Rolldown Integration guide in the Vite 7 docs to switch to 
rolldown-vite from Vite 7.
For users migrating from 
rolldown-vite to Vite 8, you can undo the dependency changes in 
package.json and update to Vite 8:
{
  "devDependencies": {
    "vite": "npm:rolldown-vite@7.2.2" // [!code --]
    "vite": "^8.0.0" // [!code ++]
  }
}
Dependency Optimizer Now Uses Rolldown
Rolldown is now used for dependency optimization instead of esbuild. Vite still supports 
optimizeDeps.esbuildOptions for backward compatibility by converting it to 
optimizeDeps.rolldownOptions automatically. 
optimizeDeps.esbuildOptions is now deprecated and will be removed in the future and we encourage you to migrate to 
optimizeDeps.rolldownOptions.
The following options are converted automatically:
esbuildOptions.minify -> 
rolldownOptions.output.minify
esbuildOptions.treeShaking -> 
rolldownOptions.treeshake
esbuildOptions.define -> 
rolldownOptions.transform.define
esbuildOptions.loader -> 
rolldownOptions.moduleTypes
esbuildOptions.preserveSymlinks -> 
!rolldownOptions.resolve.symlinks
esbuildOptions.resolveExtensions -> 
rolldownOptions.resolve.extensions
esbuildOptions.mainFields -> 
rolldownOptions.resolve.mainFields
esbuildOptions.conditions -> 
rolldownOptions.resolve.conditionNames
esbuildOptions.keepNames -> 
rolldownOptions.output.keepNames
esbuildOptions.platform -> 
rolldownOptions.platform
esbuildOptions.plugins -> 
rolldownOptions.plugins (partial support)
You can get the options set by the compatibility layer from the 
configResolved hook:
const plugin = {
  name: 'log-config',
  configResolved(config) {
    console.log('options', config.optimizeDeps.rolldownOptions)
  },
}
JavaScript Transforms by Oxc
Oxc is now used for JavaScript transformation instead of esbuild. Vite still supports the 
esbuild option for backward compatibility by converting it to 
oxc automatically. 
esbuild is now deprecated and will be removed in the future and we encourage you to migrate to 
oxc.
The following options are converted automatically:
esbuild.jsxInject -> 
oxc.jsxInject
esbuild.include -> 
oxc.include
esbuild.exclude -> 
oxc.exclude
esbuild.jsx -> 
oxc.jsx
esbuild.jsx: 'preserve' -> 
oxc.jsx: 'preserve'
esbuild.jsx: 'automatic' -> 
oxc.jsx: { runtime: 'automatic' }
esbuild.jsxImportSource -> 
oxc.jsx.importSource
esbuild.jsx: 'transform' -> 
oxc.jsx: { runtime: 'classic' }
esbuild.jsxFactory -> 
oxc.jsx.pragma
esbuild.jsxFragment -> 
oxc.jsx.pragmaFrag
esbuild.jsxDev -> 
oxc.jsx.development
esbuild.jsxSideEffects -> 
oxc.jsx.pure
esbuild.define -> 
oxc.define
esbuild.banner -> custom plugin using transform hook
esbuild.footer -> custom plugin using transform hook
The 
esbuild.supported option is not supported by Oxc. If you need this option, please see oxc-project/oxc#15373.
You can get the options set by the compatibility layer from the 
configResolved hook:
const plugin = {
  name: 'log-config',
  configResolved(config) {
    console.log('options', config.oxc)
  },
}
Currently, the Oxc transformer does not support lowering native decorators as we are waiting for the specification to progress, see (oxc-project/oxc#9170).
:::: details Workaround for lowering native decorators
You can use Babel or SWC to lower native decorators for the time being.
Using Babel:
::: code-group
$ npm install -D @rolldown/plugin-babel @babel/plugin-proposal-decorators
$ yarn add -D @rolldown/plugin-babel @babel/plugin-proposal-decorators
$ pnpm add -D @rolldown/plugin-babel @babel/plugin-proposal-decorators
$ bun add -D @rolldown/plugin-babel @babel/plugin-proposal-decorators
$ deno add -D npm:@rolldown/plugin-babel npm:@babel/plugin-proposal-decorators
:::
import babel from '@rolldown/plugin-babel'
import { defineConfig } from 'vite'
function decoratorPreset(options: Record<string, unknown>) {
  return {
    preset: () => ({
      plugins: [['@babel/plugin-proposal-decorators', options]],
    }),
    rolldown: {
      // Only run this transform if the file contains a decorator.
      filter: {
        code: '@',
      },
    },
  }
}
export default defineConfig({
  plugins: [babel({ presets: [decoratorPreset({ version: '2023-11' })] })],
})
Using SWC:
::: code-group
$ npm install -D @rollup/plugin-swc @swc/core
$ yarn add -D @rollup/plugin-swc @swc/core
$ pnpm add -D @rollup/plugin-swc @swc/core
$ bun add -D @rollup/plugin-swc @swc/core
$ deno add -D npm:@rollup/plugin-swc npm:@swc/core
:::
import swc from '@rollup/plugin-swc'
import { defineConfig, withFilter } from 'vite'
export default defineConfig({
  // ...
  plugins: [
    withFilter(
      swc({
        swc: {
          jsc: {
            parser: { decorators: true, decoratorsBeforeExport: true },
            transform: { decoratorVersion: '2023-11' },
          },
        },
      }),
      // Only run this transform if the file contains a decorator.
      { transform: { code: '@' } },
    ),
  ],
})
::::
esbuild Fallbacks
esbuild is no longer directly used by Vite and is now an optional dependency. If you are using a plugin that uses the 
transformWithEsbuild function, you need to install 
esbuild as a 
devDependency. The 
transformWithEsbuild function is deprecated and will be removed in the future. We recommend migrating to the new 
transformWithOxc function instead.
JavaScript Minification by Oxc
The Oxc Minifier is now used for JavaScript minification instead of esbuild. You can use the deprecated 
build.minify: 'esbuild' option to switch back to esbuild. This configuration option will be removed in the future and you need install 
esbuild as a 
devDependency as Vite no longer relies on esbuild directly.
If you were using the 
esbuild.minify* options to control minification behavior, you can now use 
build.rolldownOptions.output.minify instead. If you were using the 
esbuild.drop option, you can now use 
build.rolldownOptions.output.minify.compress.drop* options.
Property mangling and its related options (
mangleProps, 
reserveProps, 
mangleQuoted, 
mangleCache) are not supported by Oxc. If you need these options, please see oxc-project/oxc#15375.
esbuild and Oxc Minifier make slightly different assumptions about source code. In case you suspect the minifier is causing breakage in your code, you can compare these assumptions here:
esbuild minify assumptions
Oxc Minifier assumptions
Please report any issues you find related to minification in your JavaScript apps.
CSS Minification by Lightning CSS
Lightning CSS is now used for CSS minification by default. You can use the 
build.cssMinify: 'esbuild' option to switch back to esbuild. Note that you need to install 
esbuild as a 
devDependency.
Lightning CSS supports better syntax lowering and your CSS bundle size might increase slightly.
Consistent CommonJS Interop
The 
default import from a CommonJS (CJS) module is now handled in a consistent way.
If it matches one of the following conditions, the 
default import is the 
module.exports value of the importee CJS module. Otherwise, the 
default import is the 
module.exports.default value of the importee CJS module:
The importer is 
.mjs or 
.mts.
The closest 
package.json for the importer has a 
type field set to 
module.
The 
module.exports.__esModule value of the importee CJS module is not set to 
true.
::: details The previous behavior
In development, if it matches one of the following conditions, the 
default import is the 
module.exports value of the importee CJS module. Otherwise, the 
default import is the 
module.exports.default value of the importee CJS module:
The importer is included in the dependency optimization and 
.mjs or 
.mts.
The importer is included in the dependency optimization and the closest 
package.json for the importer has a 
type field set to 
module.
The 
module.exports.__esModule value of the importee CJS module is not set to 
true.
In build, the conditions were:
The 
module.exports.__esModule value of the importee CJS module is not set to 
true.
default property of 
module.exports does not exist.
(assuming 
build.commonjsOptions.defaultIsModuleExports is not changed from the default 
'auto')
:::
See Rolldown's docs about this problem for more details: Ambiguous 
default import from CJS modules - Bundling CJS | Rolldown.
This change may break some existing code importing CJS modules. You can use the deprecated 
legacy.inconsistentCjsInterop: true option to temporarily restore the previous behavior. If you find a package that is affected by this change, please report it to the package author or send them a pull request. Make sure to link to the Rolldown documentation above so that the author can understand the context.
Removed Module Resolution Using Format Sniffing
When both 
browser and 
module fields are present in 
package.json, Vite used to resolve the field based on the content of the file and it used to pick the ESM file for browsers. This was introduced because some packages were using the 
module field to point to ESM files for Node.js and some other packages were using the 
browser field to point to UMD files for browsers. Given that the modern 
exports field solved this problem and is now adopted by many packages, Vite no longer uses this heuristic and always respects the order of the 
resolve.mainFields option. If you were relying on this behavior, you can use the 
resolve.alias option to map the field to the desired file or apply a patch with your package manager (e.g. 
patch-package, 
pnpm patch).
Require Calls For Externalized Modules
require calls for externalized modules are now preserved as 
require calls and not converted to 
import statements. This is to preserve the semantics of 
require calls. If you want to convert them to 
import statements, you can use Rolldown's built-in 
esmExternalRequirePlugin, which is re-exported from 
vite.
import { defineConfig, esmExternalRequirePlugin } from 'vite'
export default defineConfig({
  // ...
  plugins: [
    esmExternalRequirePlugin({
      external: ['react', 'vue', /^node:/],
    }),
  ],
})
See Rolldown's docs for more details: 
require external modules - Bundling CJS | Rolldown.
import.meta.url in UMD / IIFE
import.meta.url is no longer polyfilled in UMD / IIFE output formats. It will be replaced with 
undefined by default. If you prefer the previous behavior, you can use the 
define option with 
build.rolldownOptions.output.intro option. See Rolldown's docs for more details: Well-known 
import.meta properties - Non ESM Output Formats | Rolldown.
Removed 
build.rollupOptions.watch.chokidar option
The 
build.rollupOptions.watch.chokidar option was removed. Please migrate to the 
build.rolldownOptions.watch.watcher option.
Removed object form 
build.rollupOptions.output.manualChunks and deprecate function form one
The object form 
output.manualChunks option is not supported anymore. The function form 
output.manualChunks is deprecated. Rolldown has the more flexible 
codeSplitting option. See Rolldown's docs for more details about 
codeSplitting: Manual Code Splitting - Rolldown.
build() Throws 
BundleError
This change only affects JS API users.
build() now throws a 
BundleError instead of the raw error thrown in the plugin. 
BundleError is typed as 
Error & { errors?: RolldownError[] } and it wraps the individual errors in an 
errors array. If you need the individual errors, you need to access 
.errors:
try {
  await build()
} catch (e) {
  if (e.errors) {
    for (const error of e.errors) {
      console.log(error.code) // error code
    }
  }
}
Module Type Support and Auto Detection
This change only affects plugin authors.
Rolldown has experimental support for Module types, similar to esbuild's 
loader option. Due to this, Rolldown automatically sets a module type based on the extension of the resolved id. If you are converting content from other module types to JavaScript in 
load or 
transform hooks, you may need to add 
moduleType: 'js' to the returned value:
import fs from 'node:fs'
const plugin = {
  name: 'txt-loader',
  load: {
    filter: { id: /\.txt$/ },
    handler(id) {
      const content = fs.readFileSync(id, 'utf-8')
      return {
        code: `export default ${JSON.stringify(content)}`,
        moduleType: 'js', // [!code ++]
      }
    },
  },
}
Other Related Deprecations
The following options are deprecated and will be removed in the future:
build.rollupOptions: renamed to 
build.rolldownOptions
worker.rollupOptions: renamed to 
worker.rolldownOptions
build.commonjsOptions: it is now no-op
build.dynamicImportVarsOptions.warnOnError: it is now no-op
resolve.alias[].customResolver: Use a custom plugin with 
resolveId hook and 
enforce: 'pre' instead
Removed Deprecated Features 
Passing a URL to 
import.meta.hot.accept is no longer supported. Please pass an id instead. (#21382)
Advanced
These breaking changes are expected to only affect a minority of use cases:
Extglobs are not supported yet (rolldown-vite#365)
TypeScript legacy namespace is only supported partially. See Oxc Transformer's related documentation for more details.
define does not share reference for objects: When you pass an object as a value to 
define, each variable will have a separate copy of the object. See Oxc Transformer's related documentation for more details.
bundle object changes (
bundle is an object passed in 
generateBundle / 
writeBundle hooks, returned by 
build function):
Assigning to 
bundle[foo] is not supported. This is discouraged by Rollup as well. Please use 
this.emitFile() instead.
the reference is not shared across the hooks (rolldown-vite#410)
structuredClone(bundle) errors with 
DataCloneError: #<Object> could not be cloned. This is not supported anymore. Please clone it with 
structuredClone({ ...bundle }). (rolldown-vite#128)
All parallel hooks in Rollup work as sequential hooks. See Rolldown's documentation for more details.
"use strict"; is not injected sometimes. See Rolldown's documentation for more details.
Transforming to ES5 and below with plugin-legacy is not supported (rolldown-vite#452)
Passing the same browser with multiple versions of it to 
build.target option now errors: esbuild selects the latest version of it, which was probably not what you intended.
Missing support by Rolldown: The following features are not supported by Rolldown and are no longer supported by Vite.
build.rollupOptions.output.format: 'system' (rolldown#2387)
build.rollupOptions.output.format: 'amd' (rolldown#2528)
shouldTransformCachedModule hook (rolldown#4389)
resolveImportMeta hook (rolldown#1010)
renderDynamicImport hook (rolldown#4532)
resolveFileUrl hook
parseAst / 
parseAstAsync functions are now deprecated in favor of 
parseSync / 
parse functions which have more features.
comments are removed before the 
renderChunk hook instead of after the 
renderChunk hook
comments other than the ones listed here are moved, while Rollup only removes comments if the adjacent code is removed
Migration from v6
Check the Migration from v6 Guide in the Vite v7 docs first to see the needed changes to port your app to Vite 7, and then proceed with the changes on this page.

Performance
While Vite is fast by default, performance issues can creep in as the project's requirements grow. This guide aims to help you identify and fix common performance issues, such as:
Slow server starts
Slow page loads
Slow builds
Review Your Browser Setup
Some browser extensions may interfere with requests and slow down startup and reload times for large apps, especially when using browser dev tools. We recommend creating a dev-only profile without extensions, or switch to incognito mode, while using Vite's dev server in these cases. Incognito mode should also be faster than a regular profile without extensions.
The Vite dev server does hard caching of pre-bundled dependencies and implements fast 304 responses for source code. Disabling the cache while the Browser Dev Tools are open can have a big impact on startup and full-page reload times. Please check that "Disable Cache" isn't enabled while you work with the Vite server.
Audit Configured Vite Plugins
Vite's internal and official plugins are optimized to do the least amount of work possible while providing compatibility with the broader ecosystem. For example, code transformations use regex in dev, but do a complete parse in build to ensure correctness.
However, the performance of community plugins is out of Vite's control, which may affect the developer experience. Here are a few things you can look out for when using additional Vite plugins:
Large dependencies that are only used in certain cases should be dynamically imported to reduce the Node.js startup time. Example refactors: vite-plugin-react#212 and vite-plugin-pwa#244.
The 
buildStart, 
config, and 
configResolved hooks should not run long and extensive operations. These hooks are awaited during dev server startup, which delays when you can access the site in the browser.
The 
resolveId, 
load, and 
transform hooks may cause some files to load slower than others. While sometimes unavoidable, it's still worth checking for possible areas to optimize. For example, checking if the 
code contains a specific keyword, or the 
id matches a specific extension, before doing the full transformation.
The longer it takes to transform a file, the more significant the request waterfall will be when loading the site in the browser.
You can inspect the duration it takes to transform a file using 
vite --debug plugin-transform or vite-plugin-inspect. Note that as asynchronous operations tend to provide inaccurate timings, you should treat the numbers as a rough estimate, but it should still reveal the more expensive operations.
::: tip Profiling
You can run 
vite --profile, visit the site, and press 
p + enter in your terminal to record a 
.cpuprofile. A tool like speedscope can then be used to inspect the profile and identify the bottlenecks. You can also share the profiles with the Vite team to help us identify performance issues.
:::
Reduce Resolve Operations
Resolving import paths can be an expensive operation when hitting its worst case often. For example, Vite supports "guessing" import paths with the 
resolve.extensions option, which defaults to 
['.mjs', '.js', '.mts', '.ts', '.jsx', '.tsx', '.json'].
When you try to import 
./Component.jsx with 
import './Component', Vite will run these steps to resolve it:
Check if 
./Component exists, no.
Check if 
./Component.mjs exists, no.
Check if 
./Component.js exists, no.
Check if 
./Component.mts exists, no.
Check if 
./Component.ts exists, no.
Check if 
./Component.jsx exists, yes!
As shown, a total of 6 filesystem checks is required to resolve an import path. The more implicit imports you have, the more time it adds up to resolve the paths.
Hence, it's usually better to be explicit with your import paths, e.g. 
import './Component.jsx'. You can also narrow down the list for 
resolve.extensions to reduce the general filesystem checks, but you have to make sure it works for files in 
node_modules too.
If you're a plugin author, make sure to only call 
this.resolve when needed to reduce the number of checks above.
::: tip TypeScript
If you are using TypeScript, enable 
"moduleResolution": "bundler" and 
"allowImportingTsExtensions": true in your 
tsconfig.json's 
compilerOptions to use 
.ts and 
.tsx extensions directly in your code.
:::
Avoid Barrel Files
Barrel files are files that re-export the APIs of other files in the same directory. For example:
export * from './color.js'
export * from './dom.js'
export * from './slash.js'
When you only import an individual API, e.g. 
import { slash } from './utils', all the files in that barrel file need to be fetched and transformed as they may contain the 
slash API and may also contain side-effects that run on initialization. This means you're loading more files than required on the initial page load, resulting in a slower page load.
If possible, you should avoid barrel files and import the individual APIs directly, e.g. 
import { slash } from './utils/slash.js'. You can read issue #8237 for more information.
Warm Up Frequently Used Files
The Vite dev server only transforms files as requested by the browser, which allows it to start up quickly and only apply transformations for used files. It can also pre-transform files if it anticipates certain files will be requested shortly. However, request waterfalls may still happen if some files take longer to transform than others. For example:
Given an import graph where the left file imports the right file:
main.js -> BigComponent.vue -> big-utils.js -> large-data.json
The import relationship can only be known after the file is transformed. If 
BigComponent.vue takes some time to transform, 
big-utils.js has to wait for its turn, and so on. This causes an internal waterfall even with pre-transformation built-in.
Vite allows you to warm up files that you know are frequently used, e.g. 
big-utils.js, using the 
server.warmup option. This way 
big-utils.js will be ready and cached to be served immediately when requested.
You can find files that are frequently used by running 
vite --debug transform and inspect the logs:
vite:transform 28.72ms /@vite/client +1ms
vite:transform 62.95ms /src/components/BigComponent.vue +1ms
vite:transform 102.54ms /src/utils/big-utils.js +1ms
export default defineConfig({
  server: {
    warmup: {
      clientFiles: [
        './src/components/BigComponent.vue',
        './src/utils/big-utils.js',
      ],
    },
  },
})
Note that you should only warm up files that are frequently used to not overload the Vite dev server on startup. Check the 
server.warmup option for more information.
Using 
--open or 
server.open also provides a performance boost, as Vite will automatically warm up the entry point of your app or the provided URL to open.
Use Lesser or Native Tooling
Keeping Vite fast with a growing codebase is about reducing the amount of work for the source files (JS/TS/CSS).
Examples of doing less work:
Use CSS instead of Sass/Less/Stylus when possible (nesting can be handled by PostCSS / Lightning CSS)
Don't transform SVGs into UI framework components (React, Vue, etc.). Import them as strings or URLs instead.
Examples of using native tooling:
While Vite core is based on native tooling, some features still use non-native tooling by default to provide better compatibility and feature set. But it may be worth the cost for larger applications.
Try out the experimental support for LightningCSS

Project Philosophy
Lean Extendable Core
Vite aims to support the most common patterns to build Web apps out-of-the-box, while keeping Vite core lean and maintainable long-term. We believe the best way to support diverse use cases is to provide strong primitives and APIs that plugins can build on, and we actively expand the core to make Vite more extensible. Vite's plugin system is based on a superset of Rollup's plugin API, and it enables plugins like vite-plugin-pwa and the many well maintained plugins available to cover your needs. Vite's bundler, Rolldown, maintains compatibility with Rollup's plugin interface, so plugins can often be used across both Vite and plain Rollup projects.
Pushing the Modern Web
Vite provides opinionated features that push writing modern code. For example:
The source code can only be written in ESM, where non-ESM dependencies need to be pre-bundled as ESM in order to work.
Web workers are encouraged to be written with the 
new Worker syntax to follow modern standards.
Node.js modules cannot be used in the browser.
When adding new features, these patterns are followed to create a future-proof API, which may not always be compatible with other build tools.
A Pragmatic Approach to Performance
Vite has been focused on performance since its origins. Its dev server architecture allows HMR that stays fast as projects scale. Vite is based on native tools that include the Oxc toolchain and Rolldown to implement intensive tasks but keeps the rest of the code in JS to balance speed with flexibility. When needed, framework plugins will tap into Babel to compile user code. Thanks to Rolldown's Rollup plugin compatibility, Vite has access to a wide ecosystem of plugins.
Building Frameworks on Top of Vite
Although Vite can be used by users directly, it shines as a tool to create frameworks. Vite core is framework agnostic, but there are polished plugins for each UI framework. Its JS API allows App Framework authors to use Vite features to create tailored experiences for their users. Vite includes support for SSR primitives, usually present in higher-level tools but fundamental to building modern web frameworks. And Vite plugins complete the picture by offering a way to share between frameworks. Vite is also a great fit when paired with Backend frameworks like Ruby and Laravel.
An Active Ecosystem
Vite evolution is a cooperation between framework and plugin maintainers, users, and the Vite team. We encourage active participation in Vite's Core development once a project adopts Vite. We work closely with the main projects in the ecosystem to minimize regressions on each release, aided by tools like vite-ecosystem-ci. It allows us to run the CI of major projects using Vite on selected PRs and gives us a clear status of how the Ecosystem would react to a release. We strive to fix regressions before they hit users and allow projects to update to the next versions as soon as they are released. If you are working with Vite, we invite you to join Vite's Discord and get involved in the project too.

Server-Side Rendering (SSR)
:::tip Note
SSR specifically refers to front-end frameworks (for example React, Preact, Vue, and Svelte) that support running the same application in Node.js, pre-rendering it to HTML, and finally hydrating it on the client. If you are looking for integration with traditional server-side frameworks, check out the Backend Integration guide instead.
The following guide also assumes prior experience working with SSR in your framework of choice, and will only focus on Vite-specific integration details.
:::
:::warning Low-level API
This is a low-level API meant for library and framework authors. If your goal is to create an application, make sure to check out the higher-level SSR plugins and tools at Awesome Vite SSR section first. That said, many applications are successfully built directly on top of Vite's native low-level API.
Currently, Vite is working on an improved SSR API with the Environment API. Check out the link for more details.
:::
Example Projects
Vite provides built-in support for server-side rendering (SSR). 
create-vite-extra contains example SSR setups you can use as references for this guide:
Vanilla
Vue
React
Preact
Svelte
Solid
You can also scaffold these projects locally by running 
create-vite and choose 
Others > create-vite-extra under the framework option.
Source Structure
A typical SSR application will have the following source file structure:
- index.html
- server.js # main application server
- src/
  - main.js          # exports env-agnostic (universal) app code
  - entry-client.js  # mounts the app to a DOM element
  - entry-server.js  # renders the app using the framework's SSR API
The 
index.html will need to reference 
entry-client.js and include a placeholder where the server-rendered markup should be injected:
<div id="app"><!--ssr-outlet--></div>
<script type="module" src="/src/entry-client.js"></script>
You can use any placeholder you prefer instead of 
<!--ssr-outlet-->, as long as it can be precisely replaced.
Conditional Logic
If you need to perform conditional logic based on SSR vs. client, you can use
import 'vite/client'
// ---cut---
if (import.meta.env.SSR) {
  // ... server only logic
}
This is statically replaced during build so it will allow tree-shaking of unused branches.
Setting Up the Dev Server
When building an SSR app, you likely want to have full control over your main server and decouple Vite from the production environment. It is therefore recommended to use Vite in middleware mode. Here is an example with express:
import fs from 'node:fs'
import path from 'node:path'
import express from 'express'
import { createServer as createViteServer } from 'vite'
async function createServer() {
  const app = express()
  // Create Vite server in middleware mode and configure the app type as
  // 'custom', disabling Vite's own HTML serving logic so parent server
  // can take control
  const vite = await createViteServer({
    server: { middlewareMode: true },
    appType: 'custom'
  })
  // Use vite's connect instance as middleware. If you use your own
  // express router (express.Router()), you should use router.use
  // When the server restarts (for example after the user modifies
  // vite.config.js), `vite.middlewares` is still going to be the same
  // reference (with a new internal stack of Vite and plugin-injected
  // middlewares). The following is valid even after restarts.
  app.use(vite.middlewares)
  app.use('*all', async (req, res) => {
    // serve index.html - we will tackle this next
  })
  app.listen(5173)
}
createServer()
Here 
vite is an instance of ViteDevServer. 
vite.middlewares is a Connect instance which can be used as a middleware in any connect-compatible Node.js framework.
::: tip SSR-only module updates
By default, updating a module that is only imported by the SSR environment does not reload the page in the browser. Framework integrations usually handle this for you. For a low-level custom SSR setup, you can add a plugin that reloads the browser when an SSR-only module changes:
import type { EnvironmentModuleNode, Plugin } from 'vite'
export function ssrReload(): Plugin {
  return {
    name: 'ssr-reload',
    enforce: 'post',
    hotUpdate: {
      order: 'post',
      handler({ modules, server, timestamp }) {
        if (this.environment.name !== 'ssr') return
        const invalidatedModules = new Set<EnvironmentModuleNode>()
        let hasSsrOnlyModules = false
        for (const mod of modules) {
          if (mod.file == null) continue
          const clientModules =
            server.environments.client.moduleGraph.getModulesByFile(mod.file)
          if (clientModules != null) continue
          this.environment.moduleGraph.invalidateModule(
            mod,
            invalidatedModules,
            timestamp,
            true,
          )
          hasSsrOnlyModules = true
        }
        if (hasSsrOnlyModules) {
          server.environments.client.hot.send({ type: 'full-reload' })
          return []
        }
      },
    },
  }
}
Add 
ssrReload() to the 
plugins array passed to 
createViteServer in the example above. See the 
hotUpdate hook for details.
:::
The next step is implementing the 
* handler to serve server-rendered HTML:
// @noErrors
import fs from 'node:fs'
import path from 'node:path'
/** @type {import('express').Express} */
var app
/** @type {import('vite').ViteDevServer}  */
var vite
// ---cut---
app.use('*all', async (req, res, next) => {
  const url = req.originalUrl
  try {
    // 1. Read index.html
    let template = fs.readFileSync(
      path.resolve(import.meta.dirname, 'index.html'),
      'utf-8',
    )
    // 2. Apply Vite HTML transforms. This injects the Vite HMR client,
    //    and also applies HTML transforms from Vite plugins, e.g. global
    //    preambles from @vitejs/plugin-react
    template = await vite.transformIndexHtml(url, template)
    // 3. Load the server entry. ssrLoadModule automatically transforms
    //    ESM source code to be usable in Node.js! There is no bundling
    //    required, and provides efficient invalidation similar to HMR.
    const { render } = await vite.ssrLoadModule('/src/entry-server.js')
    // 4. render the app HTML. This assumes entry-server.js's exported
    //     `render` function calls appropriate framework SSR APIs,
    //    e.g. ReactDOMServer.renderToString()
    const appHtml = await render(url)
    // 5. Inject the app-rendered HTML into the template.
    const html = template.replace(`<!--ssr-outlet-->`, () => appHtml)
    // 6. Send the rendered HTML back.
    res.status(200).set({ 'Content-Type': 'text/html' }).end(html)
  } catch (e) {
    // If an error is caught, let Vite fix the stack trace so it maps back
    // to your actual source code.
    vite.ssrFixStacktrace(e)
    next(e)
  }
})
The 
dev script in 
package.json should also be changed to use the server script instead:
  "scripts": {
-   "dev": "vite"
+   "dev": "node server"
  }
Building for Production
To ship an SSR project for production, we need to:
Produce a client build as normal;
Produce an SSR build, which can be directly loaded via 
import() so that we don't have to go through Vite's 
ssrLoadModule;
Our scripts in 
package.json will look like this:
{
  "scripts": {
    "dev": "node server",
    "build:client": "vite build --outDir dist/client",
    "build:server": "vite build --outDir dist/server --ssr src/entry-server.js"
  }
}
Note the 
--ssr flag which indicates this is an SSR build. It should also specify the SSR entry.
Then, in 
server.js we need to add some production specific logic by checking 
process.env.NODE_ENV:
Instead of reading the root 
index.html, use the 
dist/client/index.html as the template, since it contains the correct asset links to the client build.
Instead of 
await vite.ssrLoadModule('/src/entry-server.js'), use 
import('./dist/server/entry-server.js') (this file is the result of the SSR build).
Move the creation and all usage of the 
vite dev server behind dev-only conditional branches, then add static file serving middlewares to serve files from 
dist/client.
Refer to the example projects for a working setup.
Generating Preload Directives
vite build supports the 
--ssrManifest flag which will generate 
.vite/ssr-manifest.json in build output directory:
- "build:client": "vite build --outDir dist/client",
+ "build:client": "vite build --outDir dist/client --ssrManifest",
The above script will now generate 
dist/client/.vite/ssr-manifest.json for the client build (Yes, the SSR manifest is generated from the client build because we want to map module IDs to client files). The manifest contains mappings of module IDs to their associated chunks and asset files.
To leverage the manifest, frameworks need to provide a way to collect the module IDs of the components that were used during a server render call.
@vitejs/plugin-vue supports this out of the box and automatically registers used component module IDs on to the associated Vue SSR context:
const ctx = {}
const html = await vueServerRenderer.renderToString(app, ctx)
// ctx.modules is now a Set of module IDs that were used during the render
In the production branch of 
server.js we need to read and pass the manifest to the 
render function exported by 
src/entry-server.js. This would provide us with enough information to render preload directives for files used by async routes! See demo source for a full example. You can also use this information for 103 Early Hints.
Pre-Rendering / SSG
If the routes and the data needed for certain routes are known ahead of time, we can pre-render these routes into static HTML using the same logic as production SSR. This can also be considered a form of Static-Site Generation (SSG). See demo pre-render script for working example.
SSR Externals
Dependencies are "externalized" from Vite's SSR transform module system by default when running SSR. This speeds up both dev and build.
If a dependency needs to be transformed by Vite's pipeline, for example, because Vite features are used untranspiled in them, they can be added to 
ssr.noExternal.
For linked dependencies, they are not externalized by default to take advantage of Vite's HMR. If this isn't desired, for example, to test dependencies as if they aren't linked, you can add it to 
ssr.external.
:::warning Working with Aliases
If you have configured aliases that redirect one package to another, you may want to alias the actual 
node_modules packages instead to make it work for SSR externalized dependencies. Both Yarn and pnpm support aliasing via the 
npm: prefix.
:::
SSR-specific Plugin Logic
Some frameworks such as Vue or Svelte compile components into different formats based on client vs. SSR. To support conditional transforms, Vite passes an additional 
ssr property in the 
options object of the following plugin hooks:
resolveId
load
transform
Example:
/** @type {() => import('vite').Plugin} */
// ---cut---
export function mySSRPlugin() {
  return {
    name: 'my-ssr',
    transform(code, id, options) {
      if (options?.ssr) {
        // perform ssr-specific transform...
      }
    },
  }
}
The options object in 
load and 
transform is optional, Rollup is not currently using this object but may extend these hooks with additional metadata in the future.
:::tip Note
Before Vite 2.7, this was informed to plugin hooks with a positional 
ssr param instead of using the 
options object. All major frameworks and plugins are updated but you may find outdated posts using the previous API.
:::
SSR Target
The default target for the SSR build is a node environment, but you can also run the server in a Web Worker. Packages entry resolution is different for each platform. You can configure the target to be Web Worker using the 
ssr.target set to 
'webworker'.
SSR Bundle
In some cases like 
webworker runtimes, you might want to bundle your SSR build into a single JavaScript file. You can enable this behavior by setting 
ssr.noExternal to 
true. This will do two things:
Treat all dependencies as 
noExternal
Throw an error if any Node.js built-ins are imported
SSR Resolve Conditions
By default package entry resolution will use the conditions set in 
resolve.conditions for the SSR build. You can use 
ssr.resolve.conditions and 
ssr.resolve.externalConditions to customize this behavior.
Vite CLI
The CLI commands 
$ vite dev and 
$ vite preview can also be used for SSR apps. You can add your SSR middlewares to the development server with 
configureServer and to the preview server with 
configurePreviewServer.
:::tip Note
Use a post hook so that your SSR middleware runs after Vite's middlewares.
:::

static-deploy
Deploying a Static Site
The following guides are based on some shared assumptions:
You are using the default build output location (
dist). This location can be changed using 
build.outDir, and you can extrapolate instructions from these guides in that case.
You are using npm. You can use equivalent commands to run the scripts if you are using Yarn or other package managers.
Vite is installed as a local dev dependency in your project, and you have setup the following npm scripts:
{
  "scripts": {
    "build": "vite build",
    "preview": "vite preview"
  }
}
It is important to note that 
vite preview is intended for previewing the build locally and not meant as a production server.
::: tip NOTE
These guides provide instructions for performing a static deployment of your Vite site. Vite also supports Server-Side Rendering. SSR refers to front-end frameworks that support running the same application in Node.js, pre-rendering it to HTML, and finally hydrating it on the client. Check out the SSR Guide to learn about this feature. On the other hand, if you are looking for integration with traditional server-side frameworks, check out the Backend Integration guide instead.
:::
Building the App
You may run 
npm run build command to build the app.
$ npm run build
By default, the build output will be placed at 
dist. You may deploy this 
dist folder to any of your preferred platforms.
Testing the App Locally
Once you've built the app, you may test it locally by running 
npm run preview command.
$ npm run preview
The 
vite preview command will boot up a local static web server that serves the files from 
dist at 
http://localhost:4173. It's an easy way to check if the production build looks OK in your local environment.
You may configure the port of the server by passing the 
--port flag as an argument.
{
  "scripts": {
    "preview": "vite preview --port 8080"
  }
}
Now the 
preview command will launch the server at 
http://localhost:8080.
GitHub Pages
Update Vite Config
Set the correct 
base in 
vite.config.js.
If you are deploying to 
https://<USERNAME>.github.io/, or to a custom domain through GitHub Pages (eg. 
www.example.com), set 
base to 
'/'. Alternatively, you can remove 
base from the configuration, as it defaults to 
'/'.
If you are deploying to 
https://<USERNAME>.github.io/<REPO>/ (eg. your repository is at 
https://github.com/<USERNAME>/<REPO>), then set 
base to 
'/<REPO>/'.
Enable GitHub Pages
In your repository, go to Settings → Pages. Under Build and deployment, open the Source dropdown, and select GitHub Actions.
GitHub will now deploy your site using a GitHub Actions workflow, which is necessary since Vite requires a build step for deployment.
Create a Workflow
Create a new file in your repository at 
.github/workflows/deploy.yml. You can also click on “create your own” from the previous step, which will generate a starter workflow file for you.
Here’s a sample workflow that installs dependencies with npm, builds the site, and deploys it whenever you push changes to the 
main branch:
<<< ./static-deploy-github-pages.yaml#content [.github/workflows/deploy.yml]
GitLab Pages and GitLab CI
Set the correct 
base in 
vite.config.js.
If you are deploying to 
https://<USERNAME or GROUP>.gitlab.io/, you can omit 
base as it defaults to 
'/'.
If you are deploying to 
https://<USERNAME or GROUP>.gitlab.io/<REPO>/, for example your repository is at 
https://gitlab.com/<USERNAME>/<REPO>, then set 
base to 
'/<REPO>/'.
Create a file called 
.gitlab-ci.yml in the root of your project with the content below. This will build and deploy your site whenever you make changes to your content:
image: node:lts
pages:
  stage: deploy
  cache:
    key:
      files:
        - package-lock.json
      prefix: npm
    paths:
      - node_modules/
  script:
    - npm install
    - npm run build
    - cp -a dist/. public/
  artifacts:
    paths:
      - public
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
Netlify
Netlify CLI
Install the Netlify CLI via 
npm install -g netlify-cli.
Create a new site using 
netlify init.
Deploy using 
netlify deploy.
The Netlify CLI will share with you a preview URL to inspect. When you are ready to go into production, use the 
prod flag: 
netlify deploy --prod.
Netlify with Git
Push your code to a git repository (GitHub, GitLab, BitBucket, Azure DevOps).
Import the project to Netlify.
Choose the branch, output directory, and set up environment variables if applicable.
Click on Deploy.
Your Vite app is deployed!
After your project has been imported and deployed, all subsequent pushes to branches other than the production branch along with pull requests will generate Preview Deployments, and all changes made to the Production Branch (commonly “main”) will result in a Production Deployment.
Vercel
Vercel CLI
Install the Vercel CLI via 
npm i -g vercel and run 
vercel to deploy.
Vercel will detect that you are using Vite and will enable the correct settings for your deployment.
Your application is deployed! (e.g. vite-vue-template.vercel.app)
Vercel with Git
Push your code to your git repository (GitHub, GitLab, Bitbucket).
Import your Vite project into Vercel.
Vercel will detect that you are using Vite and will enable the correct settings for your deployment.
Your application is deployed! (e.g. vite-vue-template.vercel.app)
After your project has been imported and deployed, all subsequent pushes to branches will generate Preview Deployments, and all changes made to the Production Branch (commonly “main”) will result in a Production Deployment.
Learn more about Vercel’s Git Integration.
Cloudflare
Cloudflare Workers
The Cloudflare Vite plugin provides integration with Cloudflare Workers and uses Vite's Environment API to run your server-side code in the Cloudflare Workers runtime during development.
To add Cloudflare Workers to an existing Vite project, install the plugin and add it to your config:
$ npm install --save-dev @cloudflare/vite-plugin
import { cloudflare } from '@cloudflare/vite-plugin'
import { defineConfig } from 'vite'
export default defineConfig({
  plugins: [cloudflare()],
})
{
  "name": "my-vite-app",
}
After running 
npm run build, your application can now be deployed with 
npx wrangler deploy.
You can also easily add backend APIs to your Vite application to securely communicate with Cloudflare resources. This runs in the Workers runtime during development and deploys alongside your frontend. See the Cloudflare Vite plugin tutorial for a complete walkthrough.
Cloudflare Pages
Cloudflare Pages with Git
Cloudflare Pages gives you a way to deploy directly to Cloudflare without having to manage a Wrangler file.
Push your code to your git repository (GitHub, GitLab).
Log in to the Cloudflare dashboard and select your account in Account Home > Workers & Pages.
Select Create a new Project and the Pages option, then select Git.
Select the git project you want to deploy and click Begin setup
Select the corresponding framework preset in the build setting depending on the Vite framework you have selected. Otherwise enter your build commands for your project and your expected output directory.
Then save and deploy!
Your application is deployed! (e.g 
https://<PROJECTNAME>.pages.dev/)
After your project has been imported and deployed, all subsequent pushes to branches will generate Preview Deployments unless specified not to in your branch build controls. All changes to the Production Branch (commonly "main") will result in a Production Deployment.
You can also add custom domains and handle custom build settings on Pages. Learn more about Cloudflare Pages Git Integration.
Google Firebase
Install firebase-tools via 
npm i -g firebase-tools.
Create the following files at the root of your project:
::: code-group
{
  "hosting": {
    "public": "dist",
    "ignore": [],
    "rewrites": [
      {
        "source": "**",
        "destination": "/index.html"
      }
    ]
  }
}
{
  "projects": {
    "default": "<YOUR_FIREBASE_ID>"
  }
}
:::
After running 
npm run build, deploy using the command 
firebase deploy.
Surge
Install surge via 
npm i -g surge.
Run 
npm run build.
Deploy to surge by typing 
surge dist.
You can also deploy to a custom domain by adding 
surge dist yourdomain.com.
Azure Static Web Apps
You can quickly deploy your Vite app with Microsoft Azure Static Web Apps service. You need:
An Azure account and a subscription key. You can create a free Azure account here.
Your app code pushed to GitHub.
The SWA Extension in Visual Studio Code.
Install the extension in VS Code and navigate to your app root. Open the Static Web Apps extension, sign in to Azure, and click the '+' sign to create a new Static Web App. You will be prompted to designate which subscription key to use.
Follow the wizard started by the extension to give your app a name, choose a framework preset, and designate the app root (usually 
/) and built file location 
/dist. The wizard will run and will create a GitHub action in your repo in a 
.github folder.
The action will work to deploy your app (watch its progress in your repo's Actions tab) and, when successfully completed, you can view your app in the address provided in the extension's progress window by clicking the 'Browse Website' button that appears when the GitHub action has run.
Render
You can deploy your Vite app as a Static Site on Render.
Create a Render account.
In the Dashboard, click the New button and select Static Site.
Connect your GitHub/GitLab account or use a public repository.
Specify a project name and branch.
Build Command: 
npm install && npm run build
Publish Directory: 
dist
Click Create Static Site. Your app should be deployed at 
https://<PROJECTNAME>.onrender.com/.
By default, any new commit pushed to the specified branch will automatically trigger a new deployment. Auto-Deploy can be configured in the project settings.
You can also add a custom domain to your project.
Flightcontrol
Deploy your static site using Flightcontrol by following these instructions.
xmit Static Site Hosting
Deploy your static site using xmit by following this guide.
Zephyr Cloud
Zephyr Cloud is a deployment platform that integrates directly into your build process and provides global edge distribution for module federation and other kind of applications.
Zephyr follows a different approach than other cloud providers. It integrates directly with Vite build process, so every time you build or run the dev server for your application, it will be automatically deployed with Zephyr Cloud.
Follow the steps in the Vite deployment guide to get started.
EdgeOne Pages
Deploy your static site using EdgeOne Pages by following these instructions.

Troubleshooting
See Rollup's troubleshooting guide for more information too.
If the suggestions here don't work, please try posting questions on GitHub Discussions or in the 
#help channel of Vite Land Discord.
CLI
Error: Cannot find module 'C:\foo\bar&baz\vite\bin\vite.js'
The path to your project folder may include 
&, which doesn't work with 
npm on Windows (npm/cmd-shim#45).
You will need to either:
Switch to another package manager (e.g. 
pnpm, 
yarn)
Remove 
& from the path to your project
Config
This package is ESM only
When importing an ESM only package by 
require, the following error happens.
Failed to resolve "foo". This package is ESM only but it was tried to load by 
require.
Error [ERR_REQUIRE_ESM]: require() of ES Module /path/to/dependency.js from /path/to/vite.config.js not supported.
Instead change the require of index.js in /path/to/vite.config.js to a dynamic import() which is available in all CommonJS modules.
In Node.js <=22, ESM files cannot be loaded by 
require by default.
While it may work using 
--experimental-require-module, or Node.js >22, or in other runtimes, we still recommend converting your config to ESM by either:
adding 
"type": "module" to the nearest 
package.json
renaming 
vite.config.js/
vite.config.ts to 
vite.config.mjs/
vite.config.mts
Dev Server
Requests are stalled forever
If you are using Linux, file descriptor limits and inotify limits may be causing the issue. As Vite does not bundle most of the files, browsers may request many files which require many file descriptors, going over the limit.
To solve this:
Increase file descriptor limit by 
ulimit
# Check current limit
$ ulimit -Sn
# Change limit (temporary)
$ ulimit -Sn 10000 # You might need to change the hard limit too
# Restart your browser
Increase the following inotify related limits by 
sysctl
# Check current limits
$ sysctl fs.inotify
# Change limits (temporary)
$ sudo sysctl fs.inotify.max_queued_events=16384
$ sudo sysctl fs.inotify.max_user_instances=8192
$ sudo sysctl fs.inotify.max_user_watches=524288
If the above steps don't work, you can try adding 
DefaultLimitNOFILE=65536 as an un-commented config to the following files:
/etc/systemd/system.conf
/etc/systemd/user.conf
For Ubuntu Linux, you may need to add the line 
* - nofile 65536 to the file 
/etc/security/limits.conf instead of updating systemd config files.
Note that these settings persist but a restart is required.
Alternatively, if the server is running inside a VS Code devcontainer, the request may appear to be stalled. To fix this issue, see
Dev Containers / VS Code Port Forwarding.
Vite crashes with ENOSPC error
If you see an error like this on Linux:
Error: ENOSPC: System limit for number of file watchers reached
This happens when you have too many files in your project directory (e.g., many images or assets) and exceed the system's file watcher limit. Linux has a default limit of around 8,192-10,000 file watchers.
To solve this, you can:
Increase the system file watcher limit:
# Check current limit
$ cat /proc/sys/fs/inotify/max_user_watches
# Increase limit (temporary)
$ sudo sysctl fs.inotify.max_user_watches=524288
# Make it permanent - add to /etc/sysctl.conf (or edit if it already exists)
$ echo "fs.inotify.max_user_watches=524288" | sudo tee -a /etc/sysctl.conf
$ sudo sysctl -p
Exclude directories with many files from file watching using 
server.watch.ignored
Use polling instead of file system events with 
server.watch.usePolling. Note that polling uses more CPU resources
Network requests stop loading
When using a self-signed SSL certificate, Chrome ignores all caching directives and reloads the content. Vite relies on these caching directives.
To resolve the problem use a trusted SSL cert.
See: Chrome issue
macOS
You can install a trusted cert via the CLI with this command:
security add-trusted-cert -d -r trustRoot -k ~/Library/Keychains/login.keychain-db your-cert.cer
Or, by importing it into the Keychain Access app and updating the trust of your cert to "Always Trust."
431 Request Header Fields Too Large
When the server / WebSocket server receives a large HTTP header, the request will be dropped and the following warning will be shown.
Server responded with status code 431. See https://vite.dev/guide/troubleshooting.html#_431-request-header-fields-too-large.
This is because Node.js limits request header size to mitigate CVE-2018-12121.
To avoid this, try to reduce your request header size. For example, if the cookie is long, delete it. Or you can use 
--max-http-header-size to change max header size.
Dev Containers / VS Code Port Forwarding
If you are using a Dev Container or port forwarding feature in VS Code, you may need to set the 
server.host option to 
127.0.0.1 in the config to make it work.
This is because the port forwarding feature in VS Code does not support IPv6.
See #16522 for more details.
Illegal operation error when watching files
If the file or directory is located on a file system that does not support file system events, Vite may be unable to watch it.
An example error you may encounter is:
Error: EISDIR: illegal operation on a directory, watch 'C:/Users/me/project/vite.config.js'
For example, this can happen with a VirtualBox shared folder.
To solve this, you can enable 
server.watch.usePolling. Note that 
usePolling leads to high CPU utilization.
HMR
Vite detects a file change but the HMR is not working
You may be importing a file with a different case. For example, 
src/foo.js exists and 
src/bar.js contains:
import './Foo.js' // should be './foo.js'
Related issue: #964
Vite does not detect a file change
If you are running Vite with WSL2, Vite cannot watch file changes in some conditions. See 
server.watch option.
A full reload happens instead of HMR
If HMR is not handled by Vite or a plugin, a full reload will happen as it's the only way to refresh the state.
If HMR is handled but it is within a circular dependency, a full reload will also happen to recover the execution order. To solve this, try breaking the loop. You can run 
vite --debug hmr to log the circular dependency path if a file change triggered it.
Build
Built file does not work because of CORS error
If the HTML file output was opened with 
file protocol, the scripts won't run with the following error.
Access to script at 'file:///foo/bar.js' from origin 'null' has been blocked by CORS policy: Cross origin requests are only supported for protocol schemes: http, data, isolated-app, chrome-extension, chrome, https, chrome-untrusted.
Cross-Origin Request Blocked: The Same Origin Policy disallows reading the remote resource at file:///foo/bar.js. (Reason: CORS request not http).
See Reason: CORS request not HTTP - HTTP | MDN for more information about why this happens.
You will need to access the file with 
http protocol. The easiest way to achieve this is to run 
npx vite preview.
No such file or directory error due to case sensitivity
If you encounter errors like 
ENOENT: no such file or directory or 
Module not found, this often occurs when your project was developed on a case-insensitive filesystem (Windows / macOS) but built on a case-sensitive one (Linux). Please make sure that the imports have the correct casing.
Failed to fetch dynamically imported module error
TypeError: Failed to fetch dynamically imported module
This error occurs in several cases:
Version skew
Poor network conditions
Browser extensions blocking requests
Version skew
When you deploy a new version of your application, the HTML file and the JS files still reference old chunk names that were deleted in the new deployment. This happens when:
Users have an old version of your app cached in their browser
You deploy a new version with different chunk names (due to code changes)
The cached HTML tries to load chunks that no longer exist
If you are using a framework, refer to their documentation first as it may have a built-in solution for this problem.
To resolve this, you can:
Keep old chunks temporarily: Consider keeping the previous deployment's chunks for a period to allow cached users to transition smoothly.
Use a service worker: Implement a service worker that will prefetch all the assets and cache them.
Prefetch the dynamic chunks: Note that this does not help if your HTML file is cached by the browser due to 
Cache-Control headers.
Implement a graceful fallback: Implement error handling for dynamic imports to reload the page when chunks are missing. See Load Error Handling for more details.
Poor network conditions
This error may occur in unstable network environments. For example, when the request fails due to network errors or server downtime.
Browsers that support retriable module loading do not cache network and HTTP errors in the module map. In these browsers, your application or framework can retry the original dynamic import. Older browsers cache the failure, so reloading the page remains the fallback.
Retrying also does not fix version skew when a chunk has been permanently removed by a deployment.
Browser extensions blocking requests
The error may also occur if the browser extensions (like ad-blockers) are blocking that request.
It might be possible to work around by selecting a different chunk name by 
build.rolldownOptions.output.chunkFileNames, as these extensions often block requests based on file names (e.g. names containing 
ad, 
track).
Optimized Dependencies
Outdated pre-bundled deps when linking to a local package
The hash key used to invalidate optimized dependencies depends on the package lock contents, the patches applied to dependencies, and the options in the Vite config file that affects the bundling of node modules. This means that Vite will detect when a dependency is overridden using a feature as npm overrides, and re-bundle your dependencies on the next server start. Vite won't invalidate the dependencies when you use a feature like npm link. In case you link or unlink a dependency, you'll need to force re-optimization on the next server start by using 
vite --force. We recommend using overrides instead, which are supported now by every package manager (see also pnpm overrides and yarn resolutions).
Performance Bottlenecks
If you suffer any application performance bottlenecks resulting in slow load times, you can start the built-in Node.js inspector with your Vite dev server or when building your application to create the CPU profile:
::: code-group
vite --profile --open
vite build --profile
:::
::: tip Vite Dev Server
Once your application is opened in the browser, just await finish loading it and then go back to the terminal and press 
p key (will stop the Node.js inspector) then press 
q key to stop the dev server.
:::
Node.js inspector will generate 
vite-profile-0.cpuprofile in the root folder. You can pass 
--profile <name> (or 
--profile=<name>) to write 
<name>.cpuprofile instead. Go to https://www.speedscope.app/, and upload the CPU profile using the 
BROWSE button to inspect the result.
You can install vite-plugin-inspect, which lets you inspect the intermediate state of Vite plugins and can also help you to identify which plugins or middlewares are the bottleneck in your applications. The plugin can be used in both dev and build modes. Check the readme file for more details.
Others
Module externalized for browser compatibility
When you use a Node.js module in the browser, Vite will output the following warning.
Module "fs" has been externalized for browser compatibility. Cannot access "fs.readFile" in client code.
This is because Vite does not automatically polyfill Node.js modules.
We recommend avoiding Node.js modules for browser code to reduce the bundle size, although you can add polyfills manually. If the module is imported from a third-party library (that's meant to be used in the browser), it's advised to report the issue to the respective library.
Syntax Error / Type Error happens
Vite cannot handle and does not support code that only runs on non-strict mode (sloppy mode). This is because Vite uses ESM and it is always strict mode inside ESM.
For example, you might see these errors.
[ERROR] With statements cannot be used with the "esm" output format due to strict mode
TypeError: Cannot create property 'foo' on boolean 'false'
If these codes are used inside dependencies, you could use 
patch-package (or 
yarn patch or 
pnpm patch) for an escape hatch.
Browser extensions
Some browser extensions (like ad-blockers) may prevent the Vite client from sending requests to the Vite dev server. You may see a white screen without logged errors in this case. You may also see the following error:
TypeError: Failed to fetch dynamically imported module
Try disabling extensions if you have this issue.
Cross drive links on Windows
If there's a cross drive links in your project on Windows, Vite may not work.
An example of cross drive links are:
a virtual drive linked to a folder by 
subst command
a symlink/junction to a different drive by 
mklink command (e.g. Yarn global cache)
Related issue: #10802
Default import unexpectedly returns an object
The default import returns the 
module.exports object for CJS modules, while you may expect it to return the 
module.exports.default value.
This may cause errors like:
Element type is invalid: expected a string (for built-in components) or a class/function (for composite components) but got: object.
foo is not a function
See Rolldown's docs about this problem for more details: Ambiguous 
default import from CJS modules - Bundling CJS | Rolldown.

Using Plugins
Vite can be extended using plugins, which are based on Rollup's well-designed plugin interface with a few extra Vite-specific options. This means that Vite users can rely on the mature ecosystem of Rollup plugins, while also being able to extend the dev server and SSR functionality as needed.
Watch an interactive lesson on Scrimba
Adding a Plugin
To use a plugin, it needs to be added to the 
devDependencies of the project and included in the 
plugins array in the 
vite.config.js config file. For example, to provide support for legacy browsers, the official @vitejs/plugin-legacy can be used:
$ npm add -D @vitejs/plugin-legacy
import legacy from '@vitejs/plugin-legacy'
import { defineConfig } from 'vite'
export default defineConfig({
  plugins: [
    legacy({
      targets: ['defaults', 'not IE 11'],
    }),
  ],
})
plugins also accepts presets including several plugins as a single element. This is useful for complex features (like framework integration) that are implemented using several plugins. The array will be flattened internally.
Falsy plugins will be ignored, which can be used to easily activate or deactivate plugins.
Finding Plugins
:::tip NOTE
Vite aims to provide out-of-the-box support for common web development patterns. Before searching for a Vite or compatible Rollup plugin, check out the Features Guide. A lot of the cases where a plugin would be needed in a Rollup project are already covered in Vite.
:::
Check out the Plugins section for information about official plugins. Community plugins that are published to npm are listed in Vite Plugin Registry.
Enforcing Plugin Ordering
For compatibility with some Rollup plugins, it may be needed to enforce the order of the plugin or only apply at build time. This should be an implementation detail for Vite plugins. You can enforce the position of a plugin with the 
enforce modifier:
pre: invoke plugin before Vite core plugins
default: invoke plugin after Vite core plugins
post: invoke plugin after Vite build plugins
import image from '@rollup/plugin-image'
import { defineConfig } from 'vite'
export default defineConfig({
  plugins: [
    {
      ...image(),
      enforce: 'pre',
    },
  ],
})
Check out Plugins API Guide for detailed information.
Conditional Application
By default, plugins are invoked for both serve and build. In cases where a plugin needs to be conditionally applied only during serve or build, use the 
apply property to only invoke them during 
'build' or 
'serve':
import typescript2 from 'rollup-plugin-typescript2'
import { defineConfig } from 'vite'
export default defineConfig({
  plugins: [
    {
      ...typescript2(),
      apply: 'build',
    },
  ],
})
Building Plugins
Check out the Plugins API Guide for documentation about creating plugins.

Why Vite
As web applications have grown in size and complexity, the tools used to build them have struggled to keep up. Developers working on large projects have experienced painfully slow dev server startups, sluggish hot updates, and long production build times. Each generation of build tooling has improved on the last, but these problems have persisted.
Vite was created to address this. Rather than incrementally improving existing approaches, it rethought how code should be served during development. Since then, Vite has evolved through multiple major versions, each time adapting to new capabilities in the ecosystem: from leveraging native ES modules in the browser, to adopting a fully Rust-powered toolchain.
Today, Vite powers many frameworks and tools. Its architecture is designed to evolve with the web platform rather than lock into any single approach, making it a foundation you can build on for the long term.
The Origins
When Vite was first created, browsers had just gained wide support for ES modules (ESM), a way to load JavaScript files directly, without needing a tool to bundle them into a single file first. Traditional build tools (often called bundlers) would process your entire application upfront before anything could be shown in the browser. The larger the app, the longer you waited.
Vite took a different approach. It split the work into two parts:
Dependencies (libraries that rarely change) are pre-bundled once using fast native tooling, so they're ready instantly.
Source code (your application code that changes frequently) is served on-demand over native ESM. The browser loads only what it needs for the current page, and Vite transforms each file as it's requested.
This meant dev server startup was nearly instant, regardless of application size. When you edited a file, Vite used Hot Module Replacement (HMR) over native ESM to update just that module in the browser, without a full page reload or waiting for a rebuild.
In a bundle-based dev server, the entire application is bundled before it can be served.
In an ESM-based dev server, modules are served on-demand as the browser requests them.
Vite was not the first tool to explore this approach. Snowpack pioneered unbundled development and inspired Vite's dependency pre-bundling. WMR by the Preact team inspired the universal plugin API that works in both dev and build. @web/dev-server influenced Vite 1.0's server architecture. Vite built on these ideas and carried them forward.
Even though unbundled ESM works well during development, shipping it in production is still inefficient due to additional network round trips from nested imports. That's why bundling is still necessary for optimized production builds.
Growing with the Ecosystem
As Vite matured, frameworks began adopting it as their build layer. Its plugin API, based on Rollup's conventions, made integration natural without requiring frameworks to work around Vite's internals. Nuxt, SvelteKit, Astro, React Router, Analog, SolidStart, and others chose Vite as their foundation. Tools like Vitest and Storybook built on it too, extending Vite's reach beyond app bundling. Backend frameworks like Laravel and Ruby on Rails integrated Vite for their frontend asset pipelines.
This growth was not one-directional. The ecosystem shaped Vite as much as Vite shaped the ecosystem. The Vite team runs vite-ecosystem-ci, which tests major ecosystem projects against every Vite change. Ecosystem health is not an afterthought. It is part of the release process.
A Unified Toolchain
Vite originally relied on two separate tools under the hood: esbuild for fast compilation during development, and Rollup for thorough optimization in production builds. This worked, but maintaining two pipelines introduced inconsistencies: different transformation behaviors, separate plugin systems, and growing glue code to keep them aligned.
Rolldown was built to unify both into a single bundler: written in Rust for native speed, and compatible with the same plugin API the ecosystem already relied on. It uses Oxc for parsing, transforming, and minifying. This gives Vite an end-to-end toolchain where the build tool, bundler, and compiler are maintained together and evolve as a unit.
The result is one consistent pipeline from development to production. The migration was done carefully: a technical preview shipped first so early adopters could validate the change, ecosystem CI caught compatibility issues early, and a compatibility layer preserved existing configurations.
Where Vite is Heading
Vite's architecture continues to evolve. Several efforts are shaping its future:
Full bundle mode: Unbundled ESM was the right tradeoff when Vite was created because no tool was both fast enough and had the HMR and plugin capabilities needed to bundle during dev. Rolldown changes that. Since exceptionally large codebases can experience slow page loads due to the high number of unbundled network requests, the team is exploring a mode where the dev server bundles code similarly to production, reducing network overhead.
Environment API: Instead of treating "client" and "SSR" as the only two build targets, the Environment API lets frameworks define custom environments (edge runtimes, service workers, and other deployment targets), each with their own module resolution and execution rules. As where and how code runs continues to diversify, Vite's model expands with it.
Evolving with JavaScript: With Oxc and Rolldown closely collaborating with Vite, new language features and standards can be adopted quickly across the entire toolchain, without waiting on upstream dependencies.
Vite's goal is not to be the final tool, but to be one that keeps evolving with the web platform, and with the developers building on it.