top of page
Writer's pictureJeB

Chrome Extension with Angular — from Zero to a Little Hero

Updated: Jul 3, 2022

or a short how-to and why-in-the-world



Hey folks.


Today we’re going to explore the process of developing a Chrome extension with Angular.

If you're looking for the older version of the article (covering Manifest V2) you can find it on Medium.


If you’re not feeling like reading and going through the code you can watch my talk on this topic instead (note that the talk only covers Manifest V2):



We will be starting from scratch with ng new and finishing with a fully functional Chrome Extension, convenient dev environment and hopefully a decent understanding of how it works.


But first let’s clear out one thing…



Why would one want to develop a Chrome extension

There are couple of reasons that would make you want to develop a Chrome extension. First (and the most improbable one) is to make money. Yes, there are Chrome extensions that are published in Chrome Store and developers get paid for it. And if you have an idea for an extension and a business model that will be profitable — well, who am I to tell you not to go for it.

However, I believe that the main use case for developing an extension is to serve your needs as a developer.

For example at my company we have a handful of Chrome extensions that were developed by developers for developers and BOY, how much time did it save me!


I’m sure that you can think of at least one thing that you are doing repeatedly over and over during the development cycle, a thing that can be easily automated with a simple Chrome extension.


Today you’re going to learn how to build one and in order to have even more fun we’re going to do that with Angular.


What a Chrome extension consists of

Background script (service worker)

The extension service worker is the extension's event handler; it contains listeners for browser events that are important to the extension. It lies dormant until an event is fired then performs the instructed logic; it is only loaded when it is needed and unloaded when it goes idle. The service worker has access to all the Chrome APIs, as long it declares the required permissions in the manifest.json.

Content script

Content scripts are files that run in the context of web pages. By using the standard Document Object Model (DOM), they are able to read details of the web pages the browser visits, make changes to them, and pass information to their parent extension.

We’re not going to touch these in this tutorial (well, almost)


Popup

An action's popup will be shown when the user clicks on the extension's action button in the toolbar. The popup can contain any HTML contents you like, and will be automatically sized to fit its contents. The popup cannot be smaller than 25x25 and cannot be larger than 800x600.

Spoiler: this is where we use Angular


Communication between pages

Different components in an extension can communicate with each other using message passing. Either side can listen for messages sent from the other end, and respond on the same channel.

In this tutorial we’re going to focus on popup and background page but there are much more options than you can use, make sure to check them out.


So…



As I mentioned we’re going to start from scratch with ng new. Obviously we need Angular CLI for that, so if for some weird reason you don’t have it installed yet, please do:

npm i -g @angular/cli

Creating a project

  1. Start with creating a new project: ng new angular-chrome-extension

  2. cd angular-chrome-extension

  3. Create a manifest in the /src/ folder

Extensions start with their manifest. Create a file called manifest.json and include the following code, or download the file here.

Loading the extension into Chrome

We’re going to load the unpacked extension from the dist directory so we need the manifest to be there as well.

Let’s include it in assets (angular.json):

Run ng build to make sure manifest.json is indeed present in dist directory.


Time to load it into Chrome and watch it working:

  • Open Chrome.

  • Open the Extensions Management page by navigating to chrome://extensions.

  • Enable Developer Mode by toggling the switch next to Developer Mode.

  • Click the Load unpacked button and select the extension directory (dist/angular-chrome-extension).


  • Now you should be able to see the extension in Chrome:


However, as you’ve probably noticed, there is nothing in the extension apart from the default icon and the title we gave it in manifest.json.


The reason is that we didn’t define any action. Let’s define one:

The Action API controls the extension's action (toolbar icon). It can either open a popup or trigger some functionality when it's clicked.


Now let’s run ng build again and reload our extension:

Click on your extension and... Voila!

It works with Angular, yay!


However, if you look at the extensions page you may notice that there are some errors:

And if you click on the "Errors" button you'll see the details:

What does it mean?

