Dependency Pre-Bundling

Vantris bundles your bare (node_modules) dependencies on demand and caches them — zero config, you never list them. Two options, optimizeDeps.include and optimizeDeps.exclude, tune the behaviour, à la Vite.

Why pre-bundle at all?

Two reasons, same as Vite:

1. CommonJS → ESM. Many npm packages still ship CommonJS. Browsers can't import CommonJS, so Vantris bundles those packages into ESM with correct named exports — import { useState } from "react" works even though React is CJS. Subpath imports (react-dom/client) work too.
2. Fewer requests. A package like lodash-es is hundreds of internal modules. Serving each one as a separate request would flood the browser. Pre-bundling collapses a dependency into a few files.

On-demand by default

The first time a bare import is requested, Vantris bundles that package and caches the result in node_modules/.vantris/deps/. Subsequent requests hit the cache. You don't configure anything — it just happens.

import { render } from "react-dom/client"; // bundled on first request, then cached

optimizeDeps.include — pre-bundle at startup

Listing packages under include bundles them when the dev server starts, so they're ready before the first request — no first-import pause. Everything else is still bundled on demand, so this list is purely a warm-up hint; you only name the deps you want ready ahead of time. Subpaths are allowed.

import { defineConfig } from "vantris";

export default defineConfig({
  optimizeDeps: {
    include: ["react", "react-dom/client"],
  },
});

Use it for your app's core, always-used dependencies — the ones you'd otherwise pay a small bundling cost for on the very first page load. (The @vantris/react plugin seeds this list with the React packages automatically.)

optimizeDeps.exclude — serve as native ESM

Listing a package under exclude serves it straight from node_modules as native ESM, skipping the optimizer entirely. Matched by package name — every subpath of a listed package is excluded too.

export default defineConfig({
  optimizeDeps: {
    exclude: ["some-esm-only-lib"],
  },
});

Only pure-ESM packages qualify

exclude only makes sense for packages that are already valid ESM the browser can load directly. A listed package that turns out to be CommonJS can't run natively in the browser, so Vantris bundles it anyway and logs a warning.

Reach for exclude when a package is pure ESM and you'd rather the browser load it directly — for instance a large library you're actively debugging and want to step through unbundled.

DevTools integration

Modules served from /@vantris/deps/ are marked third-party, so Chrome DevTools greys them out in the Sources panel and skips them while stepping — the same treatment Vite gives its pre-bundled deps. Your own source stays in focus while debugging.

Where the cache lives

Pre-bundled dependencies live in node_modules/.vantris/deps/. It's part of the internal cache: transparent, self-invalidating, and never in your project root. Deleting it just forces a re-bundle on the next run.

Options recap

export default defineConfig({
  optimizeDeps: {
    include: ["react", "react-dom/client"], // pre-bundle at startup (warm cache)
    exclude: ["some-esm-only-lib"],          // serve as native ESM, no bundling
  },
});

Option	Type	Effect
include	string[]	Pre-bundle these at startup. Subpaths allowed.
exclude	string[]	Serve these as native ESM (pure-ESM only). Matched by name.

See the optimizeDeps Options reference for the exact types.