Performance & Caching

Last updated: June 1, 2026

How WebSandbox achieves sub-2-second boot times — WASM caching, boot deduplication, and the Dexie async queue.

Note: Performance for Cloud Servers depends on the allocated VM resources and network latency to the cloud region. The caching and boot strategies below apply exclusively to in-browser Instant Projects.

Boot Time Targets

Our Q1 2026 performance benchmarks (Chrome 124, M2 MacBook Air, 100 Mbps connection):

WASM Binary Caching

The WebContainer WASM binary is the largest asset downloaded on first load (~15 MB compressed). WebSandbox uses two caching layers:

1. HTTP cache — the binary is served with a long Cache-Control: immutable header. Once downloaded, the browser caches it indefinitely until a new version is released.
2. Service Worker cache — the SW pre-caches the binary on install, making it available even when the CDN is offline.

On subsequent visits, the WASM binary loads from the Service Worker cache at memory bandwidth speeds — effectively instant.

Boot Deduplication

WebContainer.boot() must only be called once per browser context. Calling it a second time throws an error. WebSandbox uses a module-level singleton promise to deduplicate boot calls:

// Simplified internal implementation
let bootPromise: Promise<WebContainer> | null = null;

export function getWebContainer(): Promise<WebContainer> {
  if (!bootPromise) {
    bootPromise = WebContainer.boot();
  }
  return bootPromise;
}

This ensures that even if multiple components call getWebContainer() concurrently during workspace initialisation, the boot sequence runs exactly once.

File System Performance

File writes are debounced before being persisted to IndexedDB to avoid flooding the database with writes on every keystroke. The debounce window is 300ms for text files and 1s for binary files.

For optimal performance:

• Keep node_modules out of your tracked files — it is excluded from the IndexedDB snapshot by design
• Avoid storing large binary assets (>10 MB each) directly in the workspace file system; use CDN URLs instead
• Use .gitignore to exclude generated build output from the workspace snapshot

npm Install Caching

npm install runs inside the WebContainer and is subject to the in-container network (proxied via the browser's fetch API). To speed up repeated installs:

• WebSandbox maintains an in-memory npm cache between installs in the same session — packages already downloaded in one terminal session are available instantly in subsequent ones
• Lock files (package-lock.json) are committed to the workspace and used by npm to skip resolution for unchanged dependencies

Measuring Performance

You can inspect workspace boot timing in the browser DevTools:

1. Open DevTools → Performance tab
2. Start recording before navigating to your workspace URL
3. Look for the WebContainer.boot and wc:mount custom performance marks in the timeline

WebSandbox emits performance.mark() entries at key boot milestones, making it easy to identify bottlenecks in custom configurations.