How to create your first Chrome extension

How to create your first Chrome extension:


Chrome extensions are programs that enhance the functions of the browser in some way. You probably already use an extension or two, maybe a password manager or some privacy addons. Have you ever wanted to create your own extensions but wondered how difficult the process would be? With the help of this tutorial, you will get a first-hand experience of just how easy it can be.

This article will walk you through the process of creating your first Chrome extension. We’ll build an extension that replaces the new tab page in the browser with a random photo from Unsplash. It’s a miniature version of my Stellar Photosextension which I built a few years ago when I first learned to build Chrome extensions. 

I’ve also included some tips for debugging Chrome extensions as well as links to resources where you can learn how to submit your extension to the Chrome web store. This will come in handy later on when you’re making your own extensions. The complete code for this demo project can be found here.


You need to have a basic knowledge of HTML, CSS, JavaScript and the command-line to follow through with this tutorial. You also need the latest version of Chrome installed on your computer. I tested the code used for this project on Chrome 85 but it should keep working on any later version.

Grab the starter files

The starter files for this tutorial are on GitHub. The repository includes all the markup and styles for the extension we’ll be building. You can run the command below in your terminal to clone the repository to your filesystem or download the zip file and extract it on your computer.

Once the repository has been downloaded, cd into it in your terminal and use the tree command (if you have it installed on your computer) to inspect the directory structure.

$ cd freshtab-starter-files
$ tree
├── css
│   └── styles.css
├── demo.jpg
├── icons
│   ├── 128.png
│   ├── 16.png
│   ├── 32.png
│   ├── 48.png
│   └── 64.png
├── index.html
├── js
│   ├── background.js
│   ├── index.js
│   └── popup.js
├── manifest.json
├── popup.html

If you don’t have the tree command, you can navigate to the directory in your file manager and inspect its contents that way.

Anatomy of a Chrome extension

Chrome extensions are composed of different files depending on the nature of the extension. Usually, you’ll see a manifest file, some icons, and several HTML, CSS, and JavaScript files which compose the different interfaces of the extension. Let’s take a quick look at the files contained in the project directory to see what they all do.

The manifest

This file (manifest.json) defines the structure of the extension, the permissions it needs, and other details such as name, icons, description, supported browser versions, e.t.c.

Background scripts

Background scripts are those that run in the background, listening for events and reacting to messages sent from other scripts that make up the extension. These scripts are defined in the manifest file. Our project has just one background script: the aptly named background.js file in the js folder.

Popup window

A popup is the small window displayed when a user clicks the toolbar icon in the browser interface. It is an HTML file that can include other resources such as stylesheets and scripts, but inline scripts are not allowed.

To use a popup in your extension, you need to define it in the manifest first. The popup file for this extension is popup.html which links to the popup.js in the jsfolder.

Override pages

Extensions can override browser pages such as the new tab page, history or bookmarks but only one at a time. All you need to do is specify an HTML file in the manifest and the page to be replaced (newtabbookmarks, or history). In this case, the index.html file will override the new tab page.

Extension icons

It’s necessary to include at least one icon in the extension manifest to represent it otherwise a generic one will be used instead. The icons for our extension are in the icons directory.

Content scripts

Content scripts are those that will be executed in web pages loaded in your browser. They have full access to the DOM and can communicate with other parts of the extension through the messaging API. We don’t need a content script for this particular project, but extensions that need to modify the DOM of other web pages do.

Update the manifest file

Let’s start building the Chrome extension by defining the required fields in the manifest.json file. Open up this file in your text editor and update it with the following code:

