JavaScript API
The vantris CLI is the primary entry point, but everything it relies on is also exported from the package, so you can embed Vantris in custom tooling — a test harness, a meta-framework, a bespoke build script.
import { run, runBuild, startDevServer, defineConfig } from "vantris";Everything below is a named export of vantris.
Configuration
defineConfig
function defineConfig(config: ConfigInput): ConfigInput;A typed identity helper for vantris.config.ts. Returns its argument unchanged; its value is autocompletion and type-checking. ConfigInput is a Config object or a function (sync/async) returning one.
import { defineConfig } from "vantris";
export default defineConfig({ dev: { port: 5173 } });loadConfig
function loadConfig(/* … */): Promise<ResolvedConfig>;Locate and load vantris.config.{ts,js,mjs} from a directory, apply defaults, and return the resolved config. This is what the CLI uses internally.
resolveConfig
function resolveConfig(input: ConfigInput /* … */): Promise<ResolvedConfig>;Turn a Config (or config function) into a fully ResolvedConfig — defaults applied, paths made absolute — without reading a file.
validateConfig
function validateConfig(config: unknown): asserts config is Config;Validate a config object, throwing a ConfigError with the property path, expected type, and received value on the first invalid field.
Commands
run
function run(argv: string[]): Promise<void>;The CLI entry — parse arguments and route to a command. Drive Vantris exactly as the vantris binary does:
import { run } from "vantris";
await run(["build", "--mode", "production"]);commands
The command registry (dev, build, preview) — a map of Command objects. Useful to introspect or invoke a command programmatically.
Build
runBuild
function runBuild(options: BuildOptions): Promise<BuildResult>;Run a production build programmatically and get the result (emitted files, timing). See Building for Production.
import { runBuild } from "vantris";
const result = await runBuild({ /* BuildOptions */ });Dev server
createDevServer / startDevServer
function createDevServer(options: DevServerOptions): Promise<DevServerHandle>;
function startDevServer(options: DevServerOptions): Promise<DevServerHandle>;Create (or create and start) the dev server. createDevServer is the single bootstrap shared by Node.js and Bun. The returned DevServerHandle exposes the server URL and the HMR engine — the same handle a plugin's configureServer receives.
Preview server
startPreviewServer
function startPreviewServer(options: PreviewServerOptions): Promise<PreviewServerHandle>;Start the static preview server over outDir. See Preview.
Plugins
definePlugin
function definePlugin(plugin: Plugin): Plugin;Typed identity helper for authoring plugins. See the Plugin API.
PluginContainer / loadPlugins
The container that runs plugin hooks in order (pre → normal → post), shared by the dev server and the bundler, and the loader that turns the config's plugin strings into resolved plugin objects.
Environment
loadEnv, parseEnv, clientEnv, envDefine, ENV_PREFIX
Helpers behind env loading: read .env files for a mode (loadEnv), parse env text (parseEnv), compute the client-exposed subset (clientEnv), turn it into define entries (envDefine), and the prefix constant (ENV_PREFIX — "VANTRIS_").
Module resolver
createResolver
function createResolver(/* … */): Resolver;Create the single resolver that applies resolve.alias everywhere. This is the same resolver used across dev, build, HTML, and CSS.
HTML pipeline
detectHtmlEntry, parseHtml, injectDevClient, devClientScript
The HTML tools: find the index.html entry and its module scripts (detectHtmlEntry, parseHtml), and inject the dev/HMR client into a served page (injectDevClient, devClientScript).
HMR (server side)
HmrEngine, ModuleGraph, and helpers
The server-side HMR machinery: the engine that turns file changes into updates (HmrEngine), the module graph of importer edges and accept boundaries (ModuleGraph), the client runtime renderer (renderClientRuntime), the import.meta.hot injector (injectHotContext), the accept-boundary lexer (lexHmrUsage), and the payload codecs (encodePayload, decodeClientMessage). See the HMR API.
getRuntime
function getRuntime(): Runtime;Detect the active JavaScript runtime (Node.js or Bun) — the abstraction that lets one server bootstrap serve both.
Cache
createCache, cacheForContext, cacheKey
The internal cache in node_modules/.vantris/ — create a cache (createCache), get the one bound to a context (cacheForContext), and compute a content key (cacheKey). See Internal Cache.
Context & services
createContext, createLogger, createWatcher
The dependency-injection primitives: build the Context commands receive (createContext), the styled logger (createLogger), and the file watcher (createWatcher).
Errors
VantrisError and subclasses
class VantrisError extends Error {}
class ConfigError extends VantrisError {}
class HtmlEntryError extends VantrisError {}
class BuildError extends VantrisError {}
class ServerError extends VantrisError {}
class PreviewError extends VantrisError {}
class NotImplementedError extends VantrisError {}
function isVantrisError(err: unknown): err is VantrisError;Everything intentional throws a VantrisError subclass, rendered cleanly by the CLI. Use isVantrisError to detect them when embedding Vantris.
import { runBuild, isVantrisError } from "vantris";
try {
await runBuild({ /* … */ });
} catch (err) {
if (isVantrisError(err)) console.error("Vantris:", err.message);
else throw err;
}Constants
VERSION
The Vantris version string.
import { VERSION } from "vantris";
console.log(VERSION); // "1.2.0"Exported types
Every public type is exported for use in your own code:
Config — Config, ConfigFn, ConfigInput, DevConfig, BuildConfig, PreviewConfig, ResolveConfig, ServerConfig, HttpsConfig, ProxyOptions, CorsOptions, OptimizeDepsConfig, LibConfig, LibFormat, DefineValue, ChunkInfo, AssetInfo, ChunkFileNames, AssetFileNames.
Resolved config — ResolvedConfig, ResolvedDevConfig, ResolvedServerConfig, ResolvedBuildConfig, ResolvedPreviewConfig, ResolvedResolveConfig, ResolvedOptimizeDeps, ResolvedPaths, AliasEntry, …
Plugins — Plugin, ConfigEnv, ResolveIdResult, TransformResult.
HMR — HmrEngineOptions, HotUpdateContext, HotUpdateHook, ModuleNode, ModuleInfo, HmrPayload, ClientMessage, Update, Runtime.
Servers — DevServerOptions, DevServerHandle, PreviewServerOptions, PreviewServerHandle, BuildOptions, BuildResult.
Services — Logger, Context, Command, Watcher, WatcherOptions, WatchEvent, Cache, CacheOptions, Resolver, ClientEnv, HtmlEntry, HtmlModuleScript.
import type { Config, Plugin, ResolvedConfig } from "vantris";