Skip to main content
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 (hot module replacement) when module updates are safe
  • Classified reloads (full, service worker, content scripts, or notify-only page) when runtime assets change
  • An automatic compiler restart 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 you skip either step, reload behavior can appear inconsistent even when the build pipeline is healthy.

Reload tiers

1) Hot module replacement (fastest path)

Extension.js uses HMR when code can update without restarting the extension’s background processes and event listeners. Common examples:
  • Scripts attached to extension HTML pages (accept updates through injected HMR wrappers)
  • Background script modules in non-service-worker flows
  • Scripts registered via the userScripts API
  • CSS updates in content-script/runtime wrappers where supported
From the release after 4.1.41, the hot update code for pages goes only into the scripts that a page names. It is left out when React, Vue, or Svelte handles refresh.

2) Classified reloads

When a change needs more than HMR, Extension.js classifies it into one of four reload kinds: The decision comes from the compiler’s chunk graph, not from filenames, and follows a fixed order:
  1. Forced full. A change to manifest.json or anything under _locales/ always classifies as full, no matter what else changed.
  2. Chunk membership. Extension.js looks up which chunks contain each changed source. A source in a background/ chunk means service-worker. A source in a content_scripts/ chunk means content-scripts.
  3. Changed static asset. Some changed files exist in the output directory but belong to no chunk: an icon, a web-accessible resource, a DNR ruleset. These force full, so the browser re-reads them from disk.
  4. Name heuristics. Only for sources the chunk graph does not know: paths matching background or service worker patterns classify as service-worker.
  5. Content fallback. If the manifest declares content scripts, remaining unknown changes re-inject every content-script entry.
  6. Notify-only page. Everything else is a page instruction: livereload owns the refresh, and the reload announcement still fires.
A source that lives in both a service-worker chunk and a content-script chunk fans out to both paths. One save triggers the SW restart and carries the stale content-script entries for re-injection, in a single classified instruction. Each dev reload is announced with a single context label built by the dev server. The format is context (fileA, fileB +2 more), for example service_worker + content_script (shared/api.ts). The same label appears verbatim in CLI stdout, in the page devtools console, and in the devtools pill, so you can correlate a reload across all three without guessing.
If the browser serves a stale cached service worker after a reload, the dev server detects the version mismatch and resynchronizes the extension automatically. You should not need to manually remove and re-add the extension to recover. A full or service-worker reload restarts the extension. The dev session prints a warning when the extension confirms that reload and does not reconnect within 15 seconds. The line says that the extension has not come back since, so this edit may not be live. Reload the extension from the browser. Needs the release after 4.1.39. A slow restart is not a lost one. When the extension reconnects after that warning, the session prints one more line. is back after 22s, so this edit is live. Nothing to reload. means the worker runs the current build. If the worker returns on an earlier build, the line says that the edit is not live and asks you to reload the extension from the browser.
Why do content script filenames include hashes in dev? Chrome aggressively caches chrome-extension:// resources. A stable filename like content-0.js can serve stale code even after a full extension reload. Extension.js appends a short build hash in development (for example, content-0.abcd1234.js). Each rebuild produces a fresh URL that bypasses the cache. Production builds use clean names. Set hashContentScripts: false under commands.dev in extension.config.* to opt out and keep stable dev filenames. A top-level key of the same name is ignored.

3) Compiler restart (dev server)

When extension entrypoint references change (not just module contents), the dev session restarts its compiler by itself and reloads the extension. You do not restart the command. The session restarts for these changes:
  • A manifest edit that adds, removes, or renames a script, page, icon, or JSON entry
  • A change to the script or style references of an HTML entrypoint
  • A file added under pages/ or scripts/
  • A change to an .env file
From the release after 4.1.41, the session also restarts when a file under pages/ or scripts/ is deleted or renamed, and when a script moves to another manifest key. The restart removes the outputs of entries that are gone. From the release after 4.1.41, the session also restarts when a page script or stylesheet that was missing at startup is created. A live session restarts by itself. One change still needs a restart by you: an edit to extension.config.*. The session keeps the config that it read at startup and prints a warning. Stop the session and run extension dev again.

Behavior matrix

Safari

The tiers above are the Chromium and Gecko reload paths. From 4.1.20, a Safari dev session updates by a different route. Each save rebuilds dist/safari, resyncs the app’s resources with an incremental xcodebuild, and reloads the extension in Safari. Measured on Safari 26.5.2, that is roughly 4 seconds from save to reloaded extension, with no HMR tier. See Building Safari extensions.

How the dev runtime gets injected

The reload plugin instruments your build in five injection steps, then prunes:
  1. Strip the dev-server runtime from content-script chunks, which cannot host it.
  2. Set up the reload strategy on the background and content-script entries.
  3. Inject the service-worker scripts-replay shim, so /scripts/* injections re-run on edit.
  4. Inject the bridge producer, so the background forwards console output to the control channel.
  5. Inject the bridge relay, so content-script console output reaches the same channel.
Afterward, a pruning step manages hot/. Hot-update chunks are fetched from disk on the extension origin, so stale generations would accumulate in what ships. Extension.js keeps the current generation plus one previous generation for in-flight fetches, and deletes the rest after every compile. The whole pipeline is development-only. It is a no-op in production builds and when you pass --no-reload.

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) restart the session’s compiler.
Example:
Extension.js recognizes the /pages and /scripts folders for hot-reloading and treats each entry as a separate page or script it can reload independently.
Scripts you inject programmatically with chrome.scripting.executeScript from /scripts/* are replayed on edit. When you change a file under /scripts/, Extension.js re-runs the same injection on the same tab and tears down the previous mount, so dynamically injected scripts update live, the way declarative content_scripts do, instead of leaving stale DOM until you manually re-trigger the call. This is a dev-only convenience.
From the release after 4.1.39, the replay also works on Firefox. An edit to a file that you inject with scripting.executeScript runs the new text in the open tabs. When the edit reloads no page, the terminal says so:

What the browser console says

From the release after 4.2.0, a line that the dev runtime prints in a browser console for a failure or a warning opens with a code from the error code table:
  • W_RELOAD_NOT_APPLIED: a reload or a hot update did not land, so the open page or extension keeps the build it has.
  • W_CONTENT_SCRIPT_NOT_INJECTED: in the background console, the background could not answer a page that asks for its content script, so that page runs without it.
  • W_DEV_SERVER_SOCKET: an extension page lost its socket to the dev server, so edits show after the page is reloaded.
  • W_CONTENT_SCRIPT_CLEANUP: in the page console, the cleanup function that a content script returned threw, so what the script left on the page may stay.
  • W_CONTENT_SCRIPT_MOUNT: in the page console, the default export of a content script threw when it ran.
A line that only informs, such as [Extension.js] Reloading <label>…, carries no code. Releases up to 4.2.0 printed these failures as Extension.js: <text>, with no code.

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.
  • Treat restart required diagnostics as intentional safety checks, not transient warnings.

Next steps