Dev update behavior#

Keep iteration fast by knowing which changes hot-update and which changes require a restart. Extension.js picks the lightest safe update mode per file change.

Update modes#

Mode	What happens	Typical impact
HMR	Module/style updates apply in-place	Fastest iteration, no full extension relaunch
Hard reload	Extension runtime is reloaded in the target browser	Extension context restarts, but dev process keeps running
Restart required	Compile-time diagnostic asks you to restart extension dev	Needed for structural entrypoint/list changes

Example change outcomes#

Common examples#

Change	Expected behavior
Edit content script/component code	HMR/remount path (when supported)
Edit style imports used by content scripts/pages	HMR-style update path (context-dependent)
Edit manifest.json values (non-structural)	Hard reload flow
Add/remove manifest entrypoint references	Restart required
Add/remove pages/ or scripts/ entry files	Restart required
Edit _locales/*/messages.json	Hard reload flow

What to do when restart is required#

When Extension.js reports Restart required, stop the current extension dev process and start it again before continuing.

Typical triggers:

• Adding or removing manifest entrypoint references
• Adding or removing files under pages/ or scripts/ used as extension entry files
• Structural script/style entry changes in HTML entrypoints

Practical guidance#

• Prefer editing existing modules/assets during active dev sessions for fastest feedback.
• Batch structural manifest changes (entrypoint list edits) so you restart once.
• Treat restart required diagnostics as authoritative; continuing without restart can leave stale runtime state.

Related pages#

• manifest.json
• content scripts
• background scripts / service worker
• HTML