Recently, we released version 1.1.0 of the OneNav browser extension, which is the version after the second major refactor. We encountered some technical challenges during the process, but managed to overcome them in the end. Therefore, I plan to use this article to share the technologies and experiences Xiaoz used in developing the OneNav browser extension.

About OneNav

OneNav is an open-source free bookmark (navigation) management program developed by Xiaoz using PHP + SQLite 3. It has a simple interface, easy installation, and convenient usage. OneNav helps you centralize your browser bookmarks, solving the synchronization and access difficulties across devices, platforms, and browsers, enabling deployment in one place and access from anywhere.

For those who are not familiar with OneNav, you can refer to this article: A Quick Overview of the Open-source Free Bookmark (Navigation) Management Program OneNav

Two Refactors and Technology Selection

OneNav browser extension version 1.1.0 is the third version released, which went through two refactors.

First Version

The first version was developed using Bootstrap4 + native jQuery. At that time, it only supported Chromium-based browsers. After some usage, serious performance issues were discovered, often leading to lagging situations.

First Refactor

The second version underwent a refactor using the technology combination of "Vue3 + vitesse-webext + Vant 4". However, after the actual launch, the following issues were identified:

1. Vant 4 was originally designed for mobile devices and did not provide a very user-friendly experience on PC browsers, particularly in some interactions.
2. Although vitesse-webext supported Firefox, the compilation was not successful and the issues couldn't be resolved.

Eventually, the "vitesse-webext + Vant 4" approach had to be abandoned.

Second Refactor

The third version, which is the current 1.1.0 version, underwent another refactor. This time, the technology stack used was "Vue3 + WXT + Element Plus". WXT is a next-generation web extension framework that stands out for its ability to compile a set of code into extensions suitable for Chrome/Firefox/Safari browsers. This feature is particularly important, as developing and adapting separately for each browser would be a considerable amount of work.

During the use of the vitesse-webext approach, Firefox compilation issues were encountered. However, compilation with WXT was very smooth, and the code passed compilation for different browsers without any issues.

Some Experiences in Developing Browser Extensions with WXT

While using WXT in the development process, it was not entirely smooth, and several issues were encountered. However, they were eventually resolved, leading to the compilation of the following experiences:

• Setting extension title and description, corresponding to the file: package.json
• If element-plus is imported on demand, modifications need to be made in wxt.config.ts instead of vite.config.ts
• WXT does not support the use of vue-router. It seems that all browser extensions do not support vue-router. Therefore, Vue dynamic components were used to address this issue in browser extension development.
• The storage provided by WXT allows cross-page communication, enabling storage to be used interchangeably between popup/content/background pages. If cross-page communication is needed, it is recommended to use WXT's storage. Otherwise, HTML5's native localStorage can be used directly.
• Manifest information needs to be added in the wxt.config.ts file.
• background.js does not support alert() and axios. The alternative for alert is browser.notifications.create(), and for axios, it is fetch.

Compiling Code

WXT compiles Chrome extensions by default. Simply use the command: pnpm build for compilation, and the compiled directory will be in .output/chrome-mv3. For compiling Firefox extensions, just add the parameter:

# Compiling Firefox extension with WXT
pnpm build --browser firefox --mv3

Firefox defaults to the mv2 version. To avoid potential upgrade issues, the --mv3 parameter was added to specify the latest mv3 version. Similarly, for compiling Edge extensions, use the following command:

pnpm build --browser edge

Originally, there was also a plan to support Safari, but due to Apple's closed nature and the inability to find a method to install third-party extensions for Safari, the support for Safari browsers had to be abandoned.

Issues Encountered in Firefox with WXT

After compiling the Firefox extension, an attempt was made to debug it in Firefox, but it was found that Firefox does not allow the installation of third-party extensions and displays a message stating, "This add-on could not be installed because it has not been verified." The issue can be resolved by referring to this article: "Solution to Firefox Prompt 'This add-on could not be installed because it has not been verified'"

For Firefox browser extensions, it is necessary to specify an ID in the manifest.json. Otherwise, during installation and submission, an error stating that the ID does not exist will prevent the extension from being installed. Despite searching through the WXT documentation, no instructions regarding the Firefox ID were found. Therefore, after compilation, the manifest.json was manually modified to include the following content to specify the ID:

"applications": {
    "gecko": {
      "id": "[email protected]"
    }
  }

The reason Firefox extensions require an ID is explained by ChatGPT:

• Uniqueness: The ID ensures the uniqueness of the extension in Firefox, allowing Firefox to manage (e.g., update or delete) installed extensions correctly.
• Compatibility and Updates: In some cases, if an extension needs to be uploaded to Mozilla's extension site (AMO), Firefox can automatically assign an ID. However, specifying an ID when installing directly from a file or for development purposes is a good practice.

Chrome does not require this ID, but a warning prompt may appear (which does not affect the extension's operation)!!!

Publishing Browser Extensions

Currently, OneNav browser extension has been submitted to Chrome Web Store/Firefox Add-ons and Microsoft Edge Extensions. While Chrome and Firefox have been published, Microsoft Edge Extensions are still under review.

The developer platforms for Chrome/Edge/Firefox are as follows:

• Chrome: https://chrome.google.com/webstore/devconsole
• Edge: https://partner.microsoft.com/en-us/dashboard/microsoftedge/
• Firefox: https://addons.mozilla.org/zh-CN/developers/

Chrome requires a one-time developer fee of $5, while Edge and Firefox are free and do not require any fees to submit your extension. When submitting the extension, follow the platform's rules and instructions. Pay attention to the following:

1. Extensions compiled with WXT are located in the .output directory. When packaging the extension into a .zip file, do not include subfolders.
2. Chrome/Edge have strict requirements for the promotional image sizes of extensions. Even a one-pixel difference may not be accepted.

In my experience, the Chrome platform is the most standardized and strict. Developers must provide clear explanations for each permission used in the extension. On the other hand, Edge and Firefox platforms are more lenient.

Auxiliary Tools

During the development process, I used a third-party auxiliary tool to generate extension icons of different sizes. The tool can be accessed at: Chrome Extension Icon Generator

Conclusion

The above are some insights and experiences Xiaoz gained while developing the OneNav browser extension. I hope this sharing is helpful to developers. If you plan to support multiple browsers, I highly recommend trying out WXT, the next-generation web extension framework, which can significantly improve efficiency.

Additionally, I have created a discussion group for browser extension development. Interested friends can scan the QR code to join.