Building Browser Extensions with React - That Don't Break Browsers

Welcome, everyone. My name is Jonny Fekete, and I will talk about how to build web extensions with React that do not break browsers. So let's get started. I'm sure all of you are very familiar with working with React since this is a React conference. However, have you ever tried building a web extension using React? I can tell you it's not as easy as you're used to with your own web application. Why am I eligible to talk about the subject? Well, I've been working with production-ready web extensions for more than five years now, and I believe I faced a lot of challenges that really pushed the limits of what's possible with web extensions. Plus, I am contributing to some of the open-source communities projects in this field. And more than everything, I have a YouTube tutorial series called webextensiontutorial.com where you can learn for free about how to create web extensions.

But what are web extensions, you might ask? Well, they are just zip files, really, with manifest.json. That's all it takes to create a web extension. The manifest.json file is a simple JSON that describes what permissions are required, what is the name of the extension, the description, version number, and a lot of other configurations. And, basically, that's it. If you create a zip file with this, you can immediately start debugging and creating new extensions. However, you might have heard that a couple of years ago, Chrome went from manifest.v2 to manifest.v3. They introduced a more streamlined and safe version of manifest.json. In v2, you had persistent background scripts. You had full DOM access from the background. You could import React everywhere, even in the background script. You had access to the local storage and the session storage. And there were just a lot of APIs that were inconsistent.

And manifest.v3, it solves all these problems. It is a lot more restrictive on the extension side, but it gives a lot more power for the end users. And some examples why things are different. The background is now a service worker, so you can't really keep persistent background scripts. The scripts can fall asleep or die and then wake up based on certain triggers. You don't have local storage access. You have different storages that are web extension specific. All the APIs are now async and promise-based. And you have import restrictions, so you can't really import React into your background scripts. If you remember a few years ago, the community was very loud about this because these restrictions made it difficult for ad blockers to function and people were blaming Google for introducing these restrictions.

But as you might have noticed, the world didn't end. There are still ad blockers, so things got figured out. And now we have manifest.v3. With the web extensions, we are talking about isolated contexts because a web extension has a popup. Many of them have popups when you click on the icon. Here is an example of Grammarly. Then it has a context content script when it injects some widget or some functionality to the web page that is open in the tab. And then it has background scripts, which are like service workers. They do not have the access to the open tab. And the contents of the background script don't live forever. They are not persisted. You might be able to trigger them through certain events such as when a message arrives or when the user changes a tab, some cookies change. The background scripts can listen to a lot of events and then when these events happen, they can do the logic and then die or go back to sleep.

However, one important thing to point out here is that these contexts are siloed. They are not living in the same place. You have different files for them. You are initiating React if you're using React in all these locations where you're using it except the background script because there you cannot. One of the biggest issues with web extensions is therefore the communication challenge because how do you tell from the popup something to the background script or something to the tab that is open? Well, there is an API for that. It's called sendMessage. And here's an example from popup to background. You can send Chrome.runtime.sendMessage with any payload. In this case, it's action getData, but it can be any object that can be passed to JSON stringify.

And the background script can listen to messages. As I told you, it's normally not live, but Chrome.runtime.onMessage.addListener is a way to listen to messages. And in our case, we are checking if the message.action is getData. And if it's getData, do something and sendResponse. SendResponse is an optional parameter. It's a callback function, but this is super useful because this way we can send message from one place to another and wait until the response came back. This works perfectly when the extension-owned scripts are targeted, such as the background script or a popup or the sidebar if you use a custom web page, a custom options page. However, when you are targeting the content script, which is living inside the contents of the open tab, this is a little bit different, nothing major, but you have to use Chrome.tabs.sendMessage.

And our first parameter is the tab ID so that you can target the specific tab. And that is fine, but what happens with React context or Redux or probe drilling? If you are thinking about these different silos, then you either need to initiate it on all of them. So how does it work? Well, this is probably one of the main challenges of web extension development. But there are a lot of other ones. One is how to configure development. And there is the hard way which I can speak from my very own experiences.

Setting up custom web pack configurations, it's a pain because you might need to have hundreds of lines of configuration. You need to create separate bundles for the popup, for the content script. The minifying is complicated. There is no hot reloading, really. You might waste hours of debugging. And also, it's quite browser-specific. So, for example, you want npm run start to open Chrome with the extension already injected. Extremely complicated to do it with web pack. It's possible, of course. You can also use rollup or other things, but you need to do a lot of custom things.

However, you will not be the only person who faces this challenge. And there is a more modern way to do it with a framework called WXT, which is Next.js for extensions, as they claim on their website. You can install it, and it's a very opinionated framework, but it comes with a lot of free, good stuff in it. So you can start creating web extensions immediately. Your 300 lines of configuration will become just 10 lines. It comes with a really fast hot module reloading because it uses VT under the hood. It supports all kinds of manifests, V2, V3, based on whether you are targeting Chrome or Firefox or Safari.

And it also comes with React support, so that's good for us since this is a React conference. However, even if you are using WXT framework, you will still face a couple of challenges, at least I have throughout the years of my web extension development journey. And in the second half of this presentation, I will go through the main ones that I think are a bit trickier, and you might not be prepared if you have not worked with web extensions before. None of them are extremely complicated, more like things to be considerate about.

So let's get started with the first one, which is state persistence. As you can see on this GIF, if you open a popup and make some changes in the state, in our case, change the background, which is using useState, and close the popup and open it again, the state will be gone. And the reason is that every time you open a popup, it basically renders it from scratch, so all the data is gone. You can create your own storage hooks. You can use Chrome's API for storage, or you can use a library called useChromeStorageLibrary.

Now, you can store data in three different ways, or four, but we will talk about three. The local storage, session storage, and event sync. These are not the same local storage, session storage as your underlying website would use. These are specific storages for the extensions, and local is obviously persistent across the browser. Session is only for the current session. Sync is if your user is logged in with their Google account to Chrome, then if they open your extension in another device where they are also logged in, the data will be there, too.

It's extremely easy to access it through Chrome or like Firefox or whatever you're building to API, but as I mentioned, there is already a library for that. In our case, it is the useChromeStorageLocal function, which uses the local storage, and you can just use it from your popup, from your injected scripts, everywhere when you're using React.

The next one is multi-tap state management, which is when you have state but not only one tap open, and here's a real-life example. For example, you're building a CRM extension, and you want to gather the emails from the tabs. Let's say you have three tabs open. The first one has a LinkedIn profile with one email. The second tab has a company website, the about page with three emails, and the third tab has a Gmail thread with eight emails in it.

Now, you can also use the storage as we did before, and that is the way to go. However, you should be considerate about the tab ID. The tab ID you can get through messaging from the background script, and you can then use the tab ID even in your content script and just store the data with some reference to the given tab. It's also very important, as I will mention later, to then clean up the data when the tab is closed and when you don't need the data anymore, because as the tabs keep growing, if the users don't close-close the browser, just keep closing the tabs, and you don't clean the data, and then it can lead to memory leaks.

It's also recommended to use session storage for this. What about Redux? Well, I don't know how many of you are still using Redux, but a lot of you probably are, and you are familiar with it. Redux is not really possible in the silo setup of web extensions. There is a plugin, a WebExt Redux library, which stores the data in the storage, but it's using some proxies and messages to, basically, every time there is, like, a Redux action, it stores it in a storage, the same way as we are sending message with data. But it's not really recommended. It works, but sometimes serialization breaks the object references. It comes with a lot of performance issues. It's pretty hard to debug. The Redux dev tools don't work so well with this library, and it's just better to use the storage. Like, if you are architecting a new web extension, just be considerate about it.

Challenge number four is something that I ran into many times because I was not considerate enough, but now I am. CSS collision. Let's say you're injecting a little widget on the Open tab. I mentioned Grammarly, for example, but you know a lot of password managers also show little widgets on the pages, and you have very nice design for it, but the underlying website has their own way of, let's say, styling a button. Sometimes, you know, they have important styles, and you can't really override those with your own custom styles. So what is the solution? Well, you can also put important to all your styles and then have a very ugly style sheet, but there is a much better solution, which is using the Shadow DOM and custom web components to wrap your React bundle.

This comes for free in the WXT framework. Here is an example how you can do that. You're basically using the CreateShadowRoot UI, and where it's rendering, you just render it inside that. This comes with an isolation, so all the styles that are outside of your component, of your web component, will not be inherited by the web component, so you're starting fresh, which is really, really useful in most cases. Sometimes, of course, you don't want that, but I think 99% of the cases, you want your styles to be isolated from the underlying web page if you're injecting into it. Challenge number five is the communication between a web page, your web app, and the extension.

Challenge number five is the communication between a web page, your web app, and the extension. Here, a real-life example is like, for example, your CRM has different cards of users, persons, and you want to open the sidebar when they click on the Open button in the web app. Now, the web app can't really use the Chrome APIs to send messages. However, it can use window.postMessage, the same way as it communicates with iframes, for example, and with window.postMessage, you can send a message that then the background script can listen to. Authentication was something that I had challenges with until I learned that Chrome extensions can actually access HTTP-only cookies as well if you have the cookies permission, and that way, you can listen to cookie changes and check whether the user is authenticated or not. This is not available in content script, but that's fine. You can listen in the background script, and in case the authentication passed, then you get the cookie and you send messages all across the extension.

Probably the most tricky thing with web extension development is dealing with memory leaks. There are just so many things where it can go wrong, mostly because you might have new tabs open. So my generic recommendation is that the cleanup isn't optional in extensions. It's absolutely critical for production stability. I ran into a lot of issues with redundant API calls. Again, the tabs kept adding data, background scripts accumulating. Maybe you have timers that you forget to stop for each tab, race conditions. And one way how you can also deal with it is probably adding throttling and debouncing much heavier than you would do in your regular web app just to ease the load on the background script.

I created a little benchmark, and I found that it doesn't matter if you're using local storage, session storage, or the sync storage. Storing data in those are almost for free, so don't worry about them. Send everything to the background script and let it handle the throttling and the debouncing for you. You can update the storage. Just don't update the server. Finally, to wrap up everything, we talked about what are extensions, the manifest.json file, I mentioned the WXT framework, which makes our lives so much easier. It comes with a lot of things out of the box. I talked about communication between the various silos, the various parts of web extensions, messages, listeners, and a lot of things to take care about, mostly race conditions and cleaning up everything after we don't need the data anymore. I'm sure you will have a lot of other interesting talks in this conference, but I would be happy to stay in touch. You can find me on LinkedIn. This is my website. And one last time, let me mention webextentiontutorial.com, which has a free YouTube course about creating web extensions. Maybe you want to learn more, then that's it for you. Thank you very much for listening. Have a very nice rest of the conference. Bye.