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:Documentation Index
Fetch the complete documentation index at: https://extension.js.org/llms.txt
Use this file to discover all available pages before exploring further.
- HMR (hot module replacement) 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:| Setup step | Why it matters for reload/HMR |
|---|---|
Enable Developer mode in chrome://extensions | Ensures that extension runtime updates (including service worker changes) apply reliably during development. |
| Accept the local network access prompt for content scripts | Content-script reload workflows need this when the browser requests network permission. |
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) 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 (the Extension.js browser runner enforces extension reload for consistency)
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.
3) Restart required (dev server)
When extension entrypoint references change (not just module contents), Extension.js reports restart-required diagnostics. This prevents you from continuing with a stale dependency 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
| Change type | Default behavior |
|---|---|
| JS/CSS module updates in existing entries | HMR where supported |
manifest.json / locales / service-worker-critical updates | Hard extension reload |
| Entrypoint structure updates (manifest lists, HTML script/style refs) | Restart required |
pages/ or scripts/ file add/remove during watch | Warning/error with restart guidance |
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.
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.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, 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.