In index.html that is generated by Angular CLI in dist folder you can find the following line of code: <link rel="stylesheet" href="styles.css" media="print" onload="this.media='all'"> As the error message suggests, the default security policy disallows execution of inline scripts, and event handlers considered as such. Therefore the solution would be to remove the onload event handler.

Removing it manually wouldn't help, since it's generated upon every build, however, you can disable it in angular.json by changing the optimization settings. Add the following to your angular.json:

This will disable the inlining of critical styles but since we're not fetching the files from a remote server but rather have everything packed inside the extension we don't need this optimization anyways.


Build, reload - error gone.


ANGULAR IN CHROME EXTENSION — CHECK

Live reload and ng serve

Ideally we would want to use ng serve just like we use it for web applications and expect the extension to be updated automatically every time there was a change. Unfortunately that’s not the case.


We can’t use ng serve here because it writes the bundle into the memory of the dev server, while Chrome needs an actual physical folder on disk in order to load the extension.


We can use ng build --watch though.


This command watches the sources (and assets) and rebuilds the relevant files while updating the bundles in dist directory. It will take care of updating the dist folder when one of the sources or the manifest changes.

The extension is still not updated automatically but using ng build --watch does make your life easier:

  1. If you’ve changed any source file that affects extension popup, re-open the popup. Chrome loads the popup directly from dist folder every time you open it so any changes to the popup are applied automatically when it is re-opened.

  2. If you’ve changed the manifest you have to reload the extension on the extensions page (just like we did before). Manifest is a set of definitions, rules and instructions for your extension so it is applied when the extension is installed. By pressing the reload button you’re effectively reinstalling the unpacked extension.

  3. Background scripts can be reloaded automatically, but we’ll cover it later.

Make the extension do stuff

At the moment we have an extension that shows the default Angular app page as a popup and other than that does absolutely nothing. Let’s change it.

First we’ll define what this extension will do:

  1. It will be active on all sites the sites except for google.com domain

  2. It will contain a color picker

  3. It will change the background color of a page to the selected color upon pressing a button

Disable extension for certain sites


The Service Worker

To remind you:

The extension service worker is the extension's event handler; it contains listeners for browser events that are important to the extension. It lies dormant until an event is fired then performs the instructed logic; it is only loaded when it is needed and unloaded when it goes idle.

In our case we would like to listen to web navigation completed event, do the URL matching and disable the extension if there is a match.

  1. Install the types for Chrome API: yarn add -D @types/chrome

  2. Add chrome to types array in tsconfig.app.json

  3. Create a file called background.ts in the src/ folder:

Chrome APIs are mostly asynchronous so this is what happens here:

  1. We add a listener that once the extension is installed will…

  2. …add a listener that once a user goes to any URL that contains google.com will…

  3. …query the open tabs to pick an active one and once there is an answer will…

  4. …activate the page action on this tab

Now let’s run ng build.


Did it compile the service worker? Obviously it did not. The file exists but it is not referenced from anywhere and there is no way for Angular CLI to actually know that this script is part of the build.


We need to integrate the service worker into the build process.

Compiling service worker as part of Angular build

Since the service workers run in a context different than the extension’s popup we cannot just add it to the scripts section in angular.json. Anything that’s in scripts section is compiled by Angular CLI into scripts chunk and loaded by index.html (a popup context in our case). This is also the reason we can’t just import the background script in main.ts or any other file that is compiled as part of popup build.


What we can do is create another entry for background script in Webpack build that Angular CLI runs behind the scenes. For that purpose we’ll use Custom Webpack Builder:

  • Install it: yarn add -D @angular-builders/custom-webpack

  • Update angular.json:

  • In the root of your workspace create a file called custom-webpack.config.ts with the following content:

  • Add src/background.ts to files array in tsconfig.app.json.

  • Run ng build.

You should see it in the output now (and also in dist/ directory):


Notice that the file names contain hash, which enables better cache busting for web apps. In our case it is irrelevant, moreover, it might complicate our build setup, since we need to specify background and content scripts in manifest.json and it is much easier to do when the names are constant.


Let’s disable this option in angular.json:

Running ng build now should result in following:


Now we need to make Chrome aware of this background script. We also need to grant some permissions to our extension. Update your manifest.json:

