Browser extension - Setup and test
Tags: javascript, typescript, extension
Published: 2021-01-29 15:56:35

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.

{% link https://dev.to/doctolib/run-code-tours-without-leaving-github-1dj3 %}

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:

```js
{
  "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](https://developer.chrome.com/extensions/declare_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:
```js
{
  "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:
```js
console.log('content script loaded')
```

background.js:
```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](chrome://extensions). First, activate the developer mode in the top right corner.

![Developer mode toggle](https://dev-to-uploads.s3.amazonaws.com/i/svsmt23he4h7w93c19cf.png)

The select ”Load Unpacked” on the top left.

![Load unpacked button](https://dev-to-uploads.s3.amazonaws.com/i/u9q1k4tct44k8uex5e8s.png)

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.

![Access the background page](https://dev-to-uploads.s3.amazonaws.com/i/ttgjk1lnelpyj9letco5.png)

Now every time you will edit a file and want to reload the extension, you can click the reload button:

![Extension reload button](https://dev-to-uploads.s3.amazonaws.com/i/ro9tyl82qdvlgcgktokx.png)

### Firefox

For Firefox, it’s as easy. Just go to the [about:debugging](about:debugging) page, click on “This Firefox”:

![This Firefox button](https://dev-to-uploads.s3.amazonaws.com/i/zihr4l7m45amuigf4pok.png)

Then click “Load temporary addon”:

![Load temporary addon button](https://dev-to-uploads.s3.amazonaws.com/i/qmlcnghsxp3zccpdjn6x.png)

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 inspect button](https://dev-to-uploads.s3.amazonaws.com/i/9uxohl7qwq9cumfj2ygs.png)

### 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](https://github.com/qmenoret/code-tours-github/tree/6d18419ce71ec0392f921c169225fc541ac2fbd6).

To get started faster, you can find a lot of resources with _ready to use_ repositories, such as [chrome-extension-typescript-starter](https://github.com/chibat/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:

{% user qmenoret %}

_________________

Photo by [Ricardo Gomez Angel](https://unsplash.com/@ripato?utm_source=unsplash&amp;utm_medium=referral&amp;utm_content=creditCopyText) on [Unsplash](https://unsplash.com/?utm_source=unsplash&amp;utm_medium=referral&amp;utm_content=creditCopyText)