content-scripts-register-polyfill

WebExtensions: Polyfill for browser.contentScripts.register() for Chrome and Safari.

Warning contentScripts.register by design is not compatible with Event Pages (MV2) and Service Workers (MV3).

You should prefer chrome.scripting.registerContentScripts() where available: Chrome Manifest v3, Firefox 102+. Extended details on how they differ can be found in issue #11

Install

You can download the standalone bundle and include it in your manifest.json.

npm install content-scripts-register-polyfill

import 'content-scripts-register-polyfill';

Usage

Include the script via manifest.json, then refer to the original contentScripts.register() documentation.

const registeredScript = await chrome.contentScripts.register({
	js: [{
		file: 'myfile.js'
	}],
	matches: [
		'https://google.com/*'
	]
});

Additionally, if you're using webextension-polyfill, you can also use it with the original browser.* name: browser.contentsScripts.register()

const registeredScript = await browser.contentScripts.register({
	js: [{
		file: 'myfile.js'
	}],
	matches: [
		'https://google.com/*'
	]
});

Usage as ponyfill

This package also exports a ponyfill, meaning you can also use it as a normal API instead of treating it as a polyfill. This way it will always use the current code and never rely on Firefox’ native implementation.

import registerContentScript from 'content-scripts-register-polyfill/ponyfill.js';

const registeredScript = await registerContentScript({
	js: [{
		file: 'myfile.js'
	}],
	matches: [
		'https://google.com/*'
	],
	excludeMatches: [ // Also supported
		'https://google.com/search*'
	]
});

TypeScript

Starting in v3, the types are no longer included. You have a few options:

if you're using webextension-polyfill and the browser.* API, install its types
```
npm install -D @types/webextension-polyfill
```
if you want to use it as chrome.contentScripts.register() or as a ponyfill, you might need to install two type packages:
```
npm install -D @types/webextension-polyfill @types/chrome
```

Permission

Generally you don't need any permissions other than the host permission you want to register a script on.

However, in order to use allFrames: true you should the add webNavigation permission. Without it, allFrames: true won’t work:

when the iframe is not on the same domain as the top frame
when the iframe reloads or navigates to another page
when the iframe is not ready when runAt is configured to run (runAt: 'start' is unlikely to work)

If available, the webNavigation API will be automatically used in every situation for better performance.

webext-options-sync - Helps you manage and autosave your extension's options.
webext-domain-permission-toggle - Browser-action context menu to request permission for the current tab.
webext-dynamic-content-scripts - Automatically inject your content_scripts on custom domains.
webext-detect-page - Detects where the current browser extension code is being run.
webext-content-script-ping - One-file interface to detect whether your content script have loaded.
Awesome WebExtensions: A curated list of awesome resources for Web Extensions development.

fregante/content-scripts-register-polyfill