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.
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()
})()
::: 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.
:::
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 tofalse
to disable auto resolving.envFile
: Set tofalse
to disable.env
files.
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 anid
is considered an asset.config.logger
: Vite's internal logger object.
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
/**
* 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>
}
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: {
// ...
}
}
})
})()
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()
})()
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).
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.
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 inpackage.json
- contains one of the following file
lerna.json
pnpm-workspace.yaml
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.
Type Signature:
function normalizePath(id: string): string
Related: Path Normalization
Normalizes a path to interoperate between Vite plugins.
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.
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.