Browser extension - Setup and test

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.

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:

Quentin MénoretFollow

Engineering Manager @Prismic – Mostly writing about TypeScript / JavaScript

Photo by Ricardo Gomez Angel on Unsplash