Browser extensions - Hooking into installs


Hooking into the install actions for browser extensions

23 Aug, 2022 · 3 min read

In some cases, you might want to hook into the install script of your extensions, for instance, when you want to onboard the users with some extra information.

In other cases, you might want to catch updates so that you can redirect users to the latest changelog.

And you can even use this install runtime to set a uninstall URL. This URL will be called whenever the user removes your extension.

Catching onInstall actions in browser extensions

If you would like to code along with this article, take the following GitHub branch as your starting point.

This project already has the main setup and uses a background worker, which we’ll need.

Note: Read the following article for more information about the background worker.

Now open up the public/background.js file and add the following script.

chrome.runtime.onInstalled.addListener((details) => {
  // Do something

This registers as soon as your extension is installed. We can leverage the details, which is a OnInstalledReason type.

The reasons can be:

  • install
  • update
  • chrome_update
  • shared_module_update

Let’s see how we can use that for catching the install and update actions. We’ll add some browser notifications in those cases, as we already have access to those.

chrome.runtime.onInstalled.addListener((details) => {
  if (details.reason === 'install') {
      type: 'basic',
      iconUrl: 'icons/icon-48.png',
      title: 'Hi there 👋',
      message: 'Welcome to the best extensions you ever installed',
      buttons: [{ title: 'Thanks 😅️' }],
      priority: 0,

  if (details.reason === 'update') {
      type: 'basic',
      iconUrl: 'icons/icon-48.png',
      title: 'Thank you',
      message: 'For updating this extensions',
      buttons: [{ title: 'Cool' }],
      priority: 0,

Another cool thing we can do is to set the uninstall URL. This is the URL that the user will be redirected to when they uninstall the extension. It can be helpful to ask them questions about why they are leaving, for instance.

chrome.runtime.onInstalled.addListener(details => {

Note: You can also safely add that code inside your install reason, but this is safer if your extension was previously deployed without it.

And now, when users remove the extension, they are redirected to this link.

You can view the complete code in this GitHub branch.

Thank you for reading, and let’s connect!

Thank you for reading my blog. Feel free to subscribe to my email newsletter and connect on Facebook or Twitter

Spread the knowledge with fellow developers on Twitter
Tweet this tip
Powered by Webmentions - Learn more

Read next 📖

Browser extensions - recap and status

1 Sep, 2022 · 2 min read

Browser extensions - recap and status

Browser extensions - DevTools extension

31 Aug, 2022 · 2 min read

Browser extensions -  DevTools extension

Join 2099 devs and subscribe to my newsletter