diff --git a/src/content/documentation/develop.md b/src/content/documentation/develop.md
index 60b0ecfa0..f9a3220ad 100644
--- a/src/content/documentation/develop.md
+++ b/src/content/documentation/develop.md
@@ -1,263 +1,257 @@
----
-layout: sidebar.liquid
-title: Create extensions for Firefox and Firefox for Android
-description: Deep dive into developing Firefox extensions. Get guides on Manifest V3, cross-browser porting, security best practices, and debugging tools for your add-ons.
-permalink: /documentation/develop/
-tags: []
-contributors: [caitmuenster]
-last_updated_by: caitmuenster
-date: 2019-07-09 09:00:00
----
-
-
-
-{% capture page_hero_banner_content %}
-
-# Bring your extension to life
-
-Support your development workflow with these straightforward tools and guides.
-
-{% endcapture %}
-{% include modules/overview-page-hero.liquid,
- content: page_hero_banner_content
- background: "develop-overview-hero-bg.jpg"
-%}
-
-
-
-
-
-{% capture content_with_toc %}
-
-## Firefox Tools
-
-### Development tools
-
-All you need to create extensions for Firefox is a [text editor](https://developer.mozilla.org/docs/Learn/Common_questions/Available_text_editors) and [a version of Firefox](/documentation/develop/choosing-a-firefox-version-for-extension-development/) to support your testing. Mozilla and the Firefox extension developer community have also created a number of [extension development tools](/documentation/develop/browser-extension-development-tools/) that can simplify the coding and testing of your extension.
-
-### Chromium-based browser extensions
-
-Get familiar with the [webextension-polyfill](https://github.com/mozilla/webextension-polyfill) library if you’re planning on developing for both Firefox and Chromium-based browsers.
-
-This enables you to switch between the different Firefox and Chromium-based namespaces and asynchronous call handling methods for each type of browser.
-
-### web-ext command line tool
-
-The web-ext tool can help you by:
-
-- providing features to automatically reload your extension preview as the code changes
-- assist with debugging
-- create extension packages, and more
-
-{% endcapture %}
-{% include modules/column-w-toc.liquid,
- id: "firefox-tools"
- content: content_with_toc
-%}
-
-
-
-
-
-
-
-
-
-{% capture content %}
-
-## User Experience
-
-{% endcapture %}
-{% include modules/one-column.liquid,
- content: content
-%}
-
-
-
-
-
-{% capture col_1_content %}
-
-
-
-{% endcapture %}
-{% capture col_2_content %}
-
-Having an exceptional user experience is crucial to attracting, and retaining, users of your extension.
-
-[RememBear](https://addons.mozilla.org/firefox/addon/remembear-app/) is a great example of an extension with an outstanding user experience.
-
-{% endcapture %}
-{% include modules/two-column.liquid,
- col_1: col_1_content
- col_2: col_2_content
- reverse: false
-%}
-
-
-
-
-
-{% capture content %}
-
-### Make a great first impression
-
-Focus on a slick [onboarding flow](/documentation/develop/onboard-upboard-offboard-users/) that gets users up to speed with your extension quickly.
-
-If your extension collects user data during onboarding, make sure you follow the [best practices for collecting user data consent](/documentation/develop/best-practices-for-collecting-user-data-consents/). And, it’s important that you [request the right permissions](/documentation/develop/request-the-right-permissions/).
-
-### Put your user first
-
-Keep your users engaged and follow the [user experience best practices](/documentation/develop/user-experience-best-practices/). And, don’t forget to [build an accessible extension](/documentation/develop/build-an-accessible-extension/), so that everyone can make use of it.
-
-Lastly, [building a secure extension](/documentation/develop/build-a-secure-extension/) is fundamental to delivering an excellent user experience.
-
-### Define your value proposition
-
-Users are less likely to install an extension if they don’t understand what it does and what value it adds to their browsing experience.
-Find out best practices for putting your best foot forward with your extension.
-
-{% endcapture %}
-{% include modules/one-column.liquid,
- content: content
-%}
-
-
-
-
-
-
-
-
-
-
-
-
-
-{% capture content %}
-
-## Firefox for Android
-
-{% endcapture %}
-{% include modules/one-column.liquid,
- content: content
-%}
-
-
-
-
-
-{% capture col_1_content %}
-
-
-
-{% endcapture %}
-{% capture col_2_content %}
-
-### Understanding how to develop extensions for Android
-
-To offer your extension to Firefox for Android users, you need to consider some [differences between Firefox for the desktop and Android](/documentation/develop/differences-between-desktop-and-android-extensions/).
-
-Get started with everything you need to know about [developing for Firefox for Android](/documentation/develop/developing-extensions-for-firefox-for-android/).
-
-{% endcapture %}
-{% include modules/two-column.liquid,
- col_1: col_1_content
- col_2: col_2_content
- reverse: true
-%}
-
-
-
-
-
-{% capture content %}
-
-### Creating browser experiences for Android apps
-
-If you develop Android apps, when you want to include a browser experience in your app you can take advantage of the browser engine that underpins Firefox using the [GeckoView Extensions Android library](https://github.com/mozilla/geckoview).
-
-{% endcapture %}
-{% include modules/one-column.liquid,
- content: content
-%}
-
-
-
-
-
-
-
-
-
-
-
-
-
-{% capture content %}
-
-## Port to Firefox
-
-{% endcapture %}
-{% include modules/one-column.liquid,
- content: content
-%}
-
-
-
-
-
-{% capture col_1_content %}
-
-
-
-{% endcapture %}
-{% capture col_2_content %}
-
-### Bring your Chrome extension to Firefox
-
-The Firefox extension environment is highly compatible with Chromium-based extension technology. Your extension might already be capable of running on Firefox, or need only a few changes.
-
-Check out our [porting guide](/documentation/develop/porting-a-google-chrome-extension/) to get started.
-
-{% endcapture %}
-{% include modules/two-column.liquid,
- col_1: col_1_content
- col_2: col_2_content
- reverse: true
-%}
-
-
-
-
-
-
-
-
-
-
-
-
-
-{% capture content %}
-
-## Test and debug
-
-### Make sure your extension is running right
-
-Test and [debug your code](/documentation/develop/debugging/) by [temporarily installing](/documentation/develop/temporary-installation-in-firefox/) it in Firefox.
-
-Understanding [extensions and the Add-on ID](/documentation/develop/extensions-and-the-add-on-id/) will help you test more effectively. You will also want to [test persistent and restart features](/documentation/develop/testing-persistent-and-restart-features/) along with [permission requests](/documentation/develop/test-permission-requests/).
-
-You can use [web-ext](/documentation/develop/getting-started-with-web-ext/) to automatically install and update your extension while making coding changes.
-
-{% endcapture %}
-{% include modules/one-column.liquid,
- content: content
-%}
-
-
-
-
-
-
+---
+layout: sidebar.liquid
+title: Create extensions for Firefox and Firefox for Android
+description: Deep dive into developing Firefox extensions. Get guides on Manifest V3, cross-browser porting, security best practices, and debugging tools for your add-ons.
+permalink: /documentation/develop/
+tags: []
+contributors: [caitmuenster, rebloor]
+last_updated_by: rebloor
+date: 2026-08-05
+---
+
+
+
+{% capture page_hero_banner_content %}
+
+# Bring your extension to life
+
+Support your development workflow with these straightforward tools and guides.
+
+{% endcapture %}
+{% include modules/overview-page-hero.liquid,
+ content: page_hero_banner_content
+ background: "develop-overview-hero-bg.jpg"
+%}
+
+
+
+
+
+{% capture content_with_toc %}
+
+## Firefox Tools
+
+### Development tools
+
+All you need to create extensions for Firefox is a [text editor](https://developer.mozilla.org/docs/Learn/Common_questions/Available_text_editors) and [a version of Firefox](/documentation/develop/choosing-a-firefox-version-for-extension-development/) to support your testing. Mozilla and the Firefox extension developer community have also created a number of [extension development tools](/documentation/develop/browser-extension-development-tools/) that can simplify the coding and testing of your extension.
+
+### web-ext command line tool
+
+The web-ext tool can help you by:
+
+- providing features to automatically reload your extension preview as the code changes
+- assist with debugging
+- create extension packages, and more
+
+{% endcapture %}
+{% include modules/column-w-toc.liquid,
+ id: "firefox-tools"
+ content: content_with_toc
+%}
+
+
+
+
+
+
+
+
+
+{% capture content %}
+
+## User Experience
+
+{% endcapture %}
+{% include modules/one-column.liquid,
+ content: content
+%}
+
+
+
+
+
+{% capture col_1_content %}
+
+
+
+{% endcapture %}
+{% capture col_2_content %}
+
+Having an exceptional user experience is crucial to attracting, and retaining, users of your extension.
+
+[RememBear](https://addons.mozilla.org/firefox/addon/remembear-app/) is a great example of an extension with an outstanding user experience.
+
+{% endcapture %}
+{% include modules/two-column.liquid,
+ col_1: col_1_content
+ col_2: col_2_content
+ reverse: false
+%}
+
+
+
+
+
+{% capture content %}
+
+### Make a great first impression
+
+Focus on a slick [onboarding flow](/documentation/develop/onboard-upboard-offboard-users/) that gets users up to speed with your extension quickly.
+
+If your extension collects user data during onboarding, make sure you follow the [best practices for collecting user data consent](/documentation/develop/best-practices-for-collecting-user-data-consents/). And, it’s important that you [request the right permissions](/documentation/develop/request-the-right-permissions/).
+
+### Put your user first
+
+Keep your users engaged and follow the [user experience best practices](/documentation/develop/user-experience-best-practices/). And, don’t forget to [build an accessible extension](/documentation/develop/build-an-accessible-extension/), so that everyone can make use of it.
+
+Lastly, [building a secure extension](/documentation/develop/build-a-secure-extension/) is fundamental to delivering an excellent user experience.
+
+### Define your value proposition
+
+Users are less likely to install an extension if they don’t understand what it does and what value it adds to their browsing experience.
+Find out best practices for putting your best foot forward with your extension.
+
+{% endcapture %}
+{% include modules/one-column.liquid,
+ content: content
+%}
+
+
+
+
+
+
+
+
+
+
+
+
+
+{% capture content %}
+
+## Firefox for Android
+
+{% endcapture %}
+{% include modules/one-column.liquid,
+ content: content
+%}
+
+
+
+
+
+{% capture col_1_content %}
+
+
+
+{% endcapture %}
+{% capture col_2_content %}
+
+### Understanding how to develop extensions for Android
+
+To offer your extension to Firefox for Android users, you need to consider some [differences between Firefox for the desktop and Android](/documentation/develop/differences-between-desktop-and-android-extensions/).
+
+Get started with everything you need to know about [developing for Firefox for Android](/documentation/develop/developing-extensions-for-firefox-for-android/).
+
+{% endcapture %}
+{% include modules/two-column.liquid,
+ col_1: col_1_content
+ col_2: col_2_content
+ reverse: true
+%}
+
+
+
+
+
+{% capture content %}
+
+### Creating browser experiences for Android apps
+
+If you develop Android apps, when you want to include a browser experience in your app you can take advantage of the browser engine that underpins Firefox using the [GeckoView Extensions Android library](https://github.com/mozilla/geckoview).
+
+{% endcapture %}
+{% include modules/one-column.liquid,
+ content: content
+%}
+
+
+
+
+
+
+
+
+
+
+
+
+
+{% capture content %}
+
+## Port to Firefox
+
+{% endcapture %}
+{% include modules/one-column.liquid,
+ content: content
+%}
+
+
+
+
+
+{% capture col_1_content %}
+
+
+
+{% endcapture %}
+{% capture col_2_content %}
+
+### Bring your Chrome extension to Firefox
+
+The Firefox extension environment is highly compatible with Chromium-based extension technology. Your extension might already be capable of running on Firefox, or need only a few changes.
+
+Check out our [porting guide](/documentation/develop/porting-a-google-chrome-extension/) to get started.
+
+{% endcapture %}
+{% include modules/two-column.liquid,
+ col_1: col_1_content
+ col_2: col_2_content
+ reverse: true
+%}
+
+
+
+
+
+
+
+
+
+
+
+
+
+{% capture content %}
+
+## Test and debug
+
+### Make sure your extension is running right
+
+Test and [debug your code](/documentation/develop/debugging/) by [temporarily installing](/documentation/develop/temporary-installation-in-firefox/) it in Firefox.
+
+Understanding [extensions and the Add-on ID](/documentation/develop/extensions-and-the-add-on-id/) will help you test more effectively. You will also want to [test persistent and restart features](/documentation/develop/testing-persistent-and-restart-features/) along with [permission requests](/documentation/develop/test-permission-requests/).
+
+You can use [web-ext](/documentation/develop/getting-started-with-web-ext/) to automatically install and update your extension while making coding changes.
+
+{% endcapture %}
+{% include modules/one-column.liquid,
+ content: content
+%}
+
+
+
+
+
+
diff --git a/src/content/documentation/develop/browser-compatibility.md b/src/content/documentation/develop/browser-compatibility.md
index 77966b76a..c415a30f2 100644
--- a/src/content/documentation/develop/browser-compatibility.md
+++ b/src/content/documentation/develop/browser-compatibility.md
@@ -7,7 +7,7 @@ topic: Develop
tags: [beginner, extensions, webextensions, compatibility, cross-browser]
contributors: [rebloor]
last_updated_by: rebloor
-date: 2019-05-27 6:35:30
+date: 2026-08-05
---
@@ -27,15 +27,18 @@ date: 2019-05-27 6:35:30
{% capture content_with_toc %}
-While work continues to standardize the APIs used for browser extension development, there remain differences between Chromium-based browsers—such as Chrome, Opera, and the Chromium-based Microsoft Edge—and Firefox. These differences, summarized on this page, include:
+All browsers have the same baseline support for namespace (`browser.*`) and promises:
-- **Namespace**: In Chromium-based browsers, JavaScript APIs are accessed under the `chrome` namespace. In Firefox, they are accessed under the `browser` namespace.
-- **Asynchronous APIs**: In Chromium-based browsers, asynchronous APIs are implemented using callbacks. In Firefox, asynchronous APIs are implemented using promise.
-- **API support**: Support for JavaScript APIs differs among browsers.
+- Firefox and Safari supported the `browser.*` namespace and promises from inception.
+- Chromium-based browsers (such as Chrome, Opera, and Microsoft Edge) introduced promises with Manifest V3 in their `chrome.*` namespace. Support for the `browser.*` namespace was added [in 2026](https://developer.chrome.com/docs/extensions/develop/concepts/browser-namespace), along with promise support in all asynchronous methods.
+
+While work continues to standardize the browser extension APIs, differences remain among the Firefox, Safari, and Chromium-based browsers. These differences, summarized on this page, include:
+
+- **API support**: JavaScript API support varies among browsers.
- **Manifest key support**: Support for `manifest.json` keys differs among browsers.
- Variations due to differences in browser behavior.
-Firefox is the most compliant with the proposed standard, and is, therefore, your best place to start when developing browser extensions. A simple way of addressing many of these differences is by using the [web extension polyfill library](https://github.com/mozilla/webextension-polyfill). For an introduction to using this tool, see [Building a cross-browser extension](https://developer.mozilla.org/docs/Mozilla/Add-ons/WebExtensions/Build_a_cross_browser_extension). Note, however, that the polyfill does not support Firefox exclusive APIs that are not available in Chrome.
+For information on building an extension that works on multiple browsers and accounts for these differences, see [Building a cross-browser extension](https://developer.mozilla.org/docs/Mozilla/Add-ons/WebExtensions/Build_a_cross_browser_extension).
{% endcapture %}
{% include modules/column-w-toc.liquid,
@@ -49,14 +52,17 @@ Firefox is the most compliant with the proposed standard, and is, therefore, you
{% capture content %}
-## Namespace
+## Namespace and asynchronous methods
-You reference all extensions API functions using a namespace, for example, `browser.alarms.create({delayInMinutes});` would create an alarm in Firefox that goes off after the time specified in `delayInMinutes`.
+You reference all extensions APIs using a namespace. For example, `browser.alarms.create({delayInMinutes});` creates an alarm that goes off after the time specified in `delayInMinutes`.
-There are two API namespaces in use:
+All major browsers now support the `browser` namespace and promises for asynchronous methods. Chromium-based browsers (such as Chrome, Opera, and Microsoft Edge) originally used the `chrome` namespace with callbacks. They progressively included support for promises in the `chrome` namespace, completing the full implementation along with support for the `browser` namespace in mid-2026.
-- `browser`(the proposed standard) is used in Firefox. For example: `browser.browserAction.setIcon({path: "path/to/icon.png"});`
-- `chrome` is used in Chromium-based browsers. For example: `chrome.browserAction.setIcon({path: "path/to/icon.png"});`
+::: note
+As a porting aid, Firefox supports `chrome` using callbacks, alongside `browser` using promises. This means that many older Chrome extensions work in Firefox without changes, unless they use Chrome-specific APIs that don’t exist in Firefox.
+:::
+
+To target older Chromium-based browsers with extensions written using the `browser` namespace and promises, use the [webextension-polyfill](https://github.com/mozilla/webextension-polyfill).
{% endcapture %}
{% include modules/one-column.liquid,
@@ -70,15 +76,13 @@ There are two API namespaces in use:
{% capture content %}
-## Asynchronous
-
-JavaScript provides several ways in which to handle asynchronous events. The proposed extensions API standard is to use the promise object. The promise approach provides significant advantages when dealing with chained asynchronous event calls.
+## Promises
-Firefox uses the promise object for all asynchronous WebExtensions APIs. Chromium-based browsers use callbacks.
+JavaScript provides several ways to handle asynchronous events. The extensions API standard is to use the promise object. The promise approach offers significant advantages when handling chained asynchronous event calls.
-As a porting aid, the Firefox WebExtension APIs supports `chrome` using callbacks and `browser` using promise. This means that many Chrome extensions will work in Firefox without changes, unless they are using Chrome specific APIs that don’t exist in Firefox.
+Firefox has always used the promise object. Chromium-based browsers historically supported callbacks through the `chrome` namespace, which is why many extensions and samples use callbacks. Chromium-based browsers now support promises through the `browser` namespace, so you no longer need to design around this for current browser versions.
-In Chrome, asynchronous APIs use callbacks to return values, and [`runtime.lastError`](https://developer.mozilla.org/docs/Mozilla/Add-ons/WebExtensions/API/runtime/lastError) to communicate errors:
+So, extensions and samples written against the older, callback-only Chrome APIs use the `chrome` namespace, with callbacks to return values, and [`runtime.lastError`](https://developer.mozilla.org/docs/Mozilla/Add-ons/WebExtensions/API/runtime/lastError) to communicate errors:
```js
function logCookie(c) {
@@ -92,7 +96,7 @@ function logCookie(c) {
chrome.cookies.set({ url: "https://developer.mozilla.org/" }, logCookie);
```
-The equivalent WebExtensions API code using [promise](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise):
+The equivalent code using the `browser` namespace and [promises](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise):
```js
function logCookie(c) {
@@ -121,7 +125,7 @@ If you are unfamiliar with how JavaScript can handle asynchronous events or prom
{% capture content %}
-## API Coverage
+## API coverage
The differences in the extensions API function implementations among the browsers fall into two broad categories:
diff --git a/src/content/documentation/develop/browser-extension-development-tools.md b/src/content/documentation/develop/browser-extension-development-tools.md
index 5b6119731..e26690fc7 100644
--- a/src/content/documentation/develop/browser-extension-development-tools.md
+++ b/src/content/documentation/develop/browser-extension-development-tools.md
@@ -18,7 +18,7 @@ tags:
]
contributors: [rebloor, hellosct1, ani-sha, ankushduacodes]
last_updated_by: rebloor
-date: 2023-06-02
+date: 2026-08-05
---
@@ -211,9 +211,13 @@ To get started, add the plug-in to your `webpack.config.js`.
### WebExtension browser API Polyfill
-When creating extensions you want to work in Firefox and Chrome, this library enables you to use the Firefox Promise-based APIs and have them run on Google Chrome with few, if any, changes.
+When creating extensions you want to work in Firefox and Chrome, this library enables you to use the Firefox promise-based APIs and have them run on Google Chrome with few, if any, changes.
-To get started, install using npm and load the library into the contexts where browser APIs are accessed.
+However, starting with Chrome 148, Chrome supports the `browser` namespace, except in extensions that include a DevTools page. That limitation was removed in Chrome 152 (see [Chrome bug 500769389](https://crbug.com/500769389)), and the `browser` namespace became available to all Chrome extensions.
+
+This means that all major browsers use the `browser` namespace and return promises for asynchronous functions. This polyfill is a no-op in Chrome 148 and later.
+
+If you want to enable your extension for Chrome 147 or earlier, get started by installing with npm and loading the library in the contexts where browser APIs are accessed.
[Get started](https://github.com/mozilla/webextension-polyfill/#installation)