Configuration Overview

Vantris is configured with a single optional file at the project root: vantris.config.ts (or .js / .mjs). Every field is optional — a project with zero configuration builds and runs on the documented defaults.

The config file

import { defineConfig } from "vantris";

export default defineConfig({
  // your options here
});

defineConfig is a typed identity helper: it returns its argument unchanged but gives you autocompletion and type-checking. See the JavaScript API.

A config function

The default export can also be a function (sync or async) returning a config, so a config can compute values at load time:

import { defineConfig } from "vantris";

export default defineConfig(async () => {
  return {
    define: { __BUILT_AT__: new Date().toISOString() },
  };
});

Validation

The config is validated on load. An invalid value fails fast with the property path, the expected type, and the value received — no silent coercion, no confusing downstream error:

ConfigError: `dev.port` must be a number, received "3000" (string)

The complete option surface

Below is every field with its default. Each block links to its detailed page.

import { defineConfig } from "vantris";

export default defineConfig({
  // ─── Paths ───────────────────────────────────────────────
  root: ".",             // project root
  rootDir: "./src",      // source directory
  publicDir: "./public", // static assets, served at / and copied verbatim
  outDir: "./dist",      // build output
  base: "/",             // public base path, prefixed to built URLs

  // ─── Dev server: host/port ───────────────────────────────
  dev: {
    port: 3000,
    host: "localhost",
  },

  // ─── Dev-server networking ───────────────────────────────
  server: {
    https: false,          // or true (self-signed dev cert) | { cert, key }
    proxy: {},             // e.g. { "/api": "http://localhost:8080" }
    cors: false,           // or true | { origin, methods, headers, credentials }
    spaFallback: true,     // history-API fallback to index.html
    // base: "/app/",      // defaults to the top-level `base`
  },

  // ─── Global constants (inlined in dev and build) ─────────
  define: {
    // __DEV__: true,
    // __APP_VERSION__: "1.0.0",
  },

  // ─── Production build ────────────────────────────────────
  build: {
    minify: true,
    sourcemap: false,        // or true | "inline" | "hidden"
    emptyOutDir: true,
    assetsDir: "assets",
    entryFileNames: "assets/[name]-[hash].js",
    chunkFileNames: "assets/[name]-[hash].js",
    assetFileNames: "assets/[name]-[hash][extname]",
    // lib: { ... }          // build a library instead of an app
  },

  // ─── Preview server ──────────────────────────────────────
  preview: {
    port: 4173,
    host: "localhost",
    open: false,
  },

  // ─── Module resolution ───────────────────────────────────
  resolve: {
    alias: {
      // "@": "./src",
    },
  },

  // ─── Dependency pre-bundling (dev) ───────────────────────
  optimizeDeps: {
    include: [],           // pre-bundle at startup
    exclude: [],           // serve as native ESM
  },

  // ─── Plugins (referenced by string) ──────────────────────
  plugins: [
    // "@vantris/react",
    // "./plugins/my-plugin",
  ],
});

Option index

Block	Purpose	Reference
Top-level	root, rootDir, publicDir, outDir, base, define, plugins	Shared Options
dev	Dev-server host & port	Dev Options
server	HTTPS, proxy, CORS, base, SPA fallback	Server Options
build	Minify, sourcemaps, output names, library mode	Build Options
preview	Preview-server host, port, open	Preview Options
resolve	Import aliases	Resolve Options
optimizeDeps	Dependency pre-bundling	optimizeDeps Options

TypeScript types

The config type is exported for advanced use — building a config programmatically, sharing partials, or typing a helper:

import type { Config, ConfigInput } from "vantris";

const shared: Partial<Config> = {
  resolve: { alias: { "@": "./src" } },
};

See the JavaScript API for every exported type.