XZ

Xiao Z's blog

Learn, build, share

Developing the OneNav Browser Extension: A Developer's Experience

oneNav browser extensionWXT frameworkVue3 extension developmentFirefox extension debuggingcross-browser extension
Published·Modified·

Recently, we released version 1.1.0 of the OneNav browser extension, which is the second version after a major refactor. During this process, we encountered several technical challenges, but ultimately resolved them. In this article, I will share the technologies and experiences used by xiaoz in developing the OneNav browser extension.

02d0d5634eaf4d33.png

About OneNav

OneNav is an open-source, free bookmark (navigation) management program developed by xiaoz using PHP + SQLite 3. It features a clean interface, simple installation, and ease of use. OneNav helps you centrally manage browser bookmarks, solving the difficulties of synchronization and access across devices, platforms, and browsers. With a single deployment, it can be accessed anywhere.

If you are not familiar with OneNav, you can refer to this article: A quick guide to 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 since its release, undergoing two major refactors.

First Version

The first version was developed using Bootstrap4 + jQuery. At that time, it only supported Chromium-based browsers. After using it for a while, we found serious performance issues, with frequent lagging.

First Refactor

The second version was refactored using the technology stack "Vue3 + vitesse-webext + Vant 4". However, after going live, the following issues were discovered:

  1. Vant 4 is a component library originally designed for mobile devices, and its experience on PC browsers is not very friendly, especially regarding certain interactions.
  2. Although vitesse-webext supports Firefox, the compilation never passed, and the issue could not be resolved.

Ultimately, we had to abandon the "vitesse-webext + Vant 4" solution.

Second Refactor

The third version, which is the current 1.1.0 version, underwent another refactor. This time, the adopted technical solution is "Vue3 + WXT + Element Plus". WXT is the next-generation Web extension framework. Its key advantage is that it can compile extensions for Chrome, Firefox, and Safari browsers using a single codebase. This feature is particularly important; otherwise, developing and adapting for each browser separately would require a significant amount of work.

When using the vitesse-webext solution, we encountered Firefox compilation issues, but with WXT, the compilation was very smooth, and different browsers passed compilation successfully.

56d3bd1f368a6ccb.png

WXT Official Website: https://wxt.dev/

Experiences in Developing Browser Extensions with WXT

The actual development process using WXT was not entirely smooth, and we encountered many issues, but they were eventually resolved. Here are the experiences we summarized:

  • To set the extension title and description, edit the corresponding file: package.json.
  • If importing Element Plus on-demand, you need to modify wxt.config.ts instead of vite.config.ts.
  • WXT does not support vue-router. It seems that no browser extension supports vue-router. Therefore, in browser extension development, I used Vue dynamic components to solve this.
  • WXT's storage supports cross-page communication. For example, popup, content, and background can communicate with each other using storage. Therefore, if cross-page communication is needed, it is recommended to use WXT's storage. If not, you can directly use the HTML5 native localStorage.
  • 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 the alternative for axios is fetch.

Compiling Code

WXT compiles Chrome extensions by default. You can use the command pnpm build to compile. The compiled directory is .output/chrome-mv3. To compile a Firefox extension, simply add the parameter:

# WXT compiles Firefox extension
pnpm build --browser firefox --mv3

Firefox uses the mv2 version by default. To avoid future upgrade issues, I directly added the --mv3 parameter to specify the latest mv3 version.

Similarly, to compile an Edge extension, use the following command:

pnpm build --browser edge

I originally intended to support Safari, but due to Apple's closed ecosystem, I could not find a way to install third-party extensions for debugging, so I had to give up support for the Safari browser.

Issues Encountered with WXT in Firefox

After compiling the Firefox extension, I attempted to debug it under Firefox and found that Firefox could not install third-party extensions, displaying the error "This add-on cannot be installed because it has not been verified." You can refer to this article for a solution: How to solve Firefox error "This add-on cannot be installed because it has not been verified".

Firefox browser extensions must specify an ID in manifest.json; otherwise, installation and listing will prompt that the ID does not exist, preventing installation. I searched through the WXT documentation but found no instructions regarding Firefox IDs. Therefore, I manually modified the manifest.json after compilation and added the following content to specify the ID:

"applications": {
    "gecko": {
      "id": "oneNav@example.com"
    }
  }

ChatGPT explained why Firefox extensions need an ID:

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

Chrome browsers do not require this ID; otherwise, a warning will appear (which does not affect the extension's operation).

Publishing the Browser Extension

Currently, xiaoz has published the OneNav browser extension on Chrome WEB Store, Firefox ADD-ONS, and Microsoft Edge Extensions. However, the Microsoft Edge extension is still under review, while Chrome and Firefox are already published.

The developer platforms for Chrome, Edge, and Firefox are as follows:

Among these, Chrome requires a one-time developer fee of $5, while Edge and Firefox are free, allowing you to submit your extension without any cost. When submitting the extension, follow the platform's rules. There are a few points to note:

  1. The compiled extension from WXT exists in the .output directory. When packaging the extension into a .zip file, do not include subfolders.
  2. Chrome and Edge have strict requirements for the promotional image dimensions of extensions; even a one-pixel difference is not allowed.

My impression is that the Chrome platform is the most standardized and strict. Every extension permission must be explicitly explained by the developer as to why it is needed. In contrast, Edge and Firefox are much more lenient.

Auxiliary Tools

During development, xiaoz used a third-party auxiliary tool to generate extension icons in different sizes. The address is: Chrome Extension Icon Generator

Conclusion

Above are some insights and experiences shared by xiaoz in developing the OneNav browser extension. I hope this helps other developers. If you plan to support multiple browsers, I highly recommend trying WXT, the next-generation Web extension framework, which can significantly improve efficiency.

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

a9baef7e39b3efd6.png