Server Options

The server block configures the dev server's networking layer — HTTPS, request proxying, CORS, the mount base, and the SPA history fallback. Host and port stay in dev.

For a task-oriented walkthrough, see the Networking guide.

import { defineConfig } from "vantris";

export default defineConfig({
  server: {
    https: false,
    proxy: {},
    cors: false,
    base: undefined,     // defaults to the top-level `base`
    spaFallback: true,
  },
});

• server.https
  • HttpsConfig
• server.proxy
  • ProxyOptions
• server.cors
  • CorsOptions
• server.base
• server.spaFallback
• ServerConfig at a glance

server.https

• Type: boolean | { cert: string; key: string }
• Default: false

Serve over HTTPS. true generates a self-signed development certificate on the fly (Vantris warns that browsers will prompt to trust it). Pass { cert, key } to use your own — each accepts PEM contents or a file path resolved against root.

server: { https: true }

server: {
  https: {
    cert: "./certs/localhost.pem",
    key: "./certs/localhost-key.pem",
  },
}

HttpsConfig

Field	Type	Description
cert	string	PEM certificate (contents or a path).
key	string	PEM private key (contents or a path).

server.proxy

• Type: Record<string, string | ProxyOptions>
• Default: {}

Proxy rules mapping a request-path prefix to a target origin (a string) or a ProxyOptions object.

server: {
  proxy: {
    "/api": "http://localhost:8080",
    "/auth": {
      target: "https://auth.example.com",
      changeOrigin: true,
      rewrite: (path) => path.replace(/^\/auth/, ""),
      secure: true,
    },
  },
}

An unreachable target responds with a clear 502.

ProxyOptions

Field	Type	Default	Description
target	string	—	Target origin, e.g. "http://localhost:8080".
changeOrigin	boolean	true	Rewrite the Host header to the target's.
rewrite	(path: string) => string	—	Rewrite the request path before forwarding.
secure	boolean	true	Verify TLS certificates for an https target.

server.cors

• Type: boolean | CorsOptions
• Default: false

Enable CORS. true applies permissive defaults; an object customises it. Sets Access-Control-* headers and answers preflight OPTIONS requests.

server: { cors: true }

server: {
  cors: {
    origin: ["http://localhost:3000"],
    methods: ["GET", "POST"],
    headers: ["Content-Type", "Authorization"],
    credentials: true,
  },
}

CorsOptions

Field	Type	Default	Description
origin	string | string[] | boolean	true	Allowed origin(s). true reflects Origin.
methods	string[]	["GET","HEAD","PUT","PATCH","POST","DELETE"]	Allowed methods.
headers	string[]	—	Echoed to Access-Control-Allow-Headers.
credentials	boolean	false	Sets Access-Control-Allow-Credentials.

server.base

• Type: string
• Default: the top-level base

Sub-path the dev server is mounted under. Injected scripts and asset URLs respect it. Usually you set the top-level base and leave this alone; set it to override just the dev server's mount point.

export default defineConfig({
  base: "/app/",
  server: { base: "/app/" },
});

server.spaFallback

• Type: boolean
• Default: true

History-API fallback: an unmatched, non-file route serves index.html (so client-side routing works on refresh). A missing .js/.png still returns a real 404.

server: { spaFallback: false } // disable for a multi-page app

ServerConfig at a glance

interface ServerConfig {
  https?: boolean | HttpsConfig;
  proxy?: Record<string, string | ProxyOptions>;
  cors?: boolean | CorsOptions;
  base?: string;
  spaFallback?: boolean;
}