Skip to content

fregante/content-scripts-register-polyfill

Repository files navigation

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

License

MIT © Federico Brigante