Making Your First Browser Extension

So, you want to make a browser extension. Perhaps this is something you've been interested in pursuing, but didn't know how or where to get started, and taking one look at the Google Developers documentation or the Mozilla Developer Network (MDN) Web Docs made you give up on the idea.

Well, I'm here to show you that it isn't nearly as daunting a task to get started as it may initially seem.

What this post is

For starters, what this post is not is a tutorial. We won't be building an extension here; both Google and Mozilla have excellent how-to guides on building your first extension (which we will get to).

This post is to help show you the path from an idea to a browser extension that others can find and install in their browsers. We'll look at:

  • The different types of extensions there are and the UI options available to you, so you can determine how your extension will behave and how users will interact with it
  • The manifest file you will need to have your extension recognized by the browser and operating
  • The extension API that allows your code to interface with the browser
  • How to test your extension
  • Where and how to get your extension published

Where applicable, I will provide links to both Google and Mozilla's documentation. Some information will be specific to the Chrome or Firefox browser; in which case, you will want to consult the respective documentation. There is, however, a large amount of compatibility between their extension APIs and the specification published by the W3C Draft Community Group. If one group's explanation of a subject is unclear to you, it could be helpful to seek clarity in the other group's documentation on the same topic. And yes, this compatibility means you can make your extension available on Chrome and Firefox (and Opera!) without too much hassle.

You Need an idea

In coming up with an idea for a browser extension, it is obviously helpful to reflect on what a browser extension is.

Basically, as I see it, browser extensions fall into two major camps, they either:

  1. Extend the functionality of the browser itself; or
  2. Modify the way in which you consume/perceive web pages or a specific website.

MDN's What are extensions? page provides a good list of types of extensions to further categorize these camps:

  • Enhance or complement a website
  • Let users show their personality
  • Add or remove content from web pages
  • Add tools and new browsing features
  • Games
  • Add development tools

Each of those is followed by a more detailed description and a list of examples that are worth checking out if any of them sparked inspiration or interest.

The easiest way to come up with an idea is to look at problems or annoyances you have with your everyday browser experience — whether it be something with the browser itself or an issue you have with a specific site. I made my first extension because our team was annoyed with some of the UI choices made by our project management software. My extension shuffled ticket sections around (reprioritizing them for our needs), and added buttons to copy the ticket number and ticket URL to the clipboard. So, you can create an extension that simply makes little tweaks to a website or web app that you (and/or your team) use to improve your workflow.

Your user interface

Once you've got an idea, you should consider how it will "look" as a browser extension.

If you've installed browser extensions before, then you know that they "live" in your browser's toolbar as an icon (or badge). For some, the icon is only there to signal that the extension is installed and active; they're passive extensions that don't require interaction from the user. For others, clicking the icon does something. This something could be performing some action on the current webpage, opening a menu, or opening an HTML document in a popup.

Honestly, this isn't something you need to decide right away, but I think you should be aware of your options as you begin building your extension. While you're in the thick of development, you may decide to add, remove, and/or modify features that change your mind on the interface anyway.

The Manifest file

Every extension must have a manifest file. It is a JSON file (named manifest.json) that provides metadata about your extension, such as its name, description, icons, etc.

Along with the basic stuff, the manifest also informs the browser of your extension's intentions, like aspects of the UI you've chosen (e.g., browser action vs. page action), but more importantly: permissions. To access particular parts of the extension API, your manifest will need to declare the permissions it needs. This is a security measure to limit damage performed by possible malware and to know what permission warnings to display to the user upon installation.

The only required keys in the manifest are: "manifest_version", "name", and "version". That's all you need to get started; anything else can be added as is needed by your code.


In addition to the manifest file, browser extensions are just HTML, CSS, and JavaScript. If you're familiar with these, then you're good to go! If not, don't fret; you have the knowledge of the internet at your disposal. I didn't know how to write JavaScript when I made that first extension I mentioned earlier, but by Googling the right questions, I was able to hack together something that made our project management software easier to use.

You'll need HTML and CSS if you want your extension to have a UI beyond the toolbar icon (such as a popup window). JavaScript handles not just any behavior needed for your HTML/CSS, but it's what's used to interact with the extension APIs. As touched upon earlier, there is a great deal of compatibility between the extension APIs, allowing you to develop your extension for multiple browsers with relative ease.

Testing & Debugging

No doubt you will want to test your extension during development. Basic knowledge of Chrome DevTools and/or Firefox Developer Tools will prove useful, but there are some extension-specific debugging tools and tips also worth knowing:


Woohoo! Your extension is ready to roll, and you wanna share it with the world! ...Or just your team. ...Maybe just your friends. It's up to you!

Chrome extensions will be published to the Chrome Web Store, and Firefox extensions will be published to Firefox Add-ons.

You will see that, for both Chrome and Firefox, you will need to create a developer account (if you haven't already done so) in order to publish to their respective platforms.

Note: For Chrome, there is a one-time $5 developer signup fee. This "is intended to create better safeguards against fraudulent extensions in the gallery and limit the activity of malicious developer accounts." (Source)

Getting started

Alright, that was the whirlwind tour of creating a browser extension. I hope this breakdown gives you a better idea of where to begin with making an extension of your own. Here's a quick recap of the basic process:

  1. Ideation – Identify a problem to be solved, and conceive a solution for alleviating it.
  2. UI – Get some sense of how you want users (even if it's just you) to interact with the extension.
  3. Manifest File – Create your manifest.json file; the UI phase will guide some of the configurations here.
  4. Development – Coding your HTML, CSS, and JavaScript; interfacing with the extension API.
  5. Testing & Debugging – Ya know... the trial and error part... lots of console.log...
  6. Publishing – Register a developer account, and publish your creation to the Chrome Web Store and/or Firefox Add-ons.

See?! Not so bad. Again, this post was a way of introducing you to browser extensions with a bit more ease than giving you a face-full of this.

So, what now? My advice: tutorials. Once you've got a sense of what you're dealing with — which I really hope you have now — I think the best place to start is Google and Mozilla's own tutorials. Now that we've gotten the overhead out of the way, you should be able to focus on working your way through one or more of those and using them as a jumping-off point for your own.

Once you've created an extension from the tutorials (and hopefully added some experimental tweaks of your own), I'd say look through their sample extensions (of which they have many). This will give you a much greater sense of what is possible with browser extensions, and some insight on how they ought to be architected.

Finally, here are a few interesting pages that I've found in my journeys through Google and Mozilla's documentation. Perhaps, you'll find them interesting too. In no particular order (though, I do especially recommend trying out the Extension Scaffolding Builder):