Important Announcement: Upcoming Change to chrome.userScripts API Usage in Chrome Extensions

Dear Chrome Extension Developers,

We have an upcoming change to how Chrome extensions utilize the chrome.userScripts API. We are transitioning from using the global Developer Mode toggle for enabling this API to a new toggle per developer feedback. This toggle remains an additional step to the extension being granted the userScripts permission.

New Per-Extension "Allow User Scripts" Toggle

In milestone 138, instead of relying on the global Developer Mode toggle, users will be able to manage the chrome.userScripts API permission on a per-extension basis. This new toggle will be accessible on the extension detail page (chrome://extensions/?id=<your_extension_id>).

chrome.userScripts API with the new toggle disabled is now `undefined`

In addition, to check the availability of the User Scripts API, extensions previously had to attempt to access `chrome.userScripts`. This threw an error if developer mode was disabled. From Chrome 138, the behavior aligns with other APIs and the API is undefined if unavailable.

```

// Before Chrome 138 and the Developer Mode toggle disabled:

chrome.userScripts;
// Output (throws error): The 'userScripts' API is only available for users in developer mode.

// After Chrome 138 and the new toggle is disabled:

chrome.userScripts;

// Output: returns `undefined`

```

Transition Period, Migration and Documentation Update

During this transition period, any versions prior to the above milestone will continue using the Developer Mode toggle and those at or above the release milestone will use the new per-extension "Allow User Scripts" toggle. This means that while users update both toggles will exist (depending on the Chrome version of the user) as the feature rolls out. We will be updating the developer documentation for the `chrome.userScripts` API to clearly explain both methods of enabling the API so both can be referred to. 

When the new toggle rolls out it does a one-time migration of any existing extensions to reduce user disruption. The logic for this is: if the `userScripts` permission is granted to the extension and the Developer Mode toggle is on then the new toggle will be set to on, otherwise the new toggle will be set to off. Any new extensions installed after the migration will default with the new toggle set to off.

See the release schedule for dates on when this change will reach stable.

Detecting the New Toggle in Your Code

To help you adapt your extension and potentially provide a smoother user onboarding experience during this transition period, you can use the following JavaScript check to determine which toggle mechanism is currently active:

```

let version = Number(navigator.userAgent.match(/(Chrome|Chromium)\/([0-9]+)/)?.[2]);

if (version > 138) {

  // Allow User Scripts toggle will be used.

} else {

  // Developer Mode toggle will be used.

}

```

Early Testing Opportunity

Developers who wish to experiment with the new per-extension Allow User Scripts toggle can do so by launching Chrome with the following command-line flag:

--enable-features=UserScriptUserExtensionToggle

This will allow you to preview and test the new behavior before it becomes the default.

We believe this change will provide users with more granular control over extension capabilities and enhance the overall security and transparency of Chrome extensions. We encourage you to familiarize yourselves with these upcoming changes and update your extensions accordingly.

If you have any questions, please feel free to reach out to us.

Thank you,
Justin, on behalf of the Chromium Extensions Team