I just published a new extension on Chrome and Firefox that allows anyone to run Code Tours from the Github UI. More information about Code Tours and the extension in this blog post.
Article No Longer Available
I thought it would be nice to write a series about how you could do exactly the same, step by step.
This second blog post will focus on how to set up the environment to develop a Browser Extension.
The manifest file
All we’ve seen in the previous post must now be bundled together to be loaded into the browser. In order to do so, you will need to have a folder (let’s call it extension
) containing the different scripts to be loaded, an icon for your extension, and a Manifest file to tell the browser what to load, and where to find it. The manifest for our extension looks like this:
{
"name": "Code tours Github",
"version": "0.0.1",
"description": "Allows to run code tours in your browser",
"manifest_version": 2,
"minimum_chrome_version": "60",
"background": {
"scripts": ["background.js"]
},
"permissions": ["https://render.githubusercontent.com/*", "https://github.com/*"],
"icons": {
"128": "code-tour.png"
},
"content_scripts": [
{
"run_at": "document_start",
"matches": ["https://github.com/*/*"],
"js": ["github.js"]
}
]
}
Let’s deep dive into the different properties.
Describing your extension
The properties name
, description
and version
are here to describe your extension. The name
will be displayed on the Chrome Web Store (or Firefox Addons store) and when you hover over the extension icon. The description
will also be displayed in the Store by default. You should be sure to name your extension properly as a poor description is a cause for rejection (we'll see more about submitting the extension in a next blog post).
The version
should only be incremented when you release a new version.
A nice logo!
The icon
property should be the path to a nice image you want to show in the extension toolbar of the browser. It will also be shown in the Store page so make sure to have a decent resolution for it (128x128 will do).
Starting your scripts
The backgrounds
and content_scripts
sections list the different scripts you want to load. Just give it a relative path to the script from the manifest file. For the Content Scripts, you also need to explicitly state in which pages it should be included via the matches
(or exclude_matches
) properties.
Permissions
Depending on the actions you want to perform from your extension, you will need to require some permissions. You should list them in your manifest file. For instance, you could require:
-
bookmarks
to be able to manage the bookmarks of the browser -
nativeMessaging
if you want to be able to start external programs - Any URL if you want too be able to query those with authentication (you can always do a simple GET without authentication, but if you want to query content where you need the cookies, you will need to declare it)
You could also dynamically require them from your background script, but I would recommend to put all the permissions that are required for your extension to work in the manifest file, so your user can’t reject them (either they accept, or won’t install the extension).
One important note: do not ask for more permissions than you need, you will have to justify all of them during the review process when you submit your extension, and this is yet another cause for rejection.
A minimal working extension
In order to demonstrate, just create a folder called extension
with 3 files in it.
manifest.json:
{
"name": "My extension",
"version": "0.0.1",
"description": "A small test!",
"manifest_version": 2,
"minimum_chrome_version": "60",
"background": {
"scripts": ["background.js"]
},
"content_scripts": [
{
"run_at": "document_start",
"matches": ["http://*/*", "https://*/*"],
"js": ["content_script.js"]
}
]
}
content_script.js:
console.log('content script loaded')
background.js:
console.log('background script loaded')
Now let’s load it in the browser!
Loading the extension
Now that we have a folder with our content scripts, background, and manifest, we can load it into our Browser.
Chrome
For chrome, just go to chrome://extensions. First, activate the developer mode in the top right corner.
The select ”Load Unpacked” on the top left.
It will prompt a file picker. Select the extension
folder (the one containing the manifest.json
file). Your extension is loaded and can be reloaded from this same page.
Note that if you have a background script associated with your extension, you will have a “Inspect views: background page” link. This opens the dev tools linked to your background script, allowing you to check the logs.
Now every time you will edit a file and want to reload the extension, you can click the reload button:
Firefox
For Firefox, it’s as easy. Just go to the about:debugging page, click on “This Firefox”:
Then click “Load temporary addon”:
In the same way as for Chrome you will be prompted for a file. Select the manifest
file (not the folder) and your extension will be loaded.
You will have access to a “Inspect button” granting you access to the devtools of the background page.
The result
In both cases, when inspecting the background script, you will see “background script loaded” appear in the console, and on every page you visit, you will see “content script loaded”, as if it was part of the website code.
Going further
In my case, I went with using TypeScript, which required me to transpile my code to generate what we described before, and use Webpack to generate the different script files. You can find the resulting code here.
To get started faster, you can find a lot of resources with ready to use repositories, such as chrome-extension-typescript-starter for TypeScript. It’s a good way to get started quickly.
Conclusion
We just deep dived into how to setup and test a browser extension. In the next post, we’ll start implementing some real features! Feel free to follow me here if you want to check the next one when it's out:
Photo by Ricardo Gomez Angel on Unsplash
Top comments (0)