Skip to main content
Build page-integrated extension features with content scripts while keeping a reliable dev loop for JS and CSS updates. Extension.js compiles content script entries from manifest.json and wraps them for runtime mounting and hot module replacement (HMR) behavior. It emits predictable content_scripts/* outputs.

Content script capabilities

Template examples

content

content template screenshot Minimal content script setup with vanilla JS.
Repository: extension-js/templates/content

content-react

content-react template screenshot Inject a React-powered UI into web pages through content scripts.
Repository: extension-js/templates/content-react

Supported manifest fields

Sample content script declaration

Example content script declaration in manifest.json:

Authoring contract

For every content-script-like entry, Extension.js expects a mount-style default export. This is a function that sets up behavior and optionally returns a cleanup callback:
  • The module should export default a synchronous function.
  • That function should perform setup work.
  • It may return a synchronous cleanup callback.
  • Extension.js does not support classes as the default export.
This applies to:
  • Files referenced by manifest.json > content_scripts[*].js.
  • Files you place under the project scripts/ folder and use as script entrypoints.

Valid shapes

Invalid shapes

Guidance for async content scripts

Keep the default export synchronous even when the feature does async work internally. Start async work inside the function and return a synchronous cleanup. Why this matters: Extension.js remounts content scripts during development. Without a cleanup function, you can duplicate UI, event listeners, observers, and timers.

What happens on contract violations

  • No default export: the module runs when it loads, as written, and Extension.js has no cleanup to call. Each re-inject during development adds another running copy. The dev session prints a warning that names the file, once per entry. This hint needs 4.1.39 or later.
  • Default export is not a function: Extension.js warns during development and skips mounting.
  • Default export returns a Promise: the module still runs, but Extension.js does not treat that Promise as cleanup.
If your content script appears to compile but never mounts, check the default export first.

What survives a whole-extension reload

When an edit in extension dev reloads the whole extension, a tab that stays open still holds the copy of your content script from before the reload. What happens to that old copy depends on the browser engine:
  • Chromium keeps the old copy running in the open tab beside the new one until the tab reloads, timers and listeners included. Its chrome.runtime.id is gone, and no cleanup is called for it, even when the script has a default export that returns one.
  • Firefox discards the old copy. No cleanup is called for it, and it never runs again.
On both engines, what the old copy added to the page stays until the next copy removes it. To end the old copy on Chromium, reload the tab. Or have long-lived work stop once chrome.runtime.id is gone:
For a script with no default export, the dev session warning says the same on Chromium:
Put everything that your script adds to the page under one host element marked data-extension-root. When the next copy starts, Extension.js removes the hosts that an older copy left behind, on Chromium and on Firefox:
This sweep needs a dev session. A production build has no reloads to recover from.

Runtime wrapper behavior

  • Extension.js wraps content script modules with mount/runtime helpers.
  • The wrapper also applies in production builds, and no option turns it off.
  • From the release after 4.1.41, the wrapper runs after your own loaders. See Loader order.
  • In development mode, Extension.js adds HMR accept/dispose behavior and remount flow.
  • CSS updates trigger remount events (__EXTENSIONJS_CSS_UPDATE__) in development.
  • Extension.js respects run_at timing from manifest values.

Multi-entry content scripts

You can declare multiple content script entries in a single manifest. Each entry compiles independently with its own match patterns, run timing, and world settings.

content-multi-one-entry

content-multi-one-entry template screenshot Multiple content scripts bundled under one content_scripts manifest entry.
Repository: extension-js/templates/content-multi-one-entry

content-multi-three-entries

content-multi-three-entries template screenshot Three separate content_scripts manifest entries with independent match patterns.
Repository: extension-js/templates/content-multi-three-entries

Classic multi-file entries

When one content_scripts.js array lists several plain JavaScript files with no import or export, Extension.js concatenates them into one bundle. Bundling each file as an isolated module would break them. The browser injects classic files in order into one shared scope, and concatenation preserves that:
  • Implicit cross-file globals keep working. A top-level var or function in the first file stays visible to the next file.
  • Each source file registers as a build dependency, so saving any file in the group triggers a rebuild.
  • The emitted source map points at your real files and lines, so errors trace back to the original code.
  • A raw .ts file inside a concat group gets its types stripped with the bundled SWC before concatenation.
Entries that use import or export keep normal module bundling.

scripts/ folder behavior

The scripts/ folder is for script entrypoints that no HTML page entry declares. In practice, these entries follow the same default-export pattern as content scripts. That means scripts/ is not a generic folder for loose JavaScript files:
  • Script entry files should still export a default function when they mount behavior
  • Extension.js treats adding or removing supported files under scripts/ as a structural change in watch mode
  • When a manifest edit adds, removes, or renames a script entry, a running extension dev session restarts its compiler and reloads the extension. You do not restart the command. From the release after 4.1.41, the session also restarts when a script moves to another manifest key, such as the same file moved from background.scripts to background.service_worker.

Output path

Extension.js normalizes content script entries per manifest index:
In development mode, content script JS filenames include a short hash suffix (for example, content-0.abcd1234.js). This forces the browser to load a fresh chrome-extension:// URL after each rebuild. Chrome aggressively caches extension resources, so the hash prevents stale code. Production builds use clean content-0.js names.

MAIN world notes

content-main-world

See MAIN world content scripts in action with a working example that injects UI directly into the page context:
Repository: extension-js/templates/content-main-world
  • world: "MAIN" works on Chrome 111, Firefox 128, and Safari 18 or later. The script runs in the page’s own JavaScript world on all three. On Firefox, that holds under Manifest V2 and Manifest V3.
  • A MAIN world script has no extension APIs. chrome.runtime, chrome.storage, and the rest are not available there, and you can only access page-context globals. Pair it with an isolated-world script to talk to the extension.
  • A browser prefix is only worth it for older browsers. Use chromium:world with an isolated-world fallback only if you must support a browser older than those versions.
  • A scripts/ file can run in the MAIN world too. Register or inject it at runtime with world: "MAIN". See Inject scripts at runtime.
  • From 4.2.0, a MAIN world script that fails to compile ships no broken bundle.
  • Treat MAIN world as an advanced path. Validate behavior on each target browser early.

The isolated-world bridge

MAIN world scripts cannot call extension APIs, so Extension.js pairs each MAIN group with a helper that can. Expect the built manifest to differ from your source here:
  • The dist manifest contains more content_scripts entries than the source. Extension.js prepends one isolated-world bridge entry before each MAIN group.
  • Bridge entries take asset indices after your entries. Your content_scripts/content-N outputs keep the index of the source entry that produced them.
  • The bridge resolves extension URLs through runtime.getURL and injects the MAIN world’s script chunks into the page. From the release after 4.1.39, it injects nothing on Firefox, and the MAIN world script loads its own chunks.
  • The bridge validates that event.source is the same window before acting on a message.
  • It injects only extension-scheme URLs (chrome-extension://, moz-extension://) or relative paths, never arbitrary remote URLs.

Extension URLs that the page can read on Firefox

On Firefox, your moz-extension:// origin carries an id that is unique to each install. A page that learns it can recognize the same browser again. From the release after 4.1.39, the build hands a MAIN world script that origin without writing it into the page’s DOM. The page cannot read the origin from that hand-off. That covers the build’s own plumbing only. The page can read anything that your script places in the DOM:
  • An <img src> or a <link href> that points at an extension asset.
  • A fetch of an extension URL, when the page has patched fetch.
  • A component <style> block whose url() names an extension asset. The sheet lands in a <style> element in the document.
Keep extension URLs out of the page from a MAIN world script, or accept the exposure. To keep them out, do that work in an isolated-world script and pass the data across. A page can tamper with the hand-off. A page that swaps it for its own gets nothing, and your script then loads no assets or chunks. A page that locks the hand-off before the bridge runs forces a fallback to the document, where it can read the origin.

Isolated vs MAIN quick example

Use isolated world by default. Use MAIN only when you need page-context access, and account for extension API/runtime constraints.

Support older browsers with a prefix

On Chrome 111, Firefox 128, and Safari 18 or later, the plain world key in the quick example is all that you need. A Firefox version older than 128 ignores the world key and runs the script in the isolated world. If you must support one, use browser-specific prefixes to declare MAIN world only for Chromium and provide an isolated fallback for Firefox. Every Firefox version then runs the fallback, including the versions that support MAIN:
Firefox skips the chromium: prefixed fields entirely, so the second entry reaches the Firefox build with no js and no css. Firefox gets nothing from it. The build leaves that entry out of the Firefox manifest and prints why:
When Firefox needs a content script on those matches, put a plain js on the same entry. A prefixed key overrides the plain key with the same name, so Chromium still takes chromium:js in the MAIN world and Firefox runs the plain js in the isolated world. One entry then covers both browsers, and the build prints no warning:
A plain js is the base every target reads, so the entry stays whole on any browser that does not resolve chromium:. firefox:js also keeps the entry, but only on Gecko targets, and the prefix page’s rule is to write the plain key as the base and prefix only the exception.

Matching and execution guidance

The browser still controls where a content script runs. Extension.js bundles the file, but the manifest entry still defines where and when the script runs.
  • Keep matches as narrow as the feature allows.
  • Add exclude_matches, all_frames, or match_about_blank only when the feature actually requires those behaviors.
  • Treat run_at and world as part of the feature contract, not an implementation detail.
  • Re-test permission and host-permission scope when changing where a content script runs.

Development behavior

  • Editing content script code usually updates through wrapper-driven HMR/remount flow.
  • CSS-only entries receive dev helper behavior so style updates can propagate.
  • When a manifest edit adds, removes, or renames a script entry, a running extension dev session restarts its compiler and reloads the extension. You do not restart the command. From the release after 4.1.41, the session also restarts when a script moves to another manifest key, such as the same file moved from background.scripts to background.service_worker.

Best practices

  • Keep content script entry files small and delegate logic to shared modules.
  • Scope selectors/styles carefully to avoid host-page collisions.
  • Prefer explicit run_at and world values when behavior depends on timing/context.
  • Treat manifest content-script list changes as structural development changes.
  • Pass page-derived data through validated messaging instead of performing privileged work directly in the content script.
  • Default to isolated world and move to MAIN only when the page context is strictly required.

Next steps

See the template run