> ## 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.

# Dev mode update and reload behavior

> Know which file changes hot-update and which require a restart during development. Extension.js chooses the lightest safe update mode automatically.

Keep iteration fast by knowing which changes apply instantly and which require a restart. Extension.js chooses the lightest safe update mode per file change.

## Update modes

| Mode                         | What happens                                                | Typical impact                                            |
| ---------------------------- | ----------------------------------------------------------- | --------------------------------------------------------- |
| Hot module replacement (HMR) | Module/style updates apply in-place                         | Fastest iteration, no full extension relaunch             |
| `Hard reload`                | The target browser reloads the extension runtime            | Extension context restarts, but dev process keeps running |
| `Restart required`           | Compile-time diagnostic asks you to restart `extension dev` | Needed for structural entrypoint/list changes             |

## Common examples

| Change                                           | Expected behavior                         |
| ------------------------------------------------ | ----------------------------------------- |
| Edit content script/component code               | HMR/remount path (when supported)         |
| Edit style imports used by content scripts/pages | HMR-style update path (context-dependent) |
| Edit `manifest.json` values (non-structural)     | Hard reload flow                          |
| Add/remove manifest entrypoint references        | Restart required                          |
| Add/remove `pages/` or `scripts/` entrypoints    | Restart required                          |
| Edit `_locales/*/messages.json`                  | Hard reload flow                          |

## What to do when you need to restart

When Extension.js reports `Restart required`, stop and rerun `extension dev` before continuing.

Typical triggers:

* Adding or removing manifest entrypoint references
* Adding or removing files under `pages/` or `scripts/` used as extension entrypoints
* 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 your runtime in a stale state.

## Next steps

* [manifest.json](/docs/implementation-guide/manifest-json)
* [content scripts](/docs/implementation-guide/content-scripts)
* [background scripts / service worker](/docs/implementation-guide/background)
* [HTML](/docs/implementation-guide/html)