Chrome Extensions - Manifest File

Recently, I have been learning and playing around with creating browser extensions with Google Chrome. For those not familiar, a browser extension is a small program that extends the functionality of the browser. This can add additional functionality or behavior to the browser based on an individuals needs or preferences. Using the Chrome Web Store, developers can write their own extensions and upload them for use by anyone who wants to download and use. Creating an extension for Chrome is pretty simple, anyone with knowledge of HTML, CSS, and JavaScript can do so.

In this post, I would like to talk about and walk through some of the details of the Manifest File. This is the file that all Chrome extensions start with and provides important information that the extension needs to work properly.

What is a Manifest File

The Manifest file is in a way, the blueprint for your extension. In many ways it is similar to the package.json file that you may be familiar with in JavaScript that provides a list of all of your dependencies. This file is JSON format and includes all of the important information that your extension will need. In fact, every extension must have one of these files.

The are many different fields within the manifest and we will be talking about a few of them shortly. There are a a few that are required, many that are recommended, and a whole load that are optional depending on what you want your extension to do. Let's take a look at what an example Manifest File would look like from the Chrome docs.

// manifest.json

{
    "name": "Getting Started Example",
    "version": "1.0",
    "description": "Build an Extension!",
    "manifest_version": 2
  }

Required Fields

There are three fields that are required for every Manifest file: manifest_version, name, and version. These are relatively simple and straightforward, but lets take a look at what each one is used for.

manifest_version

This field's value is an integer that specifies the version of the manifest file format required by your project. As of Chrome 18, you should specify a value of 2. While version 1 should be consider depreciated, version 2 is not yet required. However, Chrome has stated that they will stop supporting depreciated manifest versions soon. You can check out the differences in file format versions here if you're curious.

name

This one is easy - name is just a string value that serves as the primary identifier of the extension. It has a maximum character limit of 45 and is displayed in the install dialog, extension management UI, and Chrome Web Store.

There is also an optional short_name field that is a shortened version of the extension's name. It has a max character count of 12 and is used in places where there is not enough space for the full name. If this isn't specified, a likely truncated value of name will be used.

version

This field's value is self explanatory, it is the version of the extension itself. The value consists of one to four dot separated integers and have a few rules: they much be between 0 and 65535, inclusive, and non-zero integers can't start with 0. If the published extension has a newer version string than the installed extension, it will automatically be updated to the newest version.

There is another optional field similar to short_name called version_name. It can be set to a descriptive string and will be used for display purposes. An example would be "version_name": "1.0 beta". If this field is not present, version will be used for display purposes as well.

Recommended Fields

There are also three fields in the Manifest documentation that are listed as "recommended" fields. These are default_locale, description, and icons. While Chrome will not stop you from leaving these three fields out of your file, in almost all situations you will want to include them.

default_locale

This field is used for internalization within your extension. This concept is a bit outside of this post, but if you are curious to learn more, check out Google's overview here.

Essentially, this field is used to support multiple different languages or locales within your extension. Inside of a _locales directory, you are able to include a messages.json for each language your extension will support. The extension will then be able to pick the proper messages to display to the user based on locale. This field allows you to specify which locales are supported in your extension.

Note that this field becomes required if your extension contains a _locales directory and must be absent if it does not.

description

The value of this field should be a plain text string. It has a limit of 132 characters and as I'm sure you can guess, serves as a description for the extension. It is used in both the browser's extension management UI and the extension's page in the Chrome Web Store.

icons

This field specifies (you guessed it) icons that represent the extension. The value should be formatted as an object with key value pairs of icon size and file name respectively.

Per the docs, you should always provide a 128x128 icon as it is used during the installation of the extension and by the Chrome Web Store. You should also provide a 48X48 icon which will be used in the extension management page. Optionally, you can also provide a 16X16 icon to be used as a favicon. Note that you can provide any size icons you wish and Chrome will do its best, but it is recommended to use the stated sizes for the best results.

Icons should also generally be in PNG format, but Chrome will accept any format supported by WebKit. Below is an example of what the icons field should look like:

"icons": { "16": "icon16.png",
           "48": "icon48.png",
          "128": "icon128.png" }

Pick one (or none)

There are two other fields that are technically optional, but will almost always be used. However, you may only use one per extension and which one you use will depend on the intended functionality of what you are building. The two fields are browser_action and page_action.

browser_action

This field should be used when the functionality of your extension makes sense on most web pages. Think of this action as the go to for extensions that you generally want to be available at the browser level or on most web pages a user interacts with. Say you want to create an extension that will translate highlighted words on a webpage, that would be a prime candidate for a browser_action.

This field will put an icon in the main toolbar, to the right of the address bar. The value should be provided as an object which can contain the fields default_icon, default_title, and default_popup.

default_icon

The default_icon field is used to specify an icon to be displayed on the main toolbar. For best results it is recommended to use a 16 device independent pixel size icon. In order to display icons where screen pixel density is different than one, you can provide multiple sizes and Chrome will select the best fit.

default_title

This field is used to set a tooltip to be displayed for your extension. This field is pretty simple and the value should be a string.

default_popup

If this field is specified, a popup will appear when the user clicks on the toolbar icon. The value of this field should be the file name/ path of the HTML file that you wish to use for the popup. The popup can contain any HTML that you would like it to and is automatically sized to fit the contents of the file.

browser_action Example

If the above seems a bit confusing in text, take a look below at an example implementation of the browser_action field from the Chrome docs.

{
  "name": "My extension",
  ...
  "browser_action": {
    "default_icon": {
      "16": "images/icon16.png",
      "24": "images/icon24.png",
      "32": "images/icon32.png"
    },
    "default_title": "Google Mail",
    "default_popup": "popup.html"
  },
  ...
}

page_action

The page_action field is the counterpart to browser_action. It should be used for extensions where the functionality makes sense for only a few specific pages. This field will also create an icon to the right of the address bar and can make use of the same fields as browser_action. The main difference with this field is that the icon can be grayed out on pages where the extension cannot be used. This can be toggled by using the pageAction.show and pageAction.hide methods.

Optional Fields

The Manifest file can accept a large number of optional fields, and largely including these will be based on the individual functionality and needs of your extension. There are certainly way too many to include in a single blog post, but you should check out the Manifest File documentation here if you're curious to learn more.

Conclusion

I hope this breakdown of the Manifest file used in Chrome extensions has helped you understand it's use a bit better. Happy Coding!