### Detecting Extension Installation Source: https://github.com/mozilla/extension-workshop/blob/master/src/content/documentation/develop/onboard-upboard-offboard-users.md Listen for the 'install' event using `runtime.onInstalled` to trigger onboarding actions. This snippet shows how to open a new tab or popup window with onboarding content upon installation. It skips execution during development if the extension is temporarily installed. ```javascript browser.runtime.onInstalled.addListener(async ({ reason, temporary }) => { if (temporary) return; // skip during development switch (reason) { case "install": { const url = browser.runtime.getURL("views/installed.html"); await browser.tabs.create({ url }); // or: await browser.windows.create({ url, type: "popup", height: 600, width: 600, }); } break; // see below } }); ``` -------------------------------- ### Check web-ext installation Source: https://github.com/mozilla/extension-workshop/blob/master/src/content/documentation/develop/getting-started-with-web-ext.md After installation, run this command to verify that web-ext is installed correctly and display its version number. ```shell web-ext --version ``` -------------------------------- ### Example Manifest with Required and Optional Data Source: https://github.com/mozilla/extension-workshop/blob/master/src/content/documentation/develop/firefox-builtin-data-consent.md This example manifest.json file demonstrates how to specify 'locationInfo' as a required data type and 'technicalAndInteraction' as an optional data type. This configuration affects the installation prompt and about:addons display. ```json { "manifest_version": 2, "name": "Example - Data collection with fallback", "version": "1.0.0", "permissions": [ "storage", "management" ], "browser_specific_settings": { "gecko": { "id": "@example-data-collection-with-fallback", "data_collection_permissions": { "required": [ "locationInfo" ], "optional": [ "technicalAndInteraction" ] } } }, "background": { "scripts": [ "background.js" ] }, "browser_action": {}, "options_ui": { "page": "options/page.html" } } ``` -------------------------------- ### Install web-ext with Homebrew Source: https://github.com/mozilla/extension-workshop/blob/master/src/content/documentation/develop/getting-started-with-web-ext.md Use this command to install the web-ext tool if you are using Homebrew on macOS. ```shell brew install web-ext ``` -------------------------------- ### Install web-ext with npm Source: https://github.com/mozilla/extension-workshop/blob/master/src/content/documentation/develop/getting-started-with-web-ext.md Use this command to install the web-ext tool globally using npm, the Node.js package manager. ```shell npm install --global web-ext ``` -------------------------------- ### Start Local Development Server Source: https://github.com/mozilla/extension-workshop/blob/master/README.md Starts the Eleventy static site generator for local development. This includes unpublished content marked with `published: false`. ```bash yarn start ``` -------------------------------- ### Install Project Dependencies Source: https://github.com/mozilla/extension-workshop/blob/master/README.md Installs the necessary packages for the project using Yarn. Ensure Node.js LTS and Yarn are installed beforehand. ```bash yarn install ``` -------------------------------- ### Block Example Names Source: https://github.com/mozilla/extension-workshop/blob/master/src/content/sidebar-master-template.md Examples of block-style names for extensions, illustrating good naming practices. ```Liquid {% capture example %} Examples: An extension that saves passwords is called **Remembear** An extension that puts a cat on new tabs is called **Tabbycat** An extension that improves YouTube is called **Enhancer for YouTube** {% endcapture %} {% include modules/example.liquid, content: example layout: "block" %} ``` -------------------------------- ### Inline Example Name Source: https://github.com/mozilla/extension-workshop/blob/master/src/content/sidebar-master-template.md An example of an inline name for an extension. ```Liquid {% include modules/example.liquid, content: "Example: TrLrs! Tab Changer." layout: "inline" %} ``` -------------------------------- ### Open Browser Console on Startup Source: https://github.com/mozilla/extension-workshop/blob/master/src/content/documentation/develop/web-ext-command-reference-v7.md Use the --browser-console flag to open the Browser Console when starting web-ext. This is useful for viewing extension log messages. ```shell web-ext run --browser-console ``` -------------------------------- ### Listen for new extension installation and uninstall self Source: https://github.com/mozilla/extension-workshop/blob/master/src/content/documentation/manage/retiring-your-extension.md Use `management.onInstalled` to detect when a new extension is installed, and then use `management.uninstallSelf` to remove the current extension. This is useful when replacing an extension with a new one. ```javascript browser.management.onInstalled.addListener(details => { if (details.reason === "install" && details.id === "new-extension-id") { browser.management.uninstallSelf(); } }); ``` -------------------------------- ### View Command-Specific Options Source: https://github.com/mozilla/extension-workshop/blob/master/src/content/documentation/develop/getting-started-with-web-ext.md Get help for a specific web-ext command by appending the command name to --help. ```shell web-ext --help run ``` -------------------------------- ### Configure web-ext options in package.json Source: https://github.com/mozilla/extension-workshop/blob/master/src/content/documentation/develop/getting-started-with-web-ext.md Specify web-ext configuration options within the 'webExt' property of your package.json file. This example sets the 'sourceDir'. ```json { "name": "an-extension-src-dir-with-a-package-json", "version": "1.0.0", ... "webExt": { "sourceDir": "dist/extension/" } } ``` -------------------------------- ### Open Developer Tools on Startup Source: https://github.com/mozilla/extension-workshop/blob/master/src/content/documentation/develop/web-ext-command-reference-v7.md Use the --devtools flag to automatically open the Developer Tools for the installed extension upon startup. This requires Firefox 106 or newer. ```shell web-ext run --devtools ``` -------------------------------- ### Correct Third-Party Library Link Example Source: https://github.com/mozilla/extension-workshop/blob/master/src/content/documentation/publish/third-party-library-usage.md Provide a link to the exact file of a third-party library using the release tag. This ensures reviewers can verify the library version using checksums. ```text https://github.com/ccampbell/mousetrap/blob/1.4.2/mousetrap.min.js ``` -------------------------------- ### Allowed Minified Code Example Source: https://github.com/mozilla/extension-workshop/blob/master/src/content/documentation/publish/source-code-submission.md This example demonstrates minified JavaScript that reduces file size while retaining code meaning. It is acceptable for submission. ```js var d=document;var o=JSON.parse(responseText);var e=d.createElement("div");e.className=o.className;e.textContent="Your favorite color is now "+o.color;addonElement.appendChild(e); ``` -------------------------------- ### Configure array options in config file Source: https://github.com/mozilla/extension-workshop/blob/master/src/content/documentation/develop/getting-started-with-web-ext.md Define options that can be specified multiple times as an array. This example sets multiple --ignore-files patterns. ```javascript export default { ignoreFiles: [ 'package-lock.json', 'yarn.lock', ], }; ``` -------------------------------- ### Pre-install Extension Source: https://github.com/mozilla/extension-workshop/blob/master/src/content/documentation/develop/web-ext-command-reference-v7.md The --pre-install option pre-installs the extension into the profile before starting the browser, which is necessary for Firefox versions older than 49. This option also implies --no-reload. ```shell --pre-install ``` -------------------------------- ### Example pages.json Structure Source: https://github.com/mozilla/extension-workshop/blob/master/README.md This JSON structure outlines how pages, subfolders, categories, and subpage items are organized for the Extension Workshop documentation. ```json [ { "title": "Documentation Topics", "subfolderitems": [ { "title": "Develop", "url": "/documentation/develop/", "subpageitems": [ { "title": "Firefox Tools", "id": "firefox-tools" } ], "categories": [ { "category": "Getting Started", "pages": [ { "title": "Firefox Workflow Overview", "url": "/documentation/develop/firefox-workflow-overview/" } ] } ] }, { "title": "Publish", "url": "/documentation/publish/", "subpageitems": [ { "title": "Get your extension signed", "id": "get-your-extension-signed" } ] }, { "title": "Manage", "url": "/documentation/manage/", "subpageitems": [ { "title": "Stay informed when Firefox changes", "id": "stay-informed-when-firefox-changes" } ] }, { "title": "Enterprise", "url": "/documentation/enterprise/", "subpageitems": [ { "title": "Section Title", "id": "introduction" } ] }, { "title": "Themes", "url": "/documentation/themes/", "subpageitems": [ { "title": "What themes are", "id": "what-themes-are" } ] } ] }, { "title": "Extension Basics", "url": "/extension-basics/", "subpageitems": [ { "title": "Getting started", "id": "getting-started" } ] }, { "title": "Community", "url": "/community/", "subpageitems": [ { "title": "Who is part of the community?", "id": "who-is-part-of-the-community" } ], "categories": [ { "category": "About the Community", "pages": [ { "title": "", "url": "" } ] } ] } ] ``` -------------------------------- ### Run extension with specified source directory Source: https://github.com/mozilla/extension-workshop/blob/master/src/content/documentation/develop/web-ext-command-reference-v7.md Use the `--source-dir` option to specify the extension's source code directory. This example sets the source directory to '/path/to/my/extension'. ```shell web-ext run --source-dir=/path/to/my/extension ``` -------------------------------- ### Markdown Image Linking Example Source: https://github.com/mozilla/extension-workshop/blob/master/README.md Demonstrates how to link to images within markdown files, using the specified path structure from the assets directory. ```markdown ![Remembear subtitle screenshot](/assets/img/remembear-png "Remembear subtitle text") ``` -------------------------------- ### Build with multiple ignored files Source: https://github.com/mozilla/extension-workshop/blob/master/src/content/documentation/develop/web-ext-command-reference-v7.md Specify multiple glob patterns for ignored files by separating them with spaces. This example ignores files in 'path/to/first.js' and 'path/to/second.js'. ```shell web-ext build --ignore-files path/to/first.js path/to/second.js ``` -------------------------------- ### Set command-specific options in config file Source: https://github.com/mozilla/extension-workshop/blob/master/src/content/documentation/develop/getting-started-with-web-ext.md Nest configuration options under the command name to apply them only to that specific command. This example configures options for 'build' and 'run' commands. ```javascript export default { // Global options: verbose: true, // Command options: build: { overwriteDest: true, }, run: { firefox: 'nightly', }, }; ``` -------------------------------- ### Build with ignored files Source: https://github.com/mozilla/extension-workshop/blob/master/src/content/documentation/develop/web-ext-command-reference-v7.md Use the `--ignore-files` option to specify glob patterns for files to be ignored during the build process. This example ignores files ending with '.api-key'. ```shell web-ext build --ignore-files "*_/_.api-key" ``` -------------------------------- ### Specify source and artifact directories Source: https://github.com/mozilla/extension-workshop/blob/master/src/content/documentation/develop/getting-started-with-web-ext.md Use the --source-dir and --artifacts-dir options to specify custom directories for extension source code and build artifacts. This example builds an extension from a specific source directory into a 'zips' directory. ```shell web-ext build --source-dir=webextension-examples/notify-link-clicks-i18n --artifacts-dir=zips ``` -------------------------------- ### View All Commands and Options Source: https://github.com/mozilla/extension-workshop/blob/master/src/content/documentation/develop/getting-started-with-web-ext.md Display all available web-ext commands and their options. ```shell web-ext --help ``` -------------------------------- ### Firefox Browser Namespace Example Source: https://github.com/mozilla/extension-workshop/blob/master/src/content/documentation/develop/browser-compatibility.md Example of accessing the `browserAction` API using the `browser` namespace in Firefox. ```javascript browser.browserAction.setIcon({path: "path/to/icon.png"}); ``` -------------------------------- ### Open Browser at Specified URL Source: https://github.com/mozilla/extension-workshop/blob/master/src/content/documentation/develop/web-ext-command-reference-v7.md Configure the browser to open a specific URL upon startup. Multiple URLs can be opened by repeating the option. ```shell web-ext run --start-url www.mozilla.com ``` ```shell web-ext run --start-url www.mozilla.com --start-url developer.mozilla.org ``` -------------------------------- ### Chromium Browser Namespace Example Source: https://github.com/mozilla/extension-workshop/blob/master/src/content/documentation/develop/browser-compatibility.md Example of accessing the `browserAction` API using the `chrome` namespace in Chromium-based browsers. ```javascript chrome.browserAction.setIcon({path: "path/to/icon.png"}); ``` -------------------------------- ### Build Site for Production Source: https://github.com/mozilla/extension-workshop/blob/master/README.md Builds the static site for production deployment. This process optimizes assets and content. ```bash yarn build:production ``` -------------------------------- ### Build extension using web-ext Source: https://github.com/mozilla/extension-workshop/blob/master/src/content/documentation/publish/package-your-extension.md Use the `web-ext build` command to automatically package your extension, excluding common unwanted files like `.git`. ```bash web-ext build ``` -------------------------------- ### Example Manifest Validation Message Source: https://github.com/mozilla/extension-workshop/blob/master/src/content/documentation/develop/developing-extensions-for-firefox-for-android.md An example of a manifest validation message that might appear in `adb logcat` output. These messages can indicate why an add-on might fail to run. ```log I/Gecko (30440): 1496056181889 addons.xpi WARN Addon with ID @your-addon-id already installed, older version will be disabled ``` -------------------------------- ### Prohibited Obfuscated Code Example Source: https://github.com/mozilla/extension-workshop/blob/master/src/content/documentation/publish/source-code-submission.md This example shows obfuscated JavaScript, where the code's intent is masked using techniques like hex-encoded strings. This type of code is not permitted. ```js var _0x364e=['\x70\x61\x72\x73\x65','\x63\x72\x65\x61\x74\x65\x45\x6c\x65\x6d\x65\x6e\x74','\x64\x69\x76','\x63\x6c\x61\x73\x73\x4e\x61\x6d\x65','\x59\x6f\x75\x72\x20\x66\x61\x76\x6f\x72\x69\x74\x65\x20\x63\x6f\x6c\x6f\x72\x20\x69\x73\x20\x6e\x6f\x77\x20','\x61\x70\x70\x65\x6e\x64\x43\x68\x69\x6c\x64'];var _0x1dab=function(_0x440e53,_0x322e43){_0x440e53=_0x440e53-0x0;var _0x4b349d=_0x364e[_0x440e53];return _0x4b349d;};var data=JSON[_0x1dab('0x0')](responseText);var div=document[_0x1dab('0x1')](_0x1dab('0x2'));div[_0x1dab('0x3')]=data[_0x1dab('0x3')];div['\x74\x65\x78\x74\x43\x6f\x6e\x74\x65\x6e\x74']=_0x1dab('0x4')+data['\x63\x6f\x6c\x6f\x72'];addonElement[_0x1dab('0x5')](div); ``` -------------------------------- ### Build extension with configuration file Source: https://github.com/mozilla/extension-workshop/blob/master/src/content/documentation/develop/getting-started-with-web-ext.md Use the --config option to specify a configuration file for build commands. The configuration file must be an ES module. ```shell web-ext --config=my-config.mjs build ``` -------------------------------- ### Ordered List Markdown Source: https://github.com/mozilla/extension-workshop/blob/master/src/content/documentation/publish/create-an-appealing-listing.md Create ordered lists by starting each line with a number followed by a period and a space. ```markdown 1. List Item ``` -------------------------------- ### Chrome Cookies Set with Callback Source: https://github.com/mozilla/extension-workshop/blob/master/src/content/documentation/develop/browser-compatibility.md Example of setting a cookie in Chrome using callbacks and checking for errors with chrome.extension.lastError. ```javascript function logCookie(c) { if (chrome.extension.lastError) { console.error(chrome.extension.lastError); } else { console.log(c); } } chrome.cookies.set({ url: "https://developer.mozilla.org/" }, logCookie); ``` -------------------------------- ### Production Deploy Tagging Pattern Source: https://github.com/mozilla/extension-workshop/blob/master/README.md Tags matching this regular expression will trigger production deployments. An example tag is provided. ```regex ^20\d{2}\.\d{2}\.\d{2}(?:-\d+)?$ ``` -------------------------------- ### Configure signing keys in home directory config Source: https://github.com/mozilla/extension-workshop/blob/master/src/content/documentation/develop/getting-started-with-web-ext.md Set sensitive options like API keys for signing in a configuration file in your home directory. This is equivalent to using command-line arguments. ```javascript export default { "sign": { "apiKey": "", "apiSecret": "" } } ``` -------------------------------- ### Run Extension with Specific Firefox APK on Android Source: https://github.com/mozilla/extension-workshop/blob/master/src/content/documentation/develop/getting-started-with-web-ext.md If multiple Firefox versions are installed on an Android device, specify the APK to target a specific version. ```shell web-ext run --target=firefox-android ... --firefox-apk=org.mozilla.firefox ``` -------------------------------- ### web-ext docs Source: https://github.com/mozilla/extension-workshop/blob/master/src/content/documentation/develop/web-ext-command-reference.md Opens the web-ext documentation in the user's default browser. ```shell web-ext docs ``` -------------------------------- ### macOS Enterprise Policy Configuration Source: https://github.com/mozilla/extension-workshop/blob/master/src/content/documentation/enterprise/enterprise-development.md Example of a plist file for configuring Firefox enterprise policies on macOS. Administrators should integrate this with their existing configuration profiles. ```xml EnterprisePoliciesEnabled BlockAboutProfiles 3rdparty Extensions YOUR_EXTENSION_ID STRING value BOOLEAN INTEGER 10 ``` -------------------------------- ### Override environment variable with command-line option Source: https://github.com/mozilla/extension-workshop/blob/master/src/content/documentation/develop/web-ext-command-reference-v7.md A command-line option, such as `--source-dir`, will always override the corresponding environment variable. This example ignores the `WEB_EXT_SOURCE_DIR` setting. ```shell web-ext run --source-dir=/another/path/to/source ``` -------------------------------- ### web-ext build --overwrite-dest Source: https://github.com/mozilla/extension-workshop/blob/master/src/content/documentation/develop/web-ext-command-reference.md Use the --overwrite-dest option to overwrite the destination package file if it already exists. Without this option, web-ext will exit with an error if the destination file exists. ```shell web-ext build --overwrite-dest ``` -------------------------------- ### web-ext dump-config Source: https://github.com/mozilla/extension-workshop/blob/master/src/content/documentation/develop/web-ext-command-reference.md Outputs the tool's configuration settings in JSON format. ```shell web-ext dump-config ```