"manifest_version": 2,
"name": "freshtab",
"version": "1.0.0",
"description": "Experience a beautiful photo from Unsplash every time you open a new tab.",
"icons": {
"16": "icons/16.png",
"32": "icons/32.png",
"48": "icons/48.png",
"64": "icons/64.png",
"128": "icons/128.png"
"chrome_url_overrides": {
"newtab": "index.html"
"browser_action": {
"default_popup": "popup.html"
"permissions": ["storage", "unlimitedStorage"],
"background": {
"scripts": ["js/background.js"],
"persistent": false
"minimum_chrome_version": "60"

Here’s a breakdown of each field in the manifest file:

Required fields

  • manifest_version: this key specifies the version of the manifest.json used by this extension. Currently, this must always be 2.
  • name: the extension name.
  • version: the extension version.

Optional but recommended fields

  • description: the extension description.
  • icons: this specifies icons for your extension in different sizes.


  • chrome_url_overrides: used to provide a custom replacement for browser pages. In this case,the new tab page is being replaced with the index.htmlfile.
  • browser_action: used to define settings for the button that the extension adds to the browser toolbar, including a popup file if any.
  • permissions: used to define the permissions required by the extension. We need the storage permission to access the Chrome storage API, and unlimitedStorage to get an unlimited quota for storing client side data (instead of the default 5MB).
  • background: used to register background scripts. Setting the persistent key to false keeps the script from being retained in memory when not in use.
  • minimum_chrome_version: The minimum version required by your extension. Users on Chrome versions earlier than the specified one will be unable to install the extension.

Load the extension in Chrome

Open up your Chrome browser and enter chrome://extensions in the address bar. Ensure Developer mode is enabled, then click the Load unpacked button and select the extension directory. Once the extension is loaded, it will appear in the first position on the page.

At this point, the browser’s new tab page will be replaced by the one defined in our extension manifest (index.html). Try it out by opening a new tab. You should see a blank page as shown in the screenshot below:

Get your Unsplash access key

Before you can use the Unsplash API, you need to create a free
account on their website first. Follow the instructions on this
 to do so, and register a new application.
Once your app is created, take note of the access key string in the application settings page.

Fetch the background image

The first step is to fetch a random image from Unsplash. An API endpoint exists for this purpose:

This endpoint accepts a number of query parameters for the purpose of narrowing the pool of photos from which a random one will be chosen. For example, we can use the orientation parameter to limit the results to landscape images only.

Let’s use the fetch API to retrieve a single random photo from Unsplash. Add the following code to your js/background.js file:

// Replace  with the Access Key retrieved
// in the previous step.

function validateResponse(response) {
  if (!response.ok) {
    throw Error(response.statusText);

  return response;

async function getRandomPhoto() {
  const endpoint = '';

  // Creates a new Headers object.
  const headers = new Headers();
  // Set the HTTP Authorization header
  headers.append('Authorization', `Client-ID ${UNSPLASH_ACCESS_KEY}`);

  let response = await fetch(endpoint, { headers });
  const json = await validateResponse(response).json();

  return json;

async function nextImage() {
  try {
    const image = await getRandomPhoto();
  } catch (err) {

// Execute the `nextImage` function when the extension is installed

The /photos/random endpoint requires authentication via
the HTTP Authorization header. This is done by setting the Authorization header to Client-ID ACCESS_KEY where ACCESS_KEY is your application’s Access Key. Without this header, the request will result in a 401 Unauthorized response.

Once this request is made and a response is received, the validateResponse()function is executed to check if the response has a status code of 200 OK. If so, the response is read as JSON, and automatically wraps it in a resolved promise. Otherwise, an error is thrown and getRandomPhoto() photo rejects with an error.

You can try this out by reloading the extension on the chrome://extensions page after saving the file, then click the background page link to inspect the console for the script.

Note: Make sure you always reload the extension after making a change to the background.js file so that the new changes are effected.

You should see the JSON object received from Unsplash in the console. This object contains a lot of info about the image including its width and height, number of downloads, photographer information, download links, e.t.c.

We need to save this object in the Chrome storage and use it to set the background image whenever a new tab is opened. Let’s tackle that in the next step.

Save the image object locally

We cannot set the background image on our new tab pages directly from the background.js, but we need a way to access the Unsplash object from the new tab pages.

One way to share data between a background script and the other scripts that make up the extension is to save the data to a location which is accessible to all the scripts in the extension. We can use the browser localStorage API or which is specific to Chrome extensions. We’ll opt for the latter in this tutorial.

Modify the nextImage() function in your background.js file as shown below:

async function nextImage() {
  try {
    const image = await getRandomPhoto();
    // Save the `image` object to chrome's local storage area
    // under the `nextImage` key{ nextImage: image });
  } catch (err) {

To store data for your extension, you can use either or The former should be used if you want the data to be synced any Chrome browser that the user is logged into, provided the user has sync enabled. We don’t need to sync the data here so the latter option is more appropriate here.

Set the background image on each new tab page

Now that the Unsplash object is being saved to the extension’s local storage, we can access it from the new tab page. Update your js/index.js file as shown below:

function setImage(image) {
    `background-image: url(${image.urls.full});`

document.addEventListener('DOMContentLoaded', () => {
  // Retrieve the next image object'nextImage', data => {
    if (data.nextImage) {

Once the DOM is loaded and parsed, the data stored in the nextImage key is retrieved from the Chrome’s local storage compartment for extensions. If this data exists, the setImage() function is executed with the nextImage object as it’s sole argument. This function sets the background-image style on the element to the URL in the image.urls.full property.

At this point, opening a new tab will load a background image on the screen but the image loads slowly at first because it is being fetch freshly from the server when the tab is opened. This problem can be solved by saving the image data itself to the local storage instead of a link to the image. This will cause the background image to load instantly when a new tab is opened, because it will
be fetched from the local storage not the Unsplash servers. To save image data to local storage, we need to encode it to
Base64 format. For example, here’s the Base64 encoding of this image:

Encoding an image into the Base64 format produces a string that represents entire image data. You can test this by pasting the Base64 string in your browser’s address bar. It should load the image represented by the string as demonstrated below:

What we need to do next is convert each image received from the Unsplash API to a Base64 string and attach it to the image object before storing it in the local storage. Once a new tab is opened, the Base64 string will be retrieved and used in the background-image property instead of the image URL.

To convert an image to a Base64 string, we need to retrieve the image data first. Here’s how:

async function getRandomPhoto() {
  let endpoint = '';

  const headers = new Headers();
  headers.append('Authorization', `Client-ID ${UNSPLASH_ACCESS_KEY}`);

  let response = await fetch(endpoint, { headers });
  const json = await validateResponse(response).json();
  // Fetch the raw image data. The query parameters are used to control the size
  // and quality of the image:
  // q - compression quality
  // w - image width
  // See all the suported parameters:
  response = await fetch(json.urls.raw + '&q=85&w=2000');
  // Verify the status of the response (must be 200 OK)
  // and read a Blob object out of the response.
  // This object is used to represent binary data and
  // is stored in a new `blob` property on the `json` object.
  json.blob = await validateResponse(response).blob();

  return json;

The raw URL consists of a base image URL which we can add additional image
 to control the size, quality and format of the image. The query parameters &q=85&w=2000 will produce an image with a width of 2000px and 85% quality compared to the original. This should represent a good enough quality for most screen sizes.

To read the image data from the response, the blob() method is used. This returns a Blob object that represents the image data. This object is then set on a new blob property on the json object. The next step is to encode the blob object into a Base64 string so that it may be saved to local storage. Modify the nextImage()
function in your background.js file as shown below:

async function nextImage() {
  try {
    const image = await getRandomPhoto();

    // the FileReader object lets you read the contents of
    // files or raw data buffers. A blob object is a data buffer
    const fileReader = new FileReader();
    // The readAsDataURL method is used to read
    // the contents of the specified blob object
    // Once finished, the binary data is converted to
    // a Base64 string
    // The `load` event is fired when a read
    // has completed successfully. The result
    // can be found in ``
    fileReader.addEventListener('load', event => {
      // The `result` property is the Base64 string
      const { result } =;
      // This string is stored on a `base64` property
      // in the image object
      image.base64 = result;
      // The image object is subsequently stored in
      // the browser's local storage as before{ nextImage: image });
  } catch (err) {

The FileReader API is how we convert the image blob to a Base64 encoded string. The readAsDataURL() method reads the contents of the image.blob property. When the read is completed, the load event is fired and the result of the operation can be accessed under as shown above. This result property is a Base64 encoded string which is then stored on the image object in a new base64 property and the entire object is
subsequently stored in Chrome’s local storage area for extensions.

Note: Make sure to reload the extension after saving your background.js file

The next step is to update the value of the background style used to set the body background in setImage function. Replace image.urls.full with image.base64 as shown below:

function setImage(image) {
    `background-image: url(${image.base64});`

If you open a new tab, you will observe that the background image loads instantly. This is because the image is being retrieved from the local storage in its Base64 string form instead of being freshly loaded from Unsplash servers like we were doing earlier.

Load new images on each tab

At the moment, the nextImage() function is invoked only when the extension is first installed or reloaded. This means that the only way to cause a new image to load is to reload the extension in the extensions page. In this section, we’ll figure out a way to invoke nextImage() each time a new tab is opened so that a new image is fetched in the background to replace the previous one without having to reload the extension each time.

// This line is what causes the nextImage() function to be
// executed when the extension is freshly installed or reloaded.

The background.js script is not aware of when a new tab is open, but this index.jsscript is because it is a part of the custom new tab page. To communicate between the two scripts we need to send a message from one script and listen for the message in another script.

We will use the chrome.runtime.sendMessage and chrome.runtime.onMessagefunctions to add communication between the background script and new tab script. The former will be used in our index.js file to notify the background script that a new image should be fetched in the background. Modify your index.js file as shown below:

document.addEventListener('DOMContentLoaded', () => {'nextImage', (data) => {
    if (data.nextImage) {

  // Add the line below
  chrome.runtime.sendMessage({ command: 'next-image' });

Each time a new tab page loads, a message will be sent with the message object shown above. This message object can be any valid JSON object. You can also add an optional callback function as a second argument to sendMessage() if you need to handle a response from the other end but we don’t need that here.

The next step is to use the chrome.runtime.onMessage method in our background script to listen for message events and react appropriately when triggered. Add the code to the bottom of your background.js file:


// Add the lines below
chrome.runtime.onMessage.addListener((request) => {
  if (request.command === 'next-image') {
Enter fullscreen mode Exit fullscreen mode

The onMessage function is used to register a listener that listens for messages sent by chrome.runtime.sendMessage. The addListener method takes a single callback function which can take up to three parameters:

  • request: The message object from the sender
  • sender: The sender of the request
  • sendResponse: A function to call if you want to respond to the sender

We are not using sender or sendResponse in this case so I’ve left it out of the callback function. In the body of the function, an if statement is used to check the message object. If it corresponds to the message object from the new tab script, the nextImage() function is executed, causing a new image to replace the previous one.

Reload the extension and open a few new tab pages. You should see a new background image in the tabs each time. If you see the same image multiple times, it could be due to any of the two reasons below:

  • The next image is still loading in the background. The speed at which a new image can be retrieved and saved is mostly limited by your internet connection.
  • The same image is returned consecutively from Unsplash. Since images are fetched at random, there is no guarantee that a different image will be received each time. However, the pool of images from which a random one is selected is so large (except you restrict it to specific Unsplash collections) that this is unlikely to happen often.

Restrict images to user defined collections

At the moment, the pool of images from which a random one is selected is only limited by orientation according to the value of the endpoint variable in getRandomPhoto():

We can use any of the other available query parameters to further limit the pool of images. For example, we can filter images by collection:

You can retrieve a collection ID by heading to the collections page and selecting the ID from any collection URL as shown below:

Let’s add the ability for a user to optionally restrict the pool of images to those from a specific collection. We’ll create a way to do that through thepopup window which is a common way through with basic extension settings are configured. Here’s how the popup window is setup at the moment:

If you don’t see the extension icon in the top bar, make sure the icon is pinned as demonstrated in the screenshot below:

The popup window has a single input where a user may enter one or more collection IDs. The markup for this window is in the popup.html file if you want to inspect it. Our first task is to validate and save any custom collection IDs to the local storage. Open up the js/popup.js file in your text editor, and populate its contents with the following code:

const input = document.getElementById('js-collections');
const form = document.getElementById('js-form');
const message = document.getElementById('js-message');


async function saveCollections(event) {
  const value = input.value.trim();
  if (!value) return;

  try {
    // split the string into an array of collection IDs
    const collections = value.split(',');
    for (let i = 0; i  {
        message.setAttribute('class', 'success');
        message.textContent = 'Collections saved successfully!';
  } catch (err) {
    message.setAttribute('class', 'error');
    message.textContent = err;

form.addEventListener('submit', saveCollections);

document.addEventListener('DOMContentLoaded', () => {
  // Retrieve collecion IDs from the local storage (if present)
  // and set them as the value of the input'collections', (result) => {
    const collections = result.collections || '';
    input.value = collections;

Although it’s a sizeable chunk of code, it’s nothing you haven’t seen before. When the Enter key is pressed on the input, the form is submitted and saveCollections() is executed. In this function, the collection IDs are processed and eventually saved to chrome’s local storage for extensions. Don’t forget to replace the  placeholder with your actual access key.

The next step is to use any saved collection IDs in the request for a random image. Open up your background.js file and update it as shown below:

function getCollections() {
  return new Promise((resolve) => {'collections', (result) => {
      const collections = result.collections || '';

async function getRandomPhoto() {
  const collections = await getCollections();

  let endpoint = '';

  if (collections) {
    endpoint += `&collections=${collections}`;

  const headers = new Headers();
  headers.append('Authorization', `Client-ID ${UNSPLASH_ACCESS_KEY}`);

  let response = await fetch(endpoint, { headers });
  const json = await validateResponse(response).json();
  response = await fetch(json.urls.raw + '&q=85&w=2000');
  json.blob = await validateResponse(response).blob();

  return json;

The getCollections() function retrieves any saved collection IDs. If any one has been specified by the user, it is appended to the endpoint via the &collectionsquery parameter. That way, the random image will be fetched from the specified collections instead of the entire Unsplash catalogue.

Tips for debugging

Chrome extensions use the same debugging workflow as regular web pages, but they have some unique properties you need to be aware of. To debug your background script, head to the chrome extensions page at chrome://extensionsand ensure Developer mode is enabled. Next, find your extension and click background page under inspect views. This will open a DevTools window for debugging purposes.

Debugging a popup window can be done by right clicking on the popup icon and then clicking Inspect popup. This will launch a DevTools window for your popup. For the new tab page (or other override pages), debug them like you would do a regular webapage (using Ctrl+Shift+I to launch the DevTools panel).

During development, you may see an Errors button next to Details and Removeon your extension entry. This indicates that an error occurred somewhere in your extension code. Click this button to find out the exact line in your code where the error occurred.

Publishing your extension

Follow the steps detailed in this guide to publish your extension to the Chrome web store. A Google account is required.


Congratulations, you’ve successfully built your first Chrome extension. I hope you had fun building it! Feel free to leave a comment below if you have any questions or suggestions. If you want to see a more fully-fledged implementation of this particular type of Chrome extension.

Thanks for reading, and happy coding!

from Tumblr

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s