Live preview

The live preview is the emulated browser in the right column, where your extension runs as you edit it. Reach for it to open the popup, drive a content script on a sample page, and watch the background worker, without installing anything.

Quick start

preview-open popup
preview-errors

Type those in the terminal after a build. The popup opens in the preview, and preview-errors prints the build status, the surfaces that are ready, and the reload class that ran last.

How it works

What runs in the preview

The preview reads manifest.json and runs each surface it declares. Content scripts run on a sample host page and on six fixture pages the preview serves itself, so nothing is fetched from the internet.

Surface	Manifest key
Popup	action.default_popup
Options page	options_ui.page
Side panel	side_panel.default_path
DevTools panel	devtools_page
New tab page	chrome_url_overrides.newtab
History and bookmarks overrides	chrome_url_overrides.history and chrome_url_overrides.bookmarks
Content scripts	content_scripts[].js
Background worker	background.service_worker

What an edit reloads

Every write compiles on its own after a short wait, and the preview reloads only what the build changed. It reads which artifacts changed bytes and chooses one of four classes. preview-errors names the class on a Reload: line:

Build: success
Surfaces ready: popup
Reload: worker (service_worker (background.js))

• frame. A surface changed: its page, or a script or stylesheet it loads. Only that surface remounts. An open popup stays open and is reborn in place.
• content. A content script changed. The sample host page reloads and the new script is injected into the fresh document.
• worker. The background service worker changed. The worker restarts, the popup closes and its ports disconnect, and the sample host page reloads so the content scripts the new worker talks to are its own.
• full. manifest.json or _locales/ changed, or a file only the manifest names, such as an icon. Everything reloads on a fresh session.

A worker restart and a full reload clear the action badge and title, the way Chrome does on a reload.

Two chosen differences from Chrome

Chrome has no worker-only restart. A reload tears the whole extension down, closes every extension page including an open popup, and leaves the old content script orphaned in a tab that is still open. The preview keeps the popup open on a frame reload, so you can watch it change as you edit it, and reloads the sample host page on a worker restart. Both differences are written down in the emulator's parity record, measured on Chrome 143.

The wait before a build

The workbench waits 150 ms after a lone terminal write and 500 ms after a burst. A second write landing inside the open wait makes it a burst and resets the wait to 500 ms, so a chain of writes lands as one cycle. build skips the wait and compiles now.

Browser profile

Each preview starts on a fresh browser profile, which is what a local dev run does by default. Anything the extension writes to storage is gone when the preview closes. Settings has a Browser profile card with one toggle: Keep this project's browser profile keeps storage between runs, and Discard it when the preview closes returns to the default. A kept profile also offers Start clean. The change takes effect the next time the preview starts.

Where the preview is faithful

The preview is faithful within these bounds, and the preview's own limitations panel lists them. Confirm each one against a real unpacked load.

Capability	In the preview
Offscreen documents	Tracked, but their scripts do not run
Camera and screen capture	No synthetic stream for getUserMedia or getDisplayMedia
Web auth	launchWebAuthFlow captures same-origin auto-redirects only
Native messaging	Answered by an echo host; real hosts report as not found
Request filtering	declarativeNetRequest and webRequest emulated for declared hosts only
JS dialogs	alert, confirm and prompt appear as your own browser's dialogs

Reference

Limit	Value
Wait after a lone write	150 ms
Wait after a burst of writes	500 ms
Reload classes	frame, content, worker, full
Fixture pages for content scripts	6
Browser profile default	Discarded when the preview closes

When it fails

• The popup closed while you edited the background worker. That is the worker class. The worker restarts and the popup closes the way Chrome closes it. Run preview-open popup again.
• Storage is empty every time the preview restarts. The profile is discarded by default. Switch to Keep this project's browser profile in Settings.
• A capture, auth or native messaging flow never completes. It is one of the scoped capabilities above. Prove it on a real browser with Download and run locally.
• An icon change did not show. A file only the manifest names triggers a full reload. Wait for the Reload: full line, then look again.

Next

• Terminal for the preview-* commands that read and drive the preview
• Build console for the build status under the preview
• Firefox engine for a real Gecko beside the emulator
• Select to edit for pointing a prompt at an element