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
Manifestcontent_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
Thescripting 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:
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
CallingregisterContentScripts 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
updateContentScripts with the same id. The next navigation injects the new file. An unknown id rejects in both browsers.
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 thescripts/ special folder. The rules are short:
scripts/lives besidepackage.jsonat the project root, not insidesrc/. A nestedsrc/scripts/is a plain folder.- Every file there compiles to
.jsand lands atdist/<browser>/scripts/<name>.js. - Reference the emitted path in your
filesorjsarray. A.tspath builds fine but 404s in the browser. - When a runtime literal names a
.tssource, the build prints a warning with the emitted path to use. - The file follows the content script contract:
export defaulta synchronous function that returns an optional cleanup.
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.jsonpaths, and linked workspace packages. It skips packages installed undernode_modules. executeScriptwithfilesandworld: "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 otherscripts/modules. - A dynamic
import()in the file loads its chunk, also atdocument_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.
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 ascripts/ file in the MAIN world and in the isolated world, the build emits two files:
scripts/<name>.jsis the isolated world build.scripts/<name>.extjs-main-world.jsis the MAIN world build.
/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:
content template instead:

