TypeScript

TypeScript is a first-class citizen. Vantris transpiles .ts and .tsx on the fly in dev (via esbuild) and compiles them in the build (via Rolldown) — no separate build step, no ts-node, no config needed to start.

// src/main.ts — just works
const greet = (name: string): string => `Hello ${name}`;
document.body.textContent = greet("Vantris");

Transpilation, not type-checking

Like esbuild and Vite, Vantris transpiles TypeScript — it strips types and emits JavaScript, but it does not type-check during dev or build. This keeps both fast. Run type-checking separately, as its own gate:

{
  "scripts": {
    "dev": "vantris dev",
    "build": "vantris build",
    "typecheck": "tsc --noEmit"
  }
}

Run npm run typecheck in CI (and your editor's language server catches errors live as you type). Because type-checking is decoupled, a type error never blocks your dev server or a build.

What this means for your code

A few TypeScript features depend on type information the transpiler doesn't have. The practical guidance, same as any esbuild-based tool:

• Use import type / export type for type-only imports so they're reliably erased and never pull a module into the graph.
• enum and namespaces work, but prefer const objects / unions in new code.
• verbatimModuleSyntax is recommended in tsconfig.json — it makes the type-only vs. value distinction explicit and matches how Vantris erases types.

Recommended tsconfig.json

{
  "compilerOptions": {
    "target": "ESNext",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "strict": true,
    "verbatimModuleSyntax": true,
    "noEmit": true,
    "jsx": "react-jsx",
    "types": ["vantris/client"],
    "baseUrl": ".",
    "paths": { "@/*": ["./src/*"] }
  },
  "include": ["src"]
}

Two lines do double duty for Vantris:

• "paths" — when resolve.alias is omitted from your config, Vantris reads these as your aliases. See Aliases.
• "types": ["vantris/client"] — ambient types for import.meta.env, import.meta.hot, and asset/CSS imports. See Client Types.

Client types

Add vantris/client so TypeScript understands the things Vantris injects:

{ "compilerOptions": { "types": ["vantris/client"] } }

or per-file:

/// <reference types="vantris/client" />

This types:

• import.meta.env — MODE, DEV, PROD, BASE_URL, and your VANTRIS_-prefixed variables (see Env Variables).
• import.meta.hot — the HMR API.
• Asset imports — import logo from "./logo.svg" typed as string, *.module.css typed as a class map, etc.

Full details on the Client Types page.

JSX & the automatic runtime

.tsx compiles with the automatic JSX runtime by default — no import React needed. "jsx": "react" selects the classic runtime; jsxImportSource is honoured for Preact and other JSX libraries. See React & JSX.

tsconfig.json and the build

Vantris doesn't run tsc for you, so most compilerOptions that affect emit (like target) are handled by the bundler's own settings, not your tsconfig. The fields Vantris does read are paths/baseUrl (for aliases) and jsx/ jsxImportSource (for the JSX runtime). Everything else is for your editor and your typecheck script.