references/extensions/user-scripts.md
GitHubUser Scripts API
The chrome.userScripts API lets extensions run arbitrary code provided by the user at
runtime — code that cannot be shipped as part of the extension package. This is fundamentally
different from content scripts (which are bundled with the extension) and chrome.scripting
(which executes extension-owned code programmatically).
Use userScripts when: you are building a script manager, custom automation tool, or any
feature where the user supplies JavaScript that should run on web pages.
Use content scripts when: the injected code is written by you and ships with the extension.
Use chrome.scripting.executeScript when: you need one-off execution of known, extension-owned code.
Manifest
{
"manifest_version": 3,
"minimum_chrome_version": "120",
"permissions": ["userScripts"],
"host_permissions": ["https://example.com/*"]
}
"userScripts"permission is required — without itchrome.userScriptsis undefined.host_permissionsmust cover the sites where scripts will be injected.
User Enablement — CRITICAL
The chrome.userScripts API requires explicit user opt-in. Without it, the API throws on
property access. Behavior differs by Chrome version:
| Chrome version | Requirement |
|---|---|
| < 138 | User must enable Developer mode at chrome://extensions |
| ≥ 138 | User must toggle "Allow User Scripts" on the extension's details page |
// ❌ BROKEN — crashes if user hasn't enabled the API
await chrome.userScripts.register([{ id: 'foo', matches: [...], js: [...] }]);
// TypeError: Cannot read properties of undefined
// ✅ CORRECT — always guard before any chrome.userScripts.* call
function isUserScriptsAvailable() {
try {
chrome.userScripts; // throws if not enabled
return true;
} catch {
return false;
}
}
if (!isUserScriptsAvailable()) {
document.getElementById('warning').style.display = 'block';
document.getElementById('main-ui').style.display = 'none';
return;
}
Execution Worlds
| World | Constant | Behavior |
|---|---|---|
| USER_SCRIPT (default) | ExecutionWorld.USER_SCRIPT |
Isolated from host page JS; exempt from page CSP |
| MAIN | ExecutionWorld.MAIN |
Shares JS context with the host page; can access page variables |
Use USER_SCRIPT (the default) for safety. Use MAIN only when the user's script explicitly
needs to interact with the host page's JavaScript environment.
Chrome 133+ supports multiple isolated worlds via worldId, letting different user scripts
run in separate execution environments without interfering with each other.
Registering Scripts (Persistent)
register() / update() / getScripts() / unregister() manage scripts that persist across
page loads and browser sessions. Registered scripts survive the service worker being terminated.
// ❌ BROKEN — both code and file specified (ScriptSource must have exactly one)
await chrome.userScripts.register([{
id: 'my-script',
matches: ['https://example.com/*'],
js: [{ code: 'alert(1)', file: 'user-script.js' }] // Error: specify code OR file, not both
}]);
// ❌ BROKEN — id starts with underscore (reserved prefix)
await chrome.userScripts.register([{ id: '_my-script', ... }]);
// Error: User script IDs must not start with '_'
// ✅ CORRECT — register from a file bundled with the extension
await chrome.userScripts.register([{
id: 'my-user-script',
matches: ['https://example.com/*'],
js: [{ file: 'user-script.js' }],
runAt: 'document_idle' // optional, this is the default
}]);
// ✅ CORRECT — register inline code supplied by the user
await chrome.userScripts.register([{
id: 'my-user-script',
matches: ['https://example.com/*'],
js: [{ code: userProvidedCode }]
}]);
Always check before calling register() vs update() — registering an already-existing ID
throws an error:
const existing = await chrome.userScripts.getScripts({ ids: ['my-user-script'] });
if (existing.length > 0) {
await chrome.userScripts.update([{ id: 'my-user-script', js: [{ code: updatedCode }] }]);
} else {
await chrome.userScripts.register([{
id: 'my-user-script',
matches: ['https://example.com/*'],
js: [{ code: userProvidedCode }]
}]);
}
// Remove a specific script
await chrome.userScripts.unregister({ ids: ['my-user-script'] });
// Remove all registered user scripts
await chrome.userScripts.unregister();
Persistence: Restore on Extension Update
Registered user scripts are cleared when the extension updates.
// ❌ BROKEN — scripts registered once at install time are lost on every update
chrome.runtime.onInstalled.addListener(({ reason }) => {
if (reason === 'install') {
chrome.userScripts.register([{ id: 'foo', matches: [...], js: [...] }]);
// After the next extension update, 'foo' is gone — no re-registration
}
});
// ✅ CORRECT — persist configs in storage, restore on both install and update
chrome.runtime.onInstalled.addListener(async ({ reason }) => {
if (reason === chrome.runtime.OnInstalledReason.UPDATE) {
const { scripts = {} } = await chrome.storage.local.get('scripts');
for (const s of Object.values(scripts)) {
await chrome.userScripts.register([s]).catch(() => {});
}
}
});
Save the full script config (id, matches, js) to chrome.storage whenever the user saves
a script, so it can be restored after an update.
One-Off Injection (Chrome 135+)
execute() injects a script immediately into a specific tab/frame without registering it. It
does not persist across page loads.
// Requires Chrome 135+
const results = await chrome.userScripts.execute({
target: { tabId: tabId },
js: [{ code: userProvidedCode }],
world: 'USER_SCRIPT' // optional, default
});
for (const result of results) {
if (result.error) {
console.error('Injection failed in frame', result.frameId, result.error);
} else {
console.log('Result from frame', result.frameId, result.result);
}
}
Guard for Chrome 135+ availability:
if (typeof chrome.userScripts.execute === 'function') {
await chrome.userScripts.execute({ ... });
} else {
// Fall back to register-based approach
}
Messaging from User Scripts
User scripts run in the USER_SCRIPT world which has no access to chrome.runtime by
default. Messaging requires an explicit opt-in.
// ❌ BROKEN — messaging not enabled; chrome.runtime is undefined in the user script
// sw.js
chrome.runtime.onMessage.addListener((msg) => { ... }); // Never fires from user scripts
// user script code (running in the page)
chrome.runtime.sendMessage({ type: 'hello' }); // TypeError: chrome is not defined
// ✅ CORRECT — opt in first, then use the dedicated listener
// sw.js (run once, e.g. on install)
await chrome.userScripts.configureWorld({ messaging: true });
// sw.js — listen on the dedicated handler, not onMessage
chrome.runtime.onUserScriptMessage.addListener((message, sender, sendResponse) => {
sendResponse({ ok: true });
return true; // keep channel open for async responses
});
// user script code — chrome.runtime is now available
chrome.runtime.sendMessage({ type: 'FROM_USER_SCRIPT', data: 42 });
For long-lived connections use chrome.runtime.onUserScriptConnect (analogous to
runtime.onConnect for content scripts).
Chrome 133+ supports per-world messaging with worldId:
await chrome.userScripts.configureWorld({ worldId: 'my-world', messaging: true });
configureWorld() — CSP and Messaging
await chrome.userScripts.configureWorld({
csp: "script-src 'self'", // custom CSP for the world
messaging: true // enable chrome.runtime messaging
});
// Chrome 133+: configure a named world
await chrome.userScripts.configureWorld({
worldId: 'my-world',
messaging: true
});
// Chrome 133+: reset a world's configuration
await chrome.userScripts.resetWorldConfiguration('my-world');
// Chrome 133+: list all world configurations
const configs = await chrome.userScripts.getWorldConfigurations();
Complete Script Manager Pattern
// options.js — save user's script and (re)register it
async function saveScript(id, matches, code) {
// Persist the config so we can restore it after extension updates
const { scripts = {} } = await chrome.storage.local.get('scripts');
scripts[id] = { id, matches, js: [{ code }] };
await chrome.storage.local.set({ scripts });
// Register or update the live script
const existing = await chrome.userScripts.getScripts({ ids: [id] });
if (existing.length > 0) {
await chrome.userScripts.update([{ id, matches, js: [{ code }] }]);
} else {
await chrome.userScripts.register([{ id, matches, js: [{ code }] }]);
}
}
Key Differences from Content Scripts
| Content Scripts | userScripts | |
|---|---|---|
| Code source | Bundled with extension | Provided by user at runtime |
| Persistence | Automatic (manifest) | Manual (register + restore on update) |
| Arbitrary code | No | Yes |
| User opt-in | No | Yes (Developer Mode / Allow User Scripts) |
| Messaging | runtime.sendMessage |
runtime.onUserScriptMessage (after configureWorld) |
| CSP exemption | Yes | Yes (USER_SCRIPT world) |
| Multiple worlds | No | Yes (Chrome 133+ with worldId) |