If you build & reload the extension now and go to http://google.com you’ll see it’s still active. If you dig a bit into it you’ll see that the background script is being loaded but it is not being executed. And there is a reason for that.


Let’s take a look at the compiled version of our background.ts:

As you can see our code is being pushed into webpack chunks array but no one invokes it. So yes, the script is being loaded but nothing happens, because no one actually runs the code. Angular CLI (Webpack) puts the code that is responsible for chunks execution in a separate chunk called runtime. Since this code split doesn't give us much in terms of performance (remember, we have all the files available locally), we can just disable this behavior for background.ts entry:

Run the build again and notice the change in background.js:

As you can see the code is executed right away, the moment it's loaded, no Webpack runtime whatsoever.


Reload the extension, go to http://google.com and see that the extension is disabled for this site.


ACTIVE ON ALL SITES EXCEPT GOOGLE DOMAIN — CHECK


Background page live reload? Who said live reload?

Note: at the moment live reload is not supported for Manifest v3, there is an open issue about it and you're welcome to jump in and vote up (or even make a PR).


Until it is supported you should skip to Adding Color Picker.


Currently the background script behaves much like the manifest — it is reloaded only when you reload the extension. However, unlike the manifest (that is updated rarely after the initial phase of development) it contains significant part of our code and is updated quite often during the development. And believe me, it is very annoying to go to Extensions page and press Reload button every time you change a name of a variable in the background script.


So what can be done here? Since we’ve already incorporated Custom Webpack Builder in our build chain we can benefit from it a bit more.


There is a webpack-ext-reloader plugin that does exactly what we want. It augments background script code with code that listens to the changes of the chunks and when there was a change in the background chunk it tells Chrome to reload the extension.


We want this augmentation only during development so let’s create another webpack config that will make use of our initial configuration and add webpack-ext-reloder plugin on top of it:

  • Install extension reloader plugin: yarn add -D webpack-ext-reloader

  • Create a file named custom-webpack-dev.config.ts in the root of your workspace:

Refer to the plugin’s README for detailed API description

  • Add this config to your development configuration in angular.json:

Let’s make sure it works:

  1. Run the build with this config: yarn build --configuration=development

  2. Reload the extension (the old background script still lacks the live reload code, so you have to do it one last time)

  3. Navigate to http://google.com

  4. See the action disabled

  5. Go to background.ts and change the URL match pattern to blahblah

  6. Navigate to http://google.com

  7. See page action enabled


Side note: we could have written the background script in JavaScript instead of TypeScript and add it to the assets just like we did with manifest.json but it is not recommended as it diversifies your code. You also loose the live reload ability which is a dealbreaker for me.


Side note 2: everything that we’ve done here for background script (including building it with ng build , live reload etc.) is applicable to content script as well.


Adding color picker

This will be an easy one. We will use ngx-color-picker component.

  • Install ngx-color-picker: yarn add ngx-color-picker

  • Add ColorPickerModule to imports in app.module.ts:

  • Add color property to app.component.ts:

  • Replace default Angular content with color picker in app.component.html:

Refer to the color picker README for detailed API description

  • If you don’t want the white frame around the color picker remove the margins from body in styles.scss:

  • Open the popup and behold:


ADD COLOR PICKER — CHECK


But currently it doesn’t do anything. Which brings us to the next (and the last) milestone.


Change the background color of a page

Now that we have all the tools in place we want to actually apply the picked color to the site background.


Let’s do that:

  • Add colorize method to app.component.ts:

  • Bind the method to colorPickerSelect event (called upon Apply button pressed):

  • Open the popup, select a color and press Apply. Gee, did it actually work?!

Bonus: saving the last selected color

To make things neater we’d want to save the last selected color and select it next time we open the popup.


For this we’ll need a few things:

  • Add storage permission to the manifest and reload the extension:

  • Add updateColor method to app.component.ts and bind it to colorPickerChange event:

  • Set initial color from the storage once the popup is created:

  • Optional: set a default color in background script:

Now the extension will remember the last selected color and select it when you open the popup.


