Build Your First Chrome Extension (Part 1)

Chrome Extensions · Part 1 of 4

If you’ve ever wanted to build your own Chrome extension but had no idea where to start, this series is for you. Extensions are much easier to build than most people expect, and if you know a little HTML, CSS and JavaScript you can have a working one running in under 30 minutes.

This is the first post in a four-part series where you’ll build, test and eventually publish a Chrome extension from scratch. By the end of today, you’ll have an extension that opens a popup and shows a custom message when you click its icon. Every extension we build at Studio Grid, including Studio Colour, starts from this same skeleton.

What you’ll build

Today’s extension is deliberately tiny. When you click its icon in the Chrome toolbar, a small popup appears:

Hello, Chrome!

Congratulations! Your first extension is working.

It’s a modest start, and every serious extension, from password managers to ad blockers, is built on this same foundation. Once the structure makes sense, everything after it is a matter of adding features.

How a Chrome extension actually works

A Chrome extension is a small web app that runs inside Chrome itself, outside of any single tab. It’s built from the same HTML, CSS, JavaScript and images you already use for websites.

What turns a folder of web files into an extension is one special file called manifest.json. Think of it as the instruction manual Chrome reads first. It tells Chrome the extension’s name, its version, which icon to show, which files to load and what permissions it needs. Without a manifest, Chrome won’t recognize your folder as an extension.

Set up your project folder

You don’t need any special software. Create a new folder anywhere on your computer (we’ll call it hello-extension) and add four files plus an icons folder:

hello-extension/
├── icons/
│   └── icon128.png
├── manifest.json
├── popup.html
├── popup.css
└── popup.js

For now, any 128×128 PNG will work as your icon. Drop one into the icons folder and name it icon128.png.

Write the manifest.json

Open manifest.json and paste this in. It’s the heart of the whole extension.

{
  "manifest_version": 3,
  "name": "Hello Extension",
  "description": "My first Chrome extension.",
  "version": "1.0",

  "action": {
    "default_popup": "popup.html"
  },

  "icons": {
    "128": "icons/icon128.png"
  }
}

Here’s what each part does.

manifest_version

Chrome currently uses Manifest V3, so every new extension should set "manifest_version": 3. Version 2 is being phased out, so don’t start a new project on it.

name, description & version

The name is what users see in Chrome, and the description is a one-line summary. The version is a number you raise every time you publish an update, so start at "1.0".

action

This tells Chrome what happens when someone clicks your icon. Here, "default_popup": "popup.html" means Chrome opens popup.html in a small window.

icons

This points Chrome at the icon it shows in the toolbar, which is the 128px PNG you just added.

Build the popup

The popup is an ordinary web page that Chrome shows in a small floating window. It’s made of the three files you’d expect.

The HTML

Open popup.html and paste this in.

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <link rel="stylesheet" href="popup.css">
</head>
<body>
  <h1>Hello, Chrome!</h1>
  <p>Congratulations! Your first extension is working.</p>
  <script src="popup.js"></script>
</body>
</html>

The CSS

Open popup.css. The width on the body decides how wide the popup opens. This one is 280 pixels, and most extension popups fall somewhere between 280 and 400.

body {
  font-family: Arial, sans-serif;
  width: 280px;
  padding: 20px;
}
h1 {
  margin-top: 0;
  font-size: 24px;
}
p {
  line-height: 1.5;
}

The JavaScript

Open popup.js. In this first lesson its only job is to confirm the file is loading.

console.log("Hello Extension Loaded!");

You won’t see anything change on screen yet. In Part 2 we’ll make the popup interactive with buttons, input and saved settings.

Load it into Chrome

With the files in place, open Chrome and go to this address:

chrome://extensions

Turn on Developer mode in the top-right corner and three new buttons will appear. Click Load unpacked, then select your hello-extension folder. If everything is in order, your extension shows up straight away.

Test your extension

Click the puzzle-piece icon in Chrome’s toolbar, find your extension, and pin it if you like. When you click its icon, you should see your popup:

Hello, Chrome!

Congratulations! Your first extension is working.

If that message appears, you’ve built your first Chrome extension.

Troubleshooting

These are the problems that most often trip people up on the first try.

Nothing appears

Double-check that the folder has all four files and that the icons folder contains your PNG.

Chrome says the manifest is invalid

Open manifest.json and look for a missing or extra comma, a missing quotation mark or a mismatched bracket. A single typo is enough to break it.

My CSS isn’t loading

Make sure the HTML links to it and that the filename matches exactly.

<link rel="stylesheet" href="popup.css">

My JavaScript isn’t loading

Confirm this line sits just before the closing </body> tag.

<script src="popup.js"></script>

Then open the popup, right-click inside it, choose Inspect, and check the Console for errors.

What’s next

Your extension shows a static popup for now, which is a solid foundation to build on. In Part 2 we’ll make it interactive by adding buttons, handling user input and saving settings with Chrome Storage, so the extension remembers them even after Chrome closes.

At their core, extensions are small web apps with a manifest that tells Chrome how to run them. Once you’re comfortable with the structure you built today, you’re ready to add real interactivity and, eventually, ship your own extension to the Chrome Web Store.