- 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
userScriptsAPI - CSS updates in content-script/runtime wrappers where supported
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:
- Forced full. A change to
manifest.jsonor anything under_locales/always classifies asfull, no matter what else changed. - Chunk membership. Extension.js looks up which chunks contain each changed source. A source in a
background/chunk meansservice-worker. A source in acontent_scripts/chunk meanscontent-scripts. - 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. - Name heuristics. Only for sources the chunk graph does not know: paths matching
backgroundorservice workerpatterns classify asservice-worker. - Content fallback. If the manifest declares content scripts, remaining unknown changes re-inject every content-script entry.
- Notify-only page. Everything else is a
pageinstruction: livereload owns the refresh, and the reload announcement still fires.
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.
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 cacheschrome-extension://resources. A stable filename likecontent-0.jscan 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. SethashContentScripts: falseundercommands.devinextension.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/orscripts/ - A change to an
.envfile
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 rebuildsdist/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:- Strip the dev-server runtime from content-script chunks, which cannot host it.
- Set up the reload strategy on the background and content-script entries.
- Inject the service-worker scripts-replay shim, so
/scripts/*injections re-run on edit. - Inject the bridge producer, so the background forwards console output to the control channel.
- Inject the bridge relay, so content-script console output reaches the same channel.
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.
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.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.
[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.jsonand locale edits to avoid repeated hard extension reloads. - Use
pages/andscripts/for off-manifest assets. - 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.

