Performance

Architecture Overview

Vanilla Breeze uses a modular loading architecture. Instead of shipping one monolithic bundle, the framework splits into focused layers that load on demand:

Core CSS + Core JS          ← every page (88 KB gzip)
├── Extras JS               ← on demand (niche components)
├── Theme CSS               ← on demand (one at a time)
├── Charts CSS              ← on demand (data viz pages)
├── Dev CSS + Dev JS        ← on demand (debug only)
└── Service Worker          ← opt-in caching layer

Full CSS + Full JS          ← backwards-compat single bundle

The core bundles contain the base styles, layout primitives, native element styles, custom elements, and essential web components. The full bundles include everything (all themes, all components) for zero-config setups.

Bundle Inventory

Every CDN artifact with raw, gzip, and brotli sizes. Data from the latest build.

Loading Strategies

Core only (recommended)

The smallest footprint. Includes base styles, layout, native element styles, and core web components.

<link rel="stylesheet" href="/cdn/vanilla-breeze-core.css">
<script type="module" src="/cdn/vanilla-breeze-core.js"></script>

Core + Extras

Adds niche components (emoji picker, geo map, data table, etc.) as a separate bundle.

<link rel="stylesheet" href="/cdn/vanilla-breeze-core.css">
<script type="module" src="/cdn/vanilla-breeze-core.js"></script>
<script type="module" src="/cdn/vanilla-breeze-extras.js"></script>

Full bundle

Everything in one file. Simplest to set up, largest download.

<link rel="stylesheet" href="/cdn/vanilla-breeze.css">
<script type="module" src="/cdn/vanilla-breeze.js"></script>

Autoloader

Only loads components as they appear in the DOM. Best for pages that use few components.

<link rel="stylesheet" href="/cdn/vanilla-breeze-core.css">
<script type="module" src="/cdn/vanilla-breeze-autoload.js"></script>

Add-ons

Charts, dev tools, and themes are loaded separately when needed.

<!-- Charts (data visualization) -->
<link rel="stylesheet" href="/cdn/vanilla-breeze-charts.css">

<!-- Dev tools (debug overlays, wireframe) -->
<link rel="stylesheet" href="/cdn/vanilla-breeze-dev.css">
<script type="module" src="/cdn/vanilla-breeze-dev.js"></script>

<!-- Individual theme -->
<link rel="stylesheet" href="/cdn/themes/ocean.css">

Budget Policy

Every CDN artifact has a gzip size budget defined in scripts/bundle-budget.config.json. The npm run budget script checks all artifacts against their budgets and fails with exit code 1 if any are exceeded.

This check runs in CI as part of the quality gate, blocking deployment if bundle sizes regress beyond their budgets.

Current budgets

Core CSS

48 KB gzip

Core JS

50 KB gzip

Full CSS

90 KB gzip

Full JS

76 KB gzip

Extras JS

29 KB gzip

Individual themes

4 KB gzip each

Individual components

10 KB gzip each

Service Worker

Vanilla Breeze includes an opt-in service worker for offline caching. It uses stale-while-revalidate for theme CSS and optional modules, and precaches core bundles on install.

Opt in

Add a meta tag to enable caching:

<meta name="vb-service-worker" content="true">

Or set a global flag before importing:

<script>window.__VB_SERVICE_WORKER = true;</script>
<script type="module" src="/cdn/vanilla-breeze-core.js"></script>

Cache versioning

The service worker names its cache using the build version (e.g., vb-0.1.0). When a new version deploys, the old cache is automatically pruned during activation.

Cache management

The service worker supports a message channel for programmatic cache control:

import { getSWStatus, clearSWCache, checkForUpdate } from 'vanilla-breeze/lib/sw-register.js';

// Get cache status
const status = await getSWStatus();
// { version: '0.1.0', cacheName: 'vb-0.1.0', cachedURLs: [...] }

// Clear all VB caches
await clearSWCache();

// Check for updates
const { updated } = await checkForUpdate();

The settings panel includes a System section with cache management controls when the service worker is active.