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.

Related

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

License

MIT © Federico Brigante