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.
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.
Manifest Version
Since Chrome 18, manifest_version
must always be 2
.
Icons
Specify the extension icons, three sizes required (16px, 48px, 128px). Google advises the png
format for transparency.
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.
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, checkpopup.html
in the Gist below. Note that height and width must be explicitly specified in the CSS withhtml, body { width: 300px; height: 300px; }
(for example).
Running the extension
- Place all of the files (except this
README.md
) in the same directory (folder). - Then go to chrome://extensions (if you are not using Chrome go to your browser's extensions page)
- Check developer mode
- 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
Discussion