219 lines
3.8 KiB
Markdown
219 lines
3.8 KiB
Markdown
---
|
|
name: advanced-api
|
|
description: Vite's JavaScript API for programmatic usage
|
|
---
|
|
|
|
# JavaScript API
|
|
|
|
Vite's APIs are fully typed. Use TypeScript or enable JS type checking for intellisense.
|
|
|
|
## `createServer`
|
|
|
|
Create a development server programmatically:
|
|
|
|
```ts
|
|
import { createServer } from 'vite'
|
|
|
|
const server = await createServer({
|
|
configFile: false,
|
|
root: __dirname,
|
|
server: {
|
|
port: 1337
|
|
}
|
|
})
|
|
|
|
await server.listen()
|
|
server.printUrls()
|
|
server.bindCLIShortcuts({ print: true })
|
|
```
|
|
|
|
### ViteDevServer Interface
|
|
|
|
```ts
|
|
interface ViteDevServer {
|
|
config: ResolvedConfig
|
|
middlewares: Connect.Server // Connect app for custom middleware
|
|
httpServer: http.Server | null // Node HTTP server
|
|
watcher: FSWatcher // Chokidar watcher
|
|
ws: WebSocketServer // WebSocket for HMR
|
|
moduleGraph: ModuleGraph // Module import relationships
|
|
|
|
// Transform without HTTP
|
|
transformRequest(url: string): Promise<TransformResult | null>
|
|
|
|
// Apply HTML transforms
|
|
transformIndexHtml(url: string, html: string): Promise<string>
|
|
|
|
// Load module for SSR
|
|
ssrLoadModule(url: string): Promise<Record<string, any>>
|
|
|
|
// Fix SSR error stack traces
|
|
ssrFixStacktrace(e: Error): void
|
|
|
|
// Control
|
|
listen(port?: number): Promise<ViteDevServer>
|
|
restart(): Promise<void>
|
|
close(): Promise<void>
|
|
}
|
|
```
|
|
|
|
## `build`
|
|
|
|
Build for production:
|
|
|
|
```ts
|
|
import { build } from 'vite'
|
|
|
|
await build({
|
|
root: './project',
|
|
base: '/foo/',
|
|
build: {
|
|
rolldownOptions: {
|
|
// ...
|
|
}
|
|
}
|
|
})
|
|
```
|
|
|
|
## `preview`
|
|
|
|
Preview production build locally:
|
|
|
|
```ts
|
|
import { preview } from 'vite'
|
|
|
|
const previewServer = await preview({
|
|
preview: {
|
|
port: 8080,
|
|
open: true
|
|
}
|
|
})
|
|
|
|
previewServer.printUrls()
|
|
```
|
|
|
|
## `resolveConfig`
|
|
|
|
Resolve config without starting server:
|
|
|
|
```ts
|
|
import { resolveConfig } from 'vite'
|
|
|
|
const config = await resolveConfig(
|
|
{ root: './project' },
|
|
'serve', // 'serve' | 'build'
|
|
'development' // default mode
|
|
)
|
|
```
|
|
|
|
## `mergeConfig`
|
|
|
|
Deep merge two configs:
|
|
|
|
```ts
|
|
import { mergeConfig } from 'vite'
|
|
|
|
const merged = mergeConfig(baseConfig, overrideConfig)
|
|
```
|
|
|
|
Merge callback config:
|
|
|
|
```ts
|
|
import { defineConfig, mergeConfig } from 'vite'
|
|
|
|
export default defineConfig((env) =>
|
|
mergeConfig(configAsCallback(env), configAsObject)
|
|
)
|
|
```
|
|
|
|
## `loadEnv`
|
|
|
|
Load .env files:
|
|
|
|
```ts
|
|
import { loadEnv } from 'vite'
|
|
|
|
// Load VITE_* vars
|
|
const env = loadEnv('development', process.cwd())
|
|
|
|
// Load all vars (empty prefix)
|
|
const allEnv = loadEnv('development', process.cwd(), '')
|
|
```
|
|
|
|
## `searchForWorkspaceRoot`
|
|
|
|
Find monorepo workspace root:
|
|
|
|
```ts
|
|
import { searchForWorkspaceRoot } from 'vite'
|
|
|
|
const workspaceRoot = searchForWorkspaceRoot(process.cwd())
|
|
```
|
|
|
|
## `normalizePath`
|
|
|
|
Normalize paths for cross-platform:
|
|
|
|
```ts
|
|
import { normalizePath } from 'vite'
|
|
|
|
normalizePath('foo\\bar') // 'foo/bar'
|
|
```
|
|
|
|
## `transformWithOxc`
|
|
|
|
Transform JS/TS with Oxc Transformer:
|
|
|
|
```ts
|
|
import { transformWithOxc } from 'vite'
|
|
|
|
const result = await transformWithOxc(
|
|
code,
|
|
'file.ts',
|
|
{ target: 'es2020' }
|
|
)
|
|
```
|
|
|
|
## `preprocessCSS`
|
|
|
|
Pre-process CSS files:
|
|
|
|
```ts
|
|
import { preprocessCSS, resolveConfig } from 'vite'
|
|
|
|
const config = await resolveConfig({}, 'serve')
|
|
const result = await preprocessCSS(code, 'styles.scss', config)
|
|
// result.code - plain CSS
|
|
// result.modules - CSS modules mapping
|
|
```
|
|
|
|
## `loadConfigFromFile`
|
|
|
|
Load config file manually:
|
|
|
|
```ts
|
|
import { loadConfigFromFile } from 'vite'
|
|
|
|
const result = await loadConfigFromFile(
|
|
{ command: 'serve', mode: 'development' },
|
|
'vite.config.ts'
|
|
)
|
|
// result.config, result.path, result.dependencies
|
|
```
|
|
|
|
## InlineConfig
|
|
|
|
Extends UserConfig with:
|
|
|
|
```ts
|
|
interface InlineConfig extends UserConfig {
|
|
configFile?: string | false // Config file path or false to skip
|
|
mode?: string
|
|
}
|
|
```
|
|
|
|
<!--
|
|
Source references:
|
|
- https://vite.dev/guide/api-javascript.html
|
|
-->
|