Skip to content

WebExtension module: Automatically registers your content_scripts on domains added via permission.request

License

Notifications You must be signed in to change notification settings

fregante/webext-dynamic-content-scripts

Repository files navigation

webext-dynamic-content-scripts npm version

WebExtension module: Automatically registers your content_scripts on domains added via permissions.request

  • Browsers: Chrome, Firefox, and Safari
  • Manifest: v2 and v3

This module will automatically register your content_scripts from manifest.json into new domains granted via permissions.request(), or via webext-permission-toggle.

The main use case is ship your extension with a minimal set of hosts and then allow the user to enable it on any domain; this way you don't need to use a broad <all_urls> permission.

Guides

How to let your users enable your extension on any domain.

Install

You can download the standalone bundle and include it in your manifest.json. Or use npm:

npm install webext-dynamic-content-scripts
// This module is only offered as a ES Module
import 'webext-dynamic-content-scripts';

Usage

For Manifest v2, refer to the usage-mv2 documentation.

You need to:

  • import webext-dynamic-content-scripts in the worker (no functions need to be called)
  • specify optional_host_permissions in the manifest to allow new permissions to be added
  • specify at least one content_scripts
// example background.worker.js
navigator.importScripts('webext-dynamic-content-scripts.js');
// example manifest.json
{
	"permissions": ["scripting", "storage"],
	"optional_host_permissions": ["*://*/*"],
	"background": {
		"service_worker": "background.worker.js"
	},
	"content_scripts": [
		{
			"matches": ["https://github.com/*"],
			"css": ["content.css"],
			"js": ["content.js"]
		}
	]
}

activeTab tracking

By default, the module will only inject the content scripts into newly-permitted hosts, but it will ignore temporary permissions like activeTab. If you also want to automatically inject the content scripts into every frame of tabs as soon as they receive the activeTab permission, import a different entry point instead of the default one.

import 'webext-dynamic-content-scripts/including-active-tab.js';

Note This does not work well in Firefox because of some compounding bugs:

  • activeTab seems to be lost after a reload
  • further contextMenu clicks receive a moz-extension URL rather than the current page’s URL

Additional APIs

isContentScriptRegistered(url)

You can detect whether a specific URL will receive the content scripts by importing the utils file:

import {isContentScriptRegistered} from 'webext-dynamic-content-scripts/utils.js';

if (await isContentScriptRegistered('https://google.com/search')) {
	console.log('Either way, the content scripts are registered');
}

isContentScriptRegistered returns a promise that resolves with a string indicating the type of injection ('static' or 'dynamic') or false if it won't be injected on the specified URL.

Related

License

MIT © Federico Brigante