Library Mode

Library mode bundles a single entry into one or more distribution formats in a single build, instead of building an HTML application. It's how you ship a package on npm rather than deploy a site.

Enable it by setting build.lib:

import { defineConfig } from "vantris";

export default defineConfig({
  build: {
    lib: {
      entry: "./src/index.ts",
      name: "MyLibrary",                // required for the "iife" global
      formats: ["esm", "cjs", "iife"],  // default: ["esm", "cjs"]
      // fileName: "my-library",        // default: the entry's base name
    },
  },
});

When build.lib is set, the HTML pipeline is skipped entirely — Vantris does not look for index.html. The module graph is built once and written once per format.

Formats

Format	Extension	Use
esm	.mjs	Modern bundlers and Node ESM (import).
cjs	.cjs	Node CommonJS (require).
iife	.iife.js	A <script> tag global — needs name.

The default is ["esm", "cjs"]. Add "iife" when you want a browser global.

entry

The module to bundle, relative to root or absolute:

lib: { entry: "./src/index.ts" }

name — the IIFE global

Required for the iife format (a browser global needs a name); ignored by esm/cjs. Consumers reach your library as window.MyLibrary:

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

<script src="my-library.iife.js"></script>
<script>
  MyLibrary.doThing();
</script>

fileName

The output file name without extension — the extension is derived per format (.mjs, .cjs, .iife.js). Defaults to the entry file's base name. It can be a function of the format:

lib: {
  entry: "./src/index.ts",
  fileName: (format) => `my-library.${format}`,
}

Recommended package.json

Point the standard entry fields at the built formats so both ESM and CommonJS consumers resolve correctly:

{
  "name": "my-library",
  "type": "module",
  "files": ["dist"],
  "main": "./dist/index.cjs",
  "module": "./dist/index.mjs",
  "types": "./dist/index.d.ts",
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "import": "./dist/index.mjs",
      "require": "./dist/index.cjs"
    }
  },
  "scripts": {
    "build": "vantris build"
  }
}

Type declarations

Vantris bundles JavaScript. Emit your .d.ts files with tsc (tsc --emitDeclarationOnly) or a declaration bundler, and point types/exports.types at the result.

Externalising dependencies

A library usually should not inline its runtime dependencies — consumers install those alongside it. List them under dependencies/peerDependencies in package.json, and keep your bundle focused on your own code. (Bare imports that aren't part of your source stay as imports in the output.)

Options recap

Option	Type	Default	Notes
entry	string	—	Required. Relative to root/absolute.
name	string	—	Required for iife.
formats	("esm" | "cjs" | "iife")[]	["esm", "cjs"]	One file per format.
fileName	string | ((format) => string)	entry base name	Extension added per format.

See the Build Options reference for the exact types.