Live Preview
Last updated:
How the WebSandbox live preview works — the Service Worker proxy, hot-module replacement, and the multi-device preview panel.
Overview
The preview pane is a sandboxed <iframe> that communicates with the dev server running inside the WebContainer via the Service Worker proxy. Because the entire execution pipeline is local to your browser, previews are:
- Instant — no network round-trip to a remote VM
- Private — your application is never exposed to the public internet unless you explicitly share it
- Fully functional — cookies, localStorage, fetch calls to the same origin, WebSockets — everything works as in a real browser tab
How Preview Works
When your dev server starts inside the WebContainer, it binds to a virtual port. The WebContainer emits a server-ready event with the URL. WebSandbox intercepts this event and points the preview iframe at that URL.
The Service Worker intercepts every request the iframe makes to that origin and routes it through the WebContainer's network layer, which forwards the request to your in-container server and returns the response. From the iframe's perspective, it is talking to a real HTTP server.
Hot Module Replacement
HMR is handled entirely by your framework's dev server (Vite, Next.js, Webpack, etc.). The WebContainer's virtual networking layer proxies the WebSocket connection that HMR uses to push updates to the browser.
This means HMR works out of the box for any framework that supports it — no special configuration needed. When you save a file, the HMR update arrives in the preview iframe in milliseconds.
For frameworks without HMR support, WebSandbox falls back to a full iframe reload on file save.
Preview Panel
The preview panel toolbar provides:
- Address bar — shows the current preview URL and supports manual navigation to specific routes
- Reload button — force-reloads the preview iframe without restarting the dev server
- Responsive viewport selector — toggle between Desktop, Tablet (768px), and Mobile (375px) widths to test responsive layouts
- Open in new tab — opens the preview in a full browser tab (see below)
- Console errors badge — a red dot appears when the preview iframe emits uncaught errors; click to expand the error list
Opening in a New Tab
Click the Open in new tab button to navigate to the preview URL in a full browser tab. The same Service Worker proxy handles the traffic — you get the full browser DevTools experience while still connected to the in-container dev server.
Note: the preview URL is a local Service Worker-intercepted URL (e.g., https://workspace-id.local.websandbox.dev). It is not publicly accessible — the URL only works in the same browser profile that has the Service Worker registered.