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 { fileURLToPath } from 'url'
import { createServer } from 'vite'

const __dirname = fileURLToPath(new URL('.', import.meta.url))

;(async () => {
  const server = await createServer({
    // any valid user config options, plus `mode` and `configFile`
    configFile: false,
    root: __dirname,
    server: {
      port: 1337,
    },
  })
  await server.listen()

  server.printUrls()
})()

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.

`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.
envFile: Set to false to disable .env files.

`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.
   * https://github.com/paulmillr/chokidar#api
   */
  watcher: FSWatcher
  /**
   * Web socket 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. null in middleware mode or
   * before `server.listen` is called.
   */
  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): 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>
}

`build`

Type Signature:

async function build(
  inlineConfig?: InlineConfig,
): Promise<RollupOutput | RollupOutput[]>

Example Usage:

import path from 'path'
import { fileURLToPath } from 'url'
import { build } from 'vite'

const __dirname = fileURLToPath(new URL('.', import.meta.url))

;(async () => {
  await build({
    root: path.resolve(__dirname, './project'),
    base: '/foo/',
    build: {
      rollupOptions: {
        // ...
      },
    },
  })
})()

`preview`

Type Signature:

async function preview(inlineConfig?: InlineConfig): Promise<PreviewServer>

Example Usage:

import { preview } from 'vite'
;(async () => {
  const previewServer = await preview({
    // any valid user config options, plus `mode` and `configFile`
    preview: {
      port: 8080,
      open: true,
    },
  })

  previewServer.printUrls()
})()

`PreviewServer`

interface PreviewServer extends PreviewServerForHook {
  resolvedUrls: ResolvedServerUrls
}

`PreviewServerForHook`

interface PreviewServerForHook {
  /**
   * 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
   */
  resolvedUrls: ResolvedServerUrls | null
  /**
   * Print server urls
   */
  printUrls(): void
}

`resolveConfig`

Type Signature:

async function resolveConfig(
  inlineConfig: InlineConfig,
  command: 'build' | 'serve',
  defaultMode = 'development',
): Promise<ResolvedConfig>

The command value is serve in dev (in the cli vite, vite dev, and vite serve are aliases).

`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

mergeConfig accepts only config in object form. If you have a config in callback form, you should call it before passing into mergeConfig.

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

`transformWithEsbuild`

Type Signature:

async function transformWithEsbuild(
  code: string,
  filename: string,
  options?: EsbuildTransformOptions,
  inMap?: object,
): Promise<ESBuildTransformResult>

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,
): Promise<{
  path: string
  config: UserConfig
  dependencies: string[]
} | null>

Load a Vite config file manually with esbuild.

JavaScript API ​

createServer ​

InlineConfig ​

ResolvedConfig ​

ViteDevServer ​

build ​

preview ​

PreviewServer ​

PreviewServerForHook ​

resolveConfig ​

mergeConfig ​

searchForWorkspaceRoot ​

loadEnv ​

normalizePath ​

transformWithEsbuild ​

loadConfigFromFile ​

JavaScript API

`createServer`

`InlineConfig`

`ResolvedConfig`

`ViteDevServer`

`build`

`preview`

`PreviewServer`

`PreviewServerForHook`

`resolveConfig`

`mergeConfig`

`searchForWorkspaceRoot`

`loadEnv`

`normalizePath`

`transformWithEsbuild`

`loadConfigFromFile`