# webextensions-examples: Mozilla's Reference Collection for Firefox Add-on Development > webextensions-examples is a collection of complete, installable Firefox add-ons maintained by Mozilla's Add-ons team to demonstrate the WebExtensions API. Each example in the repository is a self-contained extension that can be loaded directly into Firefox for experimentation and used as a starting point for new add-on projects. **mdn/webextensions-examples** — Example Firefox add-ons created using the WebExtensions API - Repository: https://github.com/mdn/webextensions-examples - Website: https://developer.mozilla.org/en-US/Add-ons/WebExtensions - Stars: 4,479 · Forks: 2,618 - Language: JavaScript - License: MPL-2.0 - Published: 2026-09-23 · Updated: 2026-09-23 · Language: en - Canonical page: https://hysenlabs.com/projects/mdn-webextensions-examples ## What webextensions-examples Is and Who Uses It The WebExtensions API is a cross-browser standard for building browser extensions that was originally established for Chrome and Firefox. Mozilla's webextensions-examples repository is the official companion to the WebExtensions documentation on MDN. It gives developers working, installable examples for each major API area instead of documentation snippets that still need to be turned into a runnable extension. The primary audience is developers learning the API for the first time, developers who want to see a concrete reference implementation of a specific WebExtensions API before using it in a production add-on, and developers porting existing add-ons to the WebExtensions standard. Mozilla's Add-ons team maintains the repository, and contributions of new examples, features, and bug fixes are accepted according to CONTRIBUTING.md. ## Repository Layout and How to Find the Right Example Each example occupies its own top-level directory, named after what it demonstrates. The directory listing includes examples such as annotate-page, apply-css, beastify, bookmark-it, borderify, chill-out, commands, content-script-register, contextual-identities, cookie-bg-picker, devtools-panels, dynamic-theme, emoji-substitution, find-across-tabs, history-deleter, and several others. Each example directory includes its own short README explaining what the example does and any restrictions on which pages or domains it works with. The README for the main repository points to the "Example extensions" page on MDN for a full indexed listing with descriptions. The repository root also contains an examples.json file with structured metadata and an examples.schema.json that documents the schema of that file. The package.json at the root provides a validation script: running npm test runs ESLint over the repository and then runs validate.js, which checks that every example's entry in examples.json conforms to examples.schema.json. ## Installing and Running an Example in Firefox The README provides two methods for loading an example into Firefox. The first uses Firefox's built-in developer mode: open about:debugging, click Load Temporary Add-on, and select the manifest.json file from within the example's directory. The extension is loaded for the current session and unloaded when Firefox restarts. The second method uses the web-ext command-line tool, which Mozilla provides for extension development. Open the example's directory in a terminal and run: ``` web-ext run ``` web-ext launches a fresh Firefox profile with the extension already installed and automatically reloads the extension whenever a source file changes. This automatic reloading is highlighted in the README as an advantage over the manual about:debugging workflow for active development. The README specifies using the most recent release of Firefox, though it notes that most examples work with earlier releases. Examples that require pre-release Firefox APIs declare a minimum version in the strict_min_version attribute of their manifest.json browser_specific_settings key. ## Restrictions and Known Limitations of the Examples None of the examples in the repository work in Firefox private browsing windows by default, as the README states. Enabling an extension in private windows is a separate permission that must be granted through Firefox's extension settings, documented by Mozilla at the URL in the README. Some examples are restricted to specific domains or pages. The README instructs users to read each example's individual README for these restrictions. The examples do not follow production hardening practices. They are minimal demonstrations of API usage without input validation, error handling, or security review beyond what is needed to illustrate the API. Using them as a direct starting point for a production extension requires additional work. ## Chrome Compatibility: What the browser Namespace Means All examples in the repository use the browser namespace and Promise-based callbacks, which is the standard for Firefox WebExtensions. Chrome uses the chrome namespace and callback-based APIs. The README states that examples will not work in Chrome without Mozilla's webextension-polyfill, which translates the browser namespace and Promises into Chrome's chrome namespace and callback style. The README notes that these examples are tested in Firefox and may work in other browsers that support the relevant APIs. The MDN WebExtensions documentation includes a browser support table for each API, which is the recommended resource for checking which browsers support a given feature. Edge and Opera support large subsets of the API, but testing with Chrome requires the polyfill. ## What the Repository Does Not Provide webextensions-examples does not include examples for every WebExtensions API. The examples collection focuses on commonly used APIs and does not track API additions immediately. The README does not make a completeness claim, and the MDN documentation is the authoritative reference for what APIs exist. The repository also does not cover native messaging in the same lightweight way as other examples. The native-messaging directory is present, but native messaging requires a host application running on the user's machine, which is a more complex setup than other examples. The README for the main repository does not document the native messaging setup separately. There are no bundled build tools or module bundlers. Each example is plain JavaScript, HTML, and CSS with a manifest.json. Projects using TypeScript or a module bundler must adapt the examples to their own build pipeline. ## Chrome Extension Samples: A Parallel Resource for Chrome Google maintains its own repository of Chrome extension samples at github.com/GoogleChrome/chrome-extensions-samples. The fundamental difference is the API namespace: Chrome samples use the chrome namespace and callback-based APIs, while webextensions-examples uses the browser namespace and Promises. For developers who need to support both Chrome and Firefox, the choice is to start from one set and apply the polyfill for the other, or to maintain both code paths. The WebExtensions API was designed for cross-browser compatibility, but the namespace difference and some API gaps mean that zero-effort portability is not guaranteed. The MDN documentation tracks per-API browser support and is the practical guide for which features need conditional code. ## Maintenance Status and License The last push to the repository was on 2026-09-23. The repository is not archived and is maintained by Mozilla's Add-ons team. The examples are made available under the Mozilla Public License 2.0 (MPL-2.0), which is a weak copyleft license. The MPL-2.0 allows code from the repository to be used in proprietary projects, with the requirement that modifications to the MPL-licensed files themselves are shared back under the same license. ## Conclusion webextensions-examples is the right starting point for anyone learning the WebExtensions API to build Firefox add-ons, or for developers who want a tested reference when using an unfamiliar API. The examples are not production-hardened extensions; they are minimal demonstrations, and the README notes that none of them work in private browsing windows by default. Chrome developers should expect to need Mozilla's webextension-polyfill before running these examples in Chrome, because they use the browser namespace rather than the chrome namespace. ## FAQ ### What is an example of a browser extension built with the WebExtensions API? The webextensions-examples repository contains dozens of complete Firefox extensions demonstrating specific API areas, including borderify (which adds a border to web pages), bookmark-it (for bookmarking the current page), and dynamic-theme (for changing the browser theme). Each example is in its own directory with a manifest.json and a README describing what it does. ### Do the webextensions-examples work in Chrome? The examples use the browser namespace and Promises, which is the Firefox convention. Chrome uses the chrome namespace and callbacks. The README states they will not work in Chrome unless you apply Mozilla's webextension-polyfill, which bridges the two APIs. ### How do you load a webextensions-examples extension into Firefox? Open about:debugging in Firefox, click Load Temporary Add-on, and select the manifest.json file inside the example's directory. Alternatively, install the web-ext tool, navigate to the example directory, and run web-ext run to launch Firefox with the extension automatically installed and auto-reloading on file changes. ## Sources - [Issues](https://github.com/mdn/webextensions-examples/issues) - [License: MPL-2.0](https://github.com/mdn/webextensions-examples/blob/main/LICENSE) - [mdn/webextensions-examples on GitHub](https://github.com/mdn/webextensions-examples) - [Project website](https://developer.mozilla.org/en-US/Add-ons/WebExtensions) - [README](https://github.com/mdn/webextensions-examples/blob/main/README.md) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/mdn-webextensions-examples