Aliases

Import aliases let you write @/utils instead of ../../../utils. A single resolver applies resolve.alias everywhere — dev, build, HTML, and CSS — so an alias behaves the same across the whole toolchain.

Defining aliases

Set them under resolve.alias. Each key is matched as a prefix and replaced with a path (relative to root, or absolute):

import { defineConfig } from "vantris";

export default defineConfig({
  resolve: {
    alias: {
      "@": "./src",
      "~": "./shared",
    },
  },
});

Now these all resolve through the alias:

import { thing } from "@/thing";        // JS/TS  → ./src/thing

@import "@/styles/base.css";             /* CSS   → ./src/styles/base.css */
background: url("@/images/hero.png");

<link rel="icon" href="@/favicon.svg" /> <!-- HTML → ./src/favicon.svg -->

Zero-config: tsconfig.json fallback

When resolve.alias is omitted entirely, Vantris falls back to your tsconfig.json: compilerOptions.paths (resolved against baseUrl) become your aliases. So this alone gives you @/* with no config file:

// tsconfig.json
{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}

import { thing } from "@/thing"; // works with zero Vantris config

This is the recommended setup for a TypeScript project — you define aliases once, and both the TypeScript language server and Vantris agree on them.

Explicit config wins

An explicit resolve.alias in vantris.config.ts always takes precedence. The tsconfig fallback only applies when resolve.alias is not set at all — it's all-or-nothing, not a merge. If you define even one alias in the config, the tsconfig paths are ignored.

How matching works

• Keys match as a prefix. "@": "./src" turns @/a/b into ./src/a/b.
• The tsconfig form ("@/*": ["./src/*"]) uses the standard wildcard mapping.
• Longer, more specific keys should be listed so they win over shorter ones when both could match.

resolve: {
  alias: {
    "@/components": "./src/components", // more specific
    "@": "./src",                        // fallback
  },
}

Where aliases apply

Context	Example
JS/TS	import x from "@/x"
CSS	@import "@/base.css", url("@/a.png")
HTML	<img src="@/logo.svg">

Because it's one resolver, there's no chance of an alias resolving in your JS but not your CSS.

Aliases vs. the public/ directory

Aliases resolve to files under your source that get processed and hashed. public/ is for files served verbatim at a fixed URL. Reach for an alias when you're importing app code/assets; reach for public/ when you need a stable, unhashed URL.