If something goes wrong

Errors are an integral part of the development process, therefore it’s important to know how to tackle them. If something goes wrong and your extension is not loading properly you can see the errors in two ways:

  • Errors button on your extension configuration page:

  • Right click on the popup and Inspect Popup:


If you want to debug your service worker then you can inspect it from here:


Finishing words

While most of the extensions do not have a complicated UI, there are some of them, such as Checker Plus or 1PasswordX, that have quite complicated one. These extensions would be easier to build and maintain using one of the popular web frameworks, among them Angular.


I hope this article gives you all the necessary tools and understanding for developing a Chrome Extension with Angular in convenient and efficient way.


All the sources are available on Github.

Follow me if you liked the article, comment/send a message here or DM on Twitter if you have any questions.

29,018 views18 comments

Recent Posts

See All

18 Comments


Gérard Menvussa
Gérard Menvussa
Dec 23, 2023

Awesome tutorial, thanks a lot !

Like

Hi Jeb, This is an awesome article. I faced some problems which I have mentioned below: After adding the "runtime: false" in custom-webpack.config.ts. The extension is still working on google.com and I'm getting the following error in my extension: Error handling response: TypeError: Cannot read properties of undefined (reading 'id') at chrome-extension://momimlfkfdgbdcpmglhnboplilofbmcl/background.js:1:167

Context UnknownStack Trace 0 (anonymous function) Also, I am using Angular 15 to build my chrome extension and wanted my extension me be like a floating widget like Speechify ( https://chrome.google.com/webstore/detail/speechify-text-to-speech/ljflmlehinmoeknoonhibbjpldiijjmm?hl=en-US ) and to open at the bottom left of the tab body. Any help or suggestions regarding it would be really appreciated.

Like

ProGamer 119
ProGamer 119
Jan 24, 2023

Hey Jeb, great article. After stumbling a lot I finally have clarity on how to create an extension with angular. I however have a doubt, how are people able to create UIs other than the solid square provided in popup.html (e.g - https://chrome.google.com/webstore/detail/gimme-summary-get-summary/mpjcikcpmljllcobpboakgocbenkhokc) I suspect that they are somehow injecting the component directly in website's html but not sure how to achieve that with angular. Any help would be greatly appreciated.

Like
JeB
JeB
Jan 30, 2023
Replying to

You are right indeed, the extension's HTML is injected into the body of site's HTML.


This is a so called content script: https://developer.chrome.com/docs/extensions/mv3/content_scripts/ There shouldn't anything difficult about adding Angular to your content script, it's been discussed here: https://github.com/just-jeb/angular-chrome-extension/issues/1

Like

Tamar Yankelevich
Tamar Yankelevich
Sep 20, 2022

Thank you Jeb. This was a fantastic article.

As explained in your article, I need to create an angular app, then add the chrome extension files (manifest, BG page, etc.)


In my case, I would like to do the opposite,


My chrome extension has popup.js & html files, which I want to replace with a small angular/react application.


Would you have any idea how to add a small angular app to an existing chrome extension?

Like
JeB
JeB
Sep 20, 2022
Replying to

Got it. In that case I would say that the easiest/simplest way to go is to follow the tutorial (or fork the example repo) and then add your manifest/background/content script code to an existing Angular app. You can, of course, try and go the other way around and start adding Angular project within your existing extension project but I would not recommend you go down this path. There is a lot of things that could go wrong there, starting with manual addition of angular workspace files and finishing with isoteric build issues 😅. In case you go with the tutorial at least I'll be able to help you if something goes sideways.

Like

Sergey Fayman
Sergey Fayman
Aug 27, 2022

Thank you for this great tutorial! Everything works well.


One small things, filtering onCompleted events catches also iframes html tags, so if a page has a google recaptcha iframe then extension will be disabled for this page too.


For example:

<iframe src="https://www.google.com/recaptcha/api2/aframe" width="0" height="0" style="display: none;"></iframe>

Like
JeB
JeB
Sep 20, 2022
Replying to

Good point, thanks for sharing!

Like
bottom of page