Skip to main content
Keep iteration fast by knowing which changes apply instantly and which require a restart. Extension.js picks the lightest safe update mode per file change.

​
Update modes

ModeWhat happensTypical impact
Hot module replacement (HMR)Module/style updates apply in-placeFastest iteration, no full extension relaunch
Hard reloadThe target browser reloads the extension runtimeExtension context restarts, but dev process keeps running
Restart requiredCompile-time diagnostic asks you to restart extension devNeeded for structural entrypoint/list changes

​
Common examples

ChangeExpected behavior
Edit content script/component codeHMR/remount path (when supported)
Edit style imports used by content scripts/pagesHMR-style update path (context-dependent)
Edit manifest.json values (non-structural)Hard reload flow
Add/remove manifest entrypoint referencesRestart required
Add/remove pages/ or scripts/ entrypointsRestart required
Edit _locales/*/messages.jsonHard reload flow

​
What to do when you need to restart

When Extension.js reports Restart required, stop and rerun extension dev before continuing. Typical triggers:
  • Adding or removing manifest entrypoint references
  • Adding or removing files under pages/ or scripts/ used as extension entrypoints
  • 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 your runtime in a stale state.