gt-agent-company/.agents/skills/vite/references/advanced-api.md

name, description

name	description
advanced-api	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:

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

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:

import { build } from 'vite'

await build({
  root: './project',
  base: '/foo/',
  build: {
    rolldownOptions: {
      // ...
    }
  }
})

preview

Preview production build locally:

import { preview } from 'vite'

const previewServer = await preview({
  preview: {
    port: 8080,
    open: true
  }
})

previewServer.printUrls()

resolveConfig

Resolve config without starting server:

import { resolveConfig } from 'vite'

const config = await resolveConfig(
  { root: './project' },
  'serve',        // 'serve' | 'build'
  'development'   // default mode
)

mergeConfig

Deep merge two configs:

import { mergeConfig } from 'vite'

const merged = mergeConfig(baseConfig, overrideConfig)

Merge callback config:

import { defineConfig, mergeConfig } from 'vite'

export default defineConfig((env) =>
  mergeConfig(configAsCallback(env), configAsObject)
)

loadEnv

Load .env files:

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:

import { searchForWorkspaceRoot } from 'vite'

const workspaceRoot = searchForWorkspaceRoot(process.cwd())

normalizePath

Normalize paths for cross-platform:

import { normalizePath } from 'vite'

normalizePath('foo\\bar')  // 'foo/bar'

transformWithOxc

Transform JS/TS with Oxc Transformer:

import { transformWithOxc } from 'vite'

const result = await transformWithOxc(
  code,
  'file.ts',
  { target: 'es2020' }
)

preprocessCSS

Pre-process CSS files:

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:

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:

interface InlineConfig extends UserConfig {
  configFile?: string | false  // Config file path or false to skip
  mode?: string
}