Migrating from Vite

Vantris deliberately mirrors Vite's mental model — an index.html entry, an on-the-fly dev server, import.meta.hot, import.meta.env, optimizeDeps, and a Rollup-shaped plugin API. If you know Vite, you already know most of Vantris. This page maps the differences.

The big picture

Concept	Vite	Vantris
Config file	vite.config.ts	vantris.config.ts
Config helper	defineConfig	defineConfig (same idea)
CLI	vite / build / preview	vantris dev / build / preview
Dev command	vite	vantris dev
Entry	index.html	index.html (same)
HMR API	import.meta.hot	import.meta.hot (same shape)
Env	import.meta.env, VITE_	import.meta.env, VANTRIS_
Client types	vite/client	vantris/client
Plugins	Rollup/Vite plugins	Vantris plugins (definePlugin)
Dep pre-bundling	optimizeDeps	optimizeDeps (same)
Bundler	Rollup / Rolldown	Rolldown (internal, not exposed)

Config changes

Rename the file and env prefix

• vite.config.ts → vantris.config.ts.
• VITE_* env variables → VANTRIS_*. See Env Variables & Modes.
• vite/client → vantris/client in your tsconfig types. See Client Types.

Host/port moved to dev

In Vite, server.port sets the dev port. In Vantris, host/port live in dev, and server holds the networking layer (HTTPS, proxy, CORS, SPA fallback, base):

// Vite
export default defineConfig({
  server: { port: 3000, proxy: { "/api": "http://localhost:8080" } },
});

// Vantris
export default defineConfig({
  dev: { port: 3000 },
  server: { proxy: { "/api": "http://localhost:8080" } },
});

rootDir and publicDir

Vantris separates the project root from the source directory rootDir (default ./src). Vite folds source into root. If your Vite project kept source in src/ (the common case), set nothing — rootDir: "./src" is the default.

No engine escape hatch

Vite exposes build.rollupOptions, esbuild, css.postcss object config, etc. Vantris does not expose its engines — there's no rolldownOptions. Instead, the common needs are first-class Vantris options:

Vite escape hatch	Vantris equivalent
build.rollupOptions.output.*	build.entryFileNames etc.
esbuild transform options	handled internally; use plugins for custom transforms
css.postcss	drop a postcss.config.* file — auto-detected
css.modules	*.module.css convention

If you relied heavily on rollupOptions, model the need as a plugin instead.

Plugins

The plugin shape is intentionally close to Rollup/Vite, so the mental model carries over: config, configResolved, resolveId, load, transform, transformIndexHtml, handleHotUpdate, configureServer, buildStart, buildEnd, ordered with enforce.

Key differences:

• Referenced by string. Vantris config lists plugins as strings (a package name or a local path), not by importing and calling them:

  // Vite
  import react from "@vitejs/plugin-react";
  export default defineConfig({ plugins: [react()] });

  // Vantris
  export default defineConfig({ plugins: ["@vantris/react"] });

  To pass options, wrap the plugin in a local module and reference that file. See @vantris/react → With options.

• Vantris-owned types. Hook signatures are typed by Vantris (Plugin, TransformResult, PluginContext), and the bundler is never exposed in them. A plugin written against Rollup's raw types won't drop in unchanged, but the concepts and most code translate directly. See the Plugin API.

• this context. Pipeline hooks get a Vantris PluginContext (resolve, emitFile, addWatchFile, warn, error, meta), backed by the bundler's own context in the build.

What's the same

You can migrate most of these with no code change:

• index.html as the entry, with <script type="module">.
• import.meta.hot.accept(...) and the whole HMR API — same shape.
• import.meta.env.MODE / DEV / PROD / BASE_URL — same built-ins (rename your prefixed vars).
• optimizeDeps.include / optimizeDeps.exclude — same semantics.
• resolve.alias — same, plus a tsconfig paths fallback.
• CSS Modules (*.module.css), Sass/Less as optional deps, PostCSS via config file.
• public/ served verbatim; imported assets hashed.
• define for global constants.

A migration checklist

1. Rename vite.config.ts → vantris.config.ts; keep defineConfig.
2. Move server.port/server.host → dev. Leave proxy/https/cors in server.
3. Rename VITE_* → VANTRIS_* in .env files and code.
4. Swap vite/client → vantris/client in tsconfig.json.
5. Replace plugins: [react()] → plugins: ["@vantris/react"] (wrap for options).
6. Drop any rollupOptions/esbuild config; use Vantris options or a plugin.
7. Update package.json scripts: vite → vantris dev, keep build/preview.
8. Run vantris dev, then vantris build && vantris preview.

Things Vantris doesn't (yet) do

Vantris targets React and vanilla JS/TS. If your Vite project depends on a framework plugin outside that scope (Vue SFCs, Svelte, SolidJS), there isn't a first-party Vantris equivalent today — the plugin API is in place for the ecosystem to build them, and @vantris/react is the first official one.