Description
Unleash the power of the userScripts API to execute user scripts in the User Scripts context.
Approvals
userScripts
Schedule
To tap into the chrome.userScripts API, add the “userScripts” permission to your manifest.json and “host_permissions” for the websites you want to run scripts on.
“name”: “User script test extension”, “manifest_version”: 3, “minimum_chrome_version”: “120”, “authorizations”: [
“userScripts”
]”host_permissions”: [
“*://example.com/*”
]
Principles and use
A user script is a small piece of code injected into a website to customize its appearance or behavior. Scripts can be created by users or downloaded from a script repository or a user script extension.
Designer mode for extension users
As an extension developer, you already have Developer mode enabled in your setup of Chrome. For user script extensions, your users will also need to enable developer mode. Here are instructions that you can copy and paste into your own documentation.
- Go to the Extensions page by entering chrome:// extensions in a new tab. (By design chrome:// URLs are not linkable.)
-
Enable Developer Mode by clicking the toggle switch next to Developer mode.
Extensions page (chrome:// extensions)
You can determine if developer mode is enabled by checking whether chrome.userScripts throws an error.
function isUserScriptsAvailable() try catch Not available. return false; Operate in isolated worlds
Both user and content scripts can run in an isolated world or in the main world. An isolated world is an execution environment that isn’t accessible to a host page or other extensions. This allows a user script to modify its JavaScript environment without affecting the host page or other extensions’ user and content scripts. On the other hand, user scripts (and content scripts) are not visible to the host page or the user and content scripts of other extensions. Scripts running in the main world are accessible to host pages and other extensions and are visible to host pages and other extensions. To choose the world, pass “USER_SCRIPT” or “MAIN” when calling userScripts.register().
To set up a content security policy for whichever world you define, call userScripts.configureWorld() as shown below.
chrome.userScripts.configureWorld( csp: “script-src ‘self'” ); Messaging
Like content scripts and offscreen files, user scripts can communicate with other parts of an extension using messaging. Unlike other types of messages, user script messages use their own methods: runtime.onUserScriptMessage and chrome.runtime.onUserScriptConnect events.
Before sending a message, you must call configureWorld() with the messaging argument set to true. Note that both the csp and messaging arguments can be passed at the same time.
chrome.userScripts.configureWorld( ); Extension updates
User scripts are cleared when an extension updates. You can add them back by running code through the runtime.onInstalled event handler in the extension service worker. React only to the “update” reason passed to the event callback.
Example
The example below is from the userScript sample in our samples repo.
