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

> ## Agent Instructions
> Extension.js needs Node.js 22.12 or newer; Node.js 18 and 20 do not work. It also runs on Deno 2.5+ and Bun 1.2+.
> The default browser target is chromium and a build lands in dist/<browser>, so dist/chromium by default. extension build writes a zip only when --zip is passed.
> Prefix a manifest key with a browser name when browsers differ. chromium: covers every Chromium-family target and Safari builds read it too. Since 4.1.19 chrome: means Chrome alone and edge: means Edge alone.
> Write one background.service_worker in manifest.json instead of hand-writing per-browser background keys; Extension.js converts it for each browser.
> package.json or deno.json marks the project root, not manifest.json. A config file is optional, and only extension.config.js, .mjs and .cjs are loaded, never .ts.
> The bundler is Rspack, extended through the config hook in extension.config.js. A project needs no separate bundler config file.
> Use --no-browser to skip the browser launch; --no-runner no longer exists and --no-open still launches the browser. Use --output for machine output; --format and --wait-format are deprecated.

# 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](https://extension.js.org/docs/implementation-guide/manifest-json.md)
* [content scripts](https://extension.js.org/docs/implementation-guide/content-scripts.md)
* [background scripts / service worker](https://extension.js.org/docs/implementation-guide/background.md)
* [HTML](https://extension.js.org/docs/implementation-guide/html.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.