Build Options

The build block configures the production build — minification, source maps, output naming, directory cleanup, and library mode. The underlying bundler (Rolldown) is an internal detail and is never exposed: there is no rolldownOptions escape hatch.

For a task-oriented guide, see Building for Production.

import { defineConfig } from "vantris";

export default defineConfig({
  build: {
    minify: true,
    sourcemap: false,
    emptyOutDir: true,
    assetsDir: "assets",
    entryFileNames: "assets/[name]-[hash].js",
    chunkFileNames: "assets/[name]-[hash].js",
    assetFileNames: "assets/[name]-[hash][extname]",
    // lib: { ... }
  },
});

• build.minify
• build.sourcemap
• build.emptyOutDir
• build.assetsDir
• build.entryFileNames
• build.chunkFileNames
• build.assetFileNames
• build.lib
  • LibConfig
• Types
  • ChunkInfo
  • AssetInfo
• Reserved for future versions

build.minify

• Type: boolean
• Default: true

Minify the output. Turn it off to inspect readable build output.

build: { minify: false }

build.sourcemap

• Type: boolean | "inline" | "hidden"
• Default: false

Source map strategy — covers JavaScript, TypeScript, and CSS.

Value	Result
false	No source maps.
true	Separate .map files + a //# sourceMappingURL comment.
"inline"	Map appended to each file as a data URL.
"hidden"	Separate .map files, no comment.

build: { sourcemap: true }

build.emptyOutDir

• Type: boolean
• Default: true

Empty the output directory before building. The clean is guarded so it can never remove anything outside outDir.

build: { emptyOutDir: false } // keep existing files (rare)

build.assetsDir

• Type: string
• Default: "assets"

Directory (relative to outDir) for built chunks and assets. It's used to derive the default *FileNames patterns below — change it and the defaults follow.

build: { assetsDir: "static" }
// → entryFileNames defaults to "static/[name]-[hash].js"

build.entryFileNames

• Type: string | ((chunk: ChunkInfo) => string)
• Default: `${assetsDir}/[name]-[hash].js`

Naming pattern for entry chunks. A string with [name], [hash], [ext], [extname] placeholders, or a function receiving ChunkInfo.

build: { entryFileNames: "js/[name]-[hash].js" }

build: { entryFileNames: (chunk) => `js/${chunk.name}.[hash].js` }

build.chunkFileNames

• Type: string | ((chunk: ChunkInfo) => string)
• Default: `${assetsDir}/[name]-[hash].js`

Naming pattern for shared/dynamic chunks (code splitting). String or a function receiving ChunkInfo.

build.assetFileNames

• Type: string | ((asset: AssetInfo) => string)
• Default: `${assetsDir}/[name]-[hash][extname]`

Naming pattern for emitted assets (images, fonts, …). String or a function receiving AssetInfo.

build: { assetFileNames: (asset) => `media/${asset.names[0]}` }

build.lib

• Type: LibConfig
• Default: unset

Build a library instead of an HTML application. When set, the HTML pipeline is skipped and the entry is emitted in each requested format. See Library Mode.

build: {
  lib: {
    entry: "./src/index.ts",
    name: "MyLibrary",
    formats: ["esm", "cjs", "iife"],
  },
}

LibConfig

Field	Type	Default	Description
entry	string	—	Entry module (relative to root/absolute).
name	string	—	Global name — required for iife.
formats	("esm" | "cjs" | "iife")[]	["esm", "cjs"]	Formats to emit, one file each.
fileName	string | ((format: LibFormat) => string)	entry base name	Output name (extension derived per format).

Extensions per format: .mjs (esm), .cjs (cjs), .iife.js (iife).

Types

ChunkInfo

Passed to a entryFileNames/chunkFileNames function — a Vantris-owned, stable subset of the bundler's pre-render data:

interface ChunkInfo {
  name: string;              // chunk name used in naming patterns
  isEntry: boolean;          // static entry chunk?
  isDynamicEntry: boolean;   // dynamic-import entry chunk?
  facadeModuleId: string | null; // absolute id of the module this chunk represents
  moduleIds: string[];       // absolute ids of the modules included
  exports: string[];         // names exported by this chunk
}

AssetInfo

Passed to an assetFileNames function:

interface AssetInfo {
  names: string[];             // candidate names for the asset
  originalFileNames: string[]; // absolute paths of the source files
}

Reserved for future versions

The interface is shaped to grow without breaking existing configs. Options like target, manifest, and build plugins are declared as a contract in the source but not yet active. There will never be a rolldownOptions escape hatch — new output options are added as first-class, Vantris-typed fields.