A basic guide to Chrome extension development

This almanac article is a complete guide and reference to building browser Extensions.

For all browsers including

• Chrome
• Chromium Edge
• Firefox
• Opera
• Brave
• And all other WebKit/Blink/Chromium browsers except Safari

Background scripts

Background scripts (background.js in this case) run in the background and have access to Chrome APIs.

You can add multiple background scripts by adding their name in the scripts array.

persistent defines if the background page should constantly refresh. This is not usually necessary unless you are using APIs other than Chrome's built-in APIs.

Docs

Content Scripts

Content scripts (content.js in this case) run when the URL(s) specified is accessed. In this case, content.js will run on all URLs (specified by <all_urls>).
The only Chrome API that can be accessed is the message passing API, so if you want access to other Chrome APIs you must put this code in a background script and use the message passing API to relay the response.

It is advised to add window.onload to this script, check content.js in the Gist below.

run_at specifies when the content script will run:

• document_end means that the browser will run the script once it has reached </html>, so you are guaranteed that all elements are present in the DOM.
• document_idle means that the browser will run the script once it is idle, which is when all elements, including images, have been fully processed.
• document_start means that the browser will run the script when it reaches the start of the document, meaning that no elements exist in the DOM yet.

You can add multiple background scripts by adding their name in the scripts array.

Docs

Manifest Version

Since Chrome 18, manifest_version must always be 2.

Docs

Icons

Specify the extension icons, three sizes required (16px, 48px, 128px). Google advises the png format for transparency.

Docs

Permissions

Certain actions require special permissions. None are mandatory, but I've put tabs, history and bookmarks here as an example.
You don't need to specify any permissions unless Chrome tells you that a property is undefined when you try to access it using the Chrome API.

Docs

Browser action

What the browser does when the user interacts with the extension's UI.

• default_title is the text that appears when you hover on the extension icon in the Chrome unibar. This is usually the extension's name.
• default_popup is the little window that appears when you click on the icon. It is just a normal .html file, check popup.html in the Gist below. Note that height and width must be explicitly specified in the CSS with html, body { width: 300px; height: 300px; } (for example).

Docs

Running the extension

1. Place all of the files (except this README.md) in the same directory (folder).
2. Then go to chrome://extensions (if you are not using Chrome go to your browser's extensions page)
3. Check developer mode
4. Click load unpacked, and find and select the extension folder with your code

Docs and how to upload to Chrome Web Store

---

I hope that this article was a useful guide/reference.

CSS-Tricks article about Chrome extensions

Docs for getting started

My original Gist: