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

    ModeWhat happensTypical impact
    HMRModule/style updates apply in-placeFastest iteration, no full extension relaunch
    Hard reloadExtension runtime is reloaded in the target browserExtension context restarts, but dev process keeps running
    Restart requiredCompile-time diagnostic asks you to restart extension devNeeded for structural entrypoint/list changes

    Example change outcomes

    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/ entry filesRestart required
    Edit _locales/*/messages.jsonHard 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.