Skip to main content
A browser extension can run code inside a web page in three ways. A manifest content_scripts entry runs on every page that matches a pattern. chrome.scripting.executeScript runs one script in one tab when you call it. chrome.scripting.registerContentScripts registers a content script at runtime and keeps it registered. This page explains when each one runs, which permission it needs, and how the browsers differ. It also lists the console lines that injection failures print and where the file goes in an Extension.js project.

The three ways to run code in a page

Manifest content_scripts. A static declaration in manifest.json. The browser injects the listed js and css files into every page that matches matches, at the time set by run_at. Extension.js compiles each entry and wraps it for HMR, see Content scripts. chrome.scripting.executeScript. A one-off call from the service worker or another extension page. It targets one tab and runs either files (paths inside the extension) or func (a function serialized into the page, with optional args). It needs the scripting permission plus access to the tab, from activeTab after a user gesture or from a matching host_permissions pattern. chrome.scripting.registerContentScripts. A dynamic registration with the same shape as a manifest entry (id, matches, js, css, runAt, world). The browser injects it into pages that match from that moment on, and the registration persists across browser restarts by default. It needs the scripting permission and host_permissions that cover matches, because activeTab does not apply to future pages. Use the manifest entry when the feature belongs on a known set of sites. Use executeScript when the user triggers the feature, for example from a toolbar click. Use registerContentScripts when the set of sites is decided at runtime, for example from a settings page.

Manifest snippet

The scripting permission unlocks both runtime APIs. activeTab covers the tab the user clicked in, and host_permissions covers every page that matches, which dynamic registration requires:
Chromium and Firefox both read this block as written, so it needs no browser prefix. A manifest content script with world: "MAIN" needs no prefix either on Chrome 111, Firefox 128, and Safari 18 or later. Use chromium:world with an isolated-world fallback only if you must support older browsers, as shown in Content scripts. The runtime calls that match this manifest:

Change a registration

Calling registerContentScripts again with an id that is already registered rejects in both browsers. It never replaces the first registration, which stays in place.
  • Chrome: Duplicate script ID 'highlight'
  • Firefox: Content script with id "highlight" is already registered
To change an existing registration, call updateContentScripts with the same id. The next navigation injects the new file. An unknown id rejects in both browsers.
Pass persistAcrossSessions: true again in the update. In Chrome 155, an update that omits it resets the value from true to false. Firefox 158 keeps it true. Measured with Extension.js 4.1.33.

Per-browser differences

On Safari, enabling the extension is not enough. Until you grant website access, no content script runs, and the same applies to scripts you inject at runtime. See Safari for the enable and grant steps. From the release after 4.1.39, chrome.scripting and browser.scripting both work on a Firefox Manifest V2 background page, in dev and in a production build. Each keeps its own calling style: chrome.scripting answers a callback, and browser.scripting returns a promise.

Console lines you will see

Copy the line that you see into search. Each one maps to one cause. Cannot access contents of url "https://example.com/". Extension manifest must request permission to access this host. The tab is outside your host permissions and activeTab was not granted for it. Add the host to host_permissions, or call executeScript from a handler that runs after a user gesture on the tab. Could not load file: 'scripts/highlight.ts'. The executeScript or registerContentScripts call names a source path. Extension.js compiles scripts/highlight.ts to scripts/highlight.js, so inject the emitted .js path. Failed to load resource: net::ERR_FILE_NOT_FOUND A chrome-extension:// URL that ends in .ts (or another path that never reached dist/). Same fix: reference the emitted .js file, then confirm it exists under dist/<browser>/scripts/. NS_ERROR_CONTENT_BLOCKED The Firefox form of the same missing-file error on a moz-extension:// URL. Inject the emitted .js path. Cannot access a chrome:// URL Browser pages cannot be scripted. Test on a normal https:// page. The extensions gallery cannot be scripted. The Chrome Web Store is off limits to every extension. Test on another page. This page cannot be scripted due to an ExtensionsSettings policy. A managed browser blocks your extension on this host. Test on a host that the policy allows, or on a profile that the policy does not manage.

The Extension.js way

Put runtime-injected files in the scripts/ special folder. The rules are short:
  • scripts/ lives beside package.json at the project root, not inside src/. A nested src/scripts/ is a plain folder.
  • Every file there compiles to .js and lands at dist/<browser>/scripts/<name>.js.
  • Reference the emitted path in your files or js array. A .ts path builds fine but 404s in the browser.
  • When a runtime literal names a .ts source, the build prints a warning with the emitted path to use.
  • The file follows the content script contract: export default a synchronous function that returns an optional cleanup.
See Special folders for the full folder contract. During extension dev, scripts that you inject with executeScript from scripts/ are replayed on edit, so the injected code updates live the way declarative content_scripts do. See Reload and HMR. From the release after 4.1.39, executeScript with a scripts/ file resolves with the value of the file’s last expression, as a native file does. This holds on Chrome and Firefox. A value that the browser cannot clone, such as a DOM node or a function, gives no value. A background script can call registerContentScripts as it starts. From the release after 4.1.39, extension dev holds the first page for a bounded time until those registrations answer. See dev.

Run a scripts/ file in the MAIN world

Pass world: "MAIN" in the call, and the build compiles that scripts/ file for the page’s own world. Needs the release after 4.1.39.
  • The build finds the call in the background, in extension pages, and in the local modules that they import.
  • The search follows build aliases, tsconfig.json paths, and linked workspace packages. It skips packages installed under node_modules.
  • executeScript with files and world: "MAIN" gets the same treatment.
  • In development, the file carries no HMR runtime and no dev instrumentation, so neither runs on the host page.
  • A production build leaves no __EXTENSIONJS_* global on the page, even when the file imports other scripts/ modules.
  • A dynamic import() in the file loads its chunk, also at document_start.
  • On Firefox, the file resolves its imported assets and chunks from your moz-extension:// origin.
  • A production build hands the file that origin without writing it into the page’s DOM.
That hand-off covers the build’s own plumbing only. The page can read any extension URL that your script places in the DOM, and on Firefox that URL identifies the install. See the MAIN world notes in Content scripts for the cases and the fix. Write the path and world: "MAIN" as literals in the call. A const in the same file works too, and so does an exported const that the file imports. The build does not detect a call that is built from another value. When you add or remove a call during a session, extension dev restarts by itself to build the file for its new world. If the session cannot restart, it prints a warning that asks for a restart.

Register one file in both worlds

Chromium injects one file path once per frame. A file that you register in both worlds under one path runs in the isolated world alone. The two worlds also need different builds. From the release after 4.1.39, the build covers this case. When your source registers a scripts/ file in the MAIN world and in the isolated world, the build emits two files:
  • scripts/<name>.js is the isolated world build.
  • scripts/<name>.extjs-main-world.js is the MAIN world build.
Keep the path /scripts/<name>.js in every call. The build routes a world: "MAIN" call to the second file, and getRegisteredContentScripts answers with the name that you wrote. If your project already has a file with that second name, your file wins and the build makes no copy. A file that registerContentScripts places in the MAIN world only gets the second file too. The browser keeps a registered path across sessions, so that path stays a MAIN world build. The build reads the world from the call. It reads a literal, a const, a choice between the two literals, a spread of a literal object, and a .map() over a literal list. A call with no world is an isolated one. The build cannot read a world that exists only when the call runs, such as a function parameter. It builds the file for the isolated world and prints a warning that names the call:

Paths in an extension page

In an extension page, start the path at the root, as in /scripts/hook.js. Firefox resolves scripts/hook.js against the page, so the script never runs and no error is thrown. A build for a Firefox target prints a warning that names the path to write. From the release after 4.1.39, the warning also covers a file that include or public/ copies into the output. Scaffold a project that injects a scripts/ entry at runtime:
For the static path, start from the content template instead:

See also