How to Make Your First Chrome Extension

I’ve made a couple of Chrome extensions and talked about them here before. With the release of XKCD 1625 last week, I thought it would be a good opportunity to describe the process of creating an extension and publishing it in the Chrome Web Store. You can find the example extension created in this post on the Web Store. Commit messages in the accompanying Github repo provide additional details about each step. You can find more information on creating Chrome extensions in this article from Google.

1. Write the functionality that your extension will provide

This can be anything that’s allowed by the Chrome program policies. In the example extension, there’s a function that iterates over a series of keys used to generated regular expressions and replaces them with the more fun suggestions in the XKCD comic above.

var dictionary = {
    "debate":                               "dance-off",
    "self\\-?driving":                      "uncontrollably swerving",
    "candidate":                            "airbender",

for (key in dictionary) {
    content = content.replace(new RegExp(key, "g"), dictionary[key]);

return content;

2. Write a background file with instructions for the browser on how to execute your script

For this part you will interact with the Chrome browser’s APIs. The purpose of this file is to link browser actions to the functionality you developed in the previous step. In the example app, when the user clicks the app icon in their browser toolbar, a new tab will be opened using the current URL with the XKCD replacements applied to the document’s markup.

chrome.browserAction.onClicked.addListener(function(tab) {
  chrome.tabs.duplicate(, function(tab){
    chrome.tabs.executeScript(null, {file: "xkcdsub.js"});

3. Write a manifest file with info for the Chrome Web Store

Here’s where you put information that will help users find your extension and understand what it does.

Some notes about this file:

  • The manifest_version has to be “2” for current versions of Chrome.
  • Limit the permissions you need as much as possible (in the example app, it needs the user’s current page URL for either http or https connections, and the ability to execute a script on the user’s active tab).
  • Which script(s) to execute in the background (background.js in our case).
  • Icon images for the extension (19×19, 38×38, and 128×128-pixel varieties, the last of which can also be used for the extension’s icon in the web store).

4. Test your extension locally

You’ll want to test out your extension before uploading it, to ensure that it behaves as expected. You can load the extension from your local filesystem by navigating to chrome://extensions in the browser and clicking “Load Unpacked Extension”. There will be a dialog informing you if any errors occurred (such as an incorrect manifest version). If there are no errors, the extension will be loaded and accessible from the Chrome toolbar by clicking the icon you set up in the previous step. If you make any changes to your code locally, you’ll need to reload the extension.

5. Set up a Chrome Developer account

To publish your app in the web store you will need a Chrome Developer account and accompanying web page. Because you will have to verify that you can access the web page in order to associate it with your extension, it’s easiest to use a account if you are new to this process.

6. Publish your extension to the Chrome Web Store

Once you’re satisfied with your app’s behavior and ready to release it to the world, you can publish it to the web store. In this step you will supply additional details about your app to users and provide one or more screenshots or Youtube videos illustrating its functionality. Here’s the example extension applied to this news story:


7. … Profit!?!

It is quite rewarding to know that you can deliver code to enhance and extend the functionality of a web browser for users. Users can leave feedback on your extension in the web store, so check back occasionally to see if there are opportunities to improve it. Feel free to leave any feedback about this post or the accompanying extension here or open an issue on Github. If you use these tips to make your own Chrome extension I would love to hear about it!