How to Build a Chrome Extension: A Step-by-Step Guide

What you need to know before you start

A Chrome extension is a small program that adds a feature or changes how Chrome works. You write it using the same languages you'd use for a website — HTML, CSS, and JavaScript — and Chrome handles the rest. You don't need special permission from Google, and you don't need to publish it anywhere if you only want to use it yourself. The whole process takes a few hours if you're building something straightforward, like a tool that changes the color of web pages or blocks certain words.

The barrier to entry is low because Chrome extensions run in a sandbox — they can't access your files or your operating system directly. That also means they have limits on what they can do. If you want to build something that works only for you, you can load it as an unpublished extension. If you want to share it with others, you'll need to package it and submit it to the Chrome Web Store, which involves a one-time fee and a review process.

Key Takeaways

Chrome extensions use HTML, CSS, and JavaScript — the same languages as websites — so you can start building one if you already know those languages or are willing to learn them.
You need a manifest file (a text file that tells Chrome what your extension does) and at least one JavaScript file to make the extension run.
You can test your extension on your own computer by loading it in developer mode before you publish it anywhere.
Publishing to the Chrome Web Store requires a Google developer account, a one-time registration fee, and a review that usually takes a few days.
An unpublished extension only works on your own computer and only in the Chrome browser where you loaded it.

The three files every extension needs

Every Chrome extension starts with a folder on your computer containing at least three things: a manifest file, a background script, and a popup or content script. The manifest file is a text file named manifest.json that tells Chrome the extension's name, what permissions it needs, and which files to run. Think of it as the instruction manual Chrome reads first.

The background script is a JavaScript file (usually named background.js) that runs in the background and listens for events — like when you click the extension icon or when a page loads. The popup is the small window that appears when you click the extension icon in Chrome's toolbar. It's built with HTML and CSS, just like a web page, and it can run its own JavaScript to respond to clicks or changes.

If your extension needs to change the content of web pages themselves (like hiding ads or highlighting text), you'll also need a content script — another JavaScript file that runs inside the page itself, not in the background. Content scripts can read and modify the page, but they have fewer permissions than background scripts.

Writing your manifest file

The manifest file is where you declare what your extension does and what it needs permission to do. Open a text editor (Notepad, VS Code, or any plain-text editor) and create a file named manifest.json. Here's a minimal example for an extension that adds a button to your toolbar:

{ "manifest_version": 3, "name": "My First Extension", "version": "1.0", "description": "A straightforward extension that does one thing", "permissions": ["activeTab"], "action": { "default_popup": "popup.html", "default_title": "Click me" }, "background": { "service_worker": "background.js" } }

The manifest_version must be 3 (older versions are no longer supported). The permissions array lists what your extension is allowed to do — activeTab means it can see the current tab you're looking at. If you need to access storage, add "storage". If you need to run on all websites, add "scripting". The more permissions you ask for, the more Chrome warns users about your extension, so only request what you actually need.

Creating the popup and background script

Create a file named popup.html in the same folder as your manifest. This is the window that opens when someone clicks your extension icon. Here's a straightforward example:

<!DOCTYPE html> <html> <head> <style> body { width: 300px; padding: 10px; font-family: Arial; } button { padding: 10px; background-color: blue; color: white; } </style> </head> <body> <h1>My Extension</h1> <button id="myButton">Click me</button> <script src="popup.js"></script> </body> </html>

Now create popup.js to handle what happens when the button is clicked:

document.getElementById("myButton").addEventListener("click", () => { chrome.tabs.query({active: true, currentWindow: true}, (tabs) => { chrome.tabs.sendMessage(tabs[0].id, {greeting: "hello"}); }); });

Create background.js as an empty file for now — it can stay empty if your extension doesn't need to listen for events in the background. If you want your extension to do something when a page loads or when you click the icon, you'll add code here later.

Loading your extension in Chrome

Open Chrome and go to chrome://extensions in the address bar. In the top right, turn on Developer mode. You'll see a button that says "Load unpacked". Click it and navigate to the folder where you saved your manifest, popup, and background files. Chrome will load your extension when ready.

Your extension icon will appear in the toolbar at the top right of Chrome. Click it to see your popup. If something doesn't work, go back to chrome://extensions, find your extension, and click "Errors" to see what went wrong. Most errors are typos in the manifest or missing files.

Every time you change your code, refresh the extension by clicking the refresh icon next to its name on the extensions page. You don't need to reload Chrome itself.

Testing and debugging your extension

Chrome's developer tools work on extensions just like they work on websites. Right-click on your extension's popup and select "Inspect". A developer console will open where you can see any error messages and test JavaScript code. If your extension isn't showing up in the toolbar, check the manifest for typos — the most common mistake is misspelling a filename or forgetting a comma.

If you're building a content script (code that runs inside web pages), you'll need to add it to your manifest under "content_scripts" and specify which websites it should run on. Test it by opening one of those websites and checking the console for errors.

Keep your extension straightforward while you're learning. A single button that does one thing is easier to debug than an extension that tries to do five things at once. Once you have one feature working, add the next one.

Publishing to the Chrome Web Store

If you want other people to use your extension, you'll need to publish it. Go to the Chrome Web Store developer dashboard and sign in with a Google account. You'll need to pay a one-time registration fee (currently $5) to publish extensions.

Upload a ZIP file of your extension folder, write a description and take a screenshot of your extension in action, and submit it for review. Google's review process usually takes a few days. They check that your extension does what it claims to do and that it doesn't violate their policies — for example, it can't steal data, display misleading ads, or impersonate other software.

Once approved, your extension will appear in the Chrome Web Store and anyone can install it. You can update it anytime by uploading a new version with a higher version number in your manifest.

Frequently Asked Questions

Do I need to know JavaScript to build a Chrome extension?

Yes, you need at least basic JavaScript. If you don't know it yet, spend a few hours learning the fundamentals — variables, functions, event listeners, and how to select HTML elements. Mozilla's JavaScript guide and freeCodeCamp both have free tutorials that will get you started quickly enough to build a straightforward extension.

Can I make an extension that works on all websites?

Yes, but you need to ask for broad permissions in your manifest. Add "host_permissions": ["<all_urls>"] to run your content script on every website. Chrome will warn users that your extension can see everything they do, so only ask for this if you genuinely need it.

What's the difference between a content script and a background script?

A content script runs inside the web page itself and can read and change what's on the page. A background script runs separately and can listen for events like when you click the extension icon or when a new tab opens. Content scripts have fewer permissions but can do more with the page; background scripts have more permissions but can't directly change the page.

Can I test my extension without publishing it?

Yes. Load it in developer mode on your own computer and it will work just like a published extension — only on your machine and only in Chrome. You can share it with others by sending them the folder, and they can load it the same way. It won't appear in the Chrome Web Store, and it won't auto-update when you make changes.

What happens if my extension breaks after a Chrome update?

Chrome updates the extension API occasionally, which can break older extensions. If your extension stops working, check the Chrome release notes to see what changed. Most breaks are small — a function name changed or a permission was renamed. The Chrome developer documentation lists all the changes in each version.

This guide is for general information only and is not medical, financial, legal, or other professional advice. For decisions specific to your situation, consult a qualified professional. See our Editorial Policy.