#Page reload and hot module replacement (HMR)

Keep development fast by using the lightest update strategy for each file change.

Need fast feedback after each file change? Extension.js chooses the safest and fastest update path automatically:

• HMR when module updates are safe
• Hard extension reload when runtime-critical assets change
• Restart-required errors/warnings when entrypoint structure changes

#Reload prerequisites (DevTools setup dialog)

Before evaluating reload behavior, confirm the same setup checks shown in the Extension.js DevTools Confirm setup dialog:

If either step is missing, reload behavior can appear inconsistent even when the build pipeline is healthy.

#Reload tiers

#1) Hot module replacement (fastest path)

HMR is used when code can update without restarting extension runtime wiring.

Common examples:

• Scripts attached to extension HTML pages (accept updates through injected HMR wrappers)
• Background script modules in non-service-worker flows
• User script API script flows
• CSS updates in content-script/runtime wrappers where supported

#2) Hard extension reload

Some file changes require reloading the extension runtime itself.

Typical hard-reload triggers:

• manifest.json
• _locales/**.json
• Service worker/background runtime-critical changes
• Content script output changes (browser runner enforces extension reload for consistency)

Extension.js applies browser-specific hard reload mechanisms internally (Chromium and Firefox flows differ under the hood), but behavior is unified at the CLI/user level.

#3) Restart required (dev server)

When extension entrypoint references change (instead of just module contents), Extension.js reports restart-required diagnostics so you do not continue with a stale graph.

Typical restart-required scenarios:

• Manifest script entrypoint list changes
• HTML entrypoint script/style references change
• pages/ / scripts/ file set changes in watch mode (especially removals)

#Behavior matrix

#Reloading scripts and HTML outside the manifest

pages/ and scripts/ follow the same reload strategy as manifest-declared assets.

• Existing module updates can use hot-update paths.
• Entrypoint set changes (add/remove or reference graph changes) may require restart.

Example:

pages/
└── extra-page.html
scripts/
└── extra-script.js

Note: The /pages and /scripts folders are special folders recognized by Extension.js for hot-reloading. Each entry in these folders is treated as a separate page or script that can be reloaded independently.

#Best practices

• Keep entrypoint references stable during active dev sessions to maximize HMR.
• Batch manifest.json and locale edits to avoid repeated hard extension reloads.
• Use pages/ and scripts/ for off-manifest assets, then restart when file sets or entry wiring changes.
• Treat restart-required diagnostics as intentional safety checks, not transient warnings.

#Next steps

• Review off-manifest asset flows in special folders.
• Understand structural update outcomes in dev update behavior.