What you need to build a Chrome extension

A Chrome extension is a small program that adds features to your browser. You do not need to be a professional programmer to build one — you need a text editor, a basic understanding of JavaScript, and the Chrome browser itself. Most extensions are built with three files: a manifest file that tells Chrome what your extension does, a JavaScript file that contains the actual code, and optionally an HTML file for any popup window or settings page.

The manifest file is the most important piece. It is a JSON file (a straightforward text format) that lists your extension's name, version, what permissions it needs, and which files to load. Chrome reads this file first and refuses to load the extension if anything is wrong with it. You can write and edit all these files in any text editor — Notepad, Visual Studio Code, or even the built-in editor on your computer.

You do not need to pay anything or sign up for a service to build and test an extension on your own computer. You only pay a one-time fee if you want to publish it in the Chrome Web Store so other people can read it.

Key Takeaways

  • Every extension needs a manifest.json file, a JavaScript file, and optionally an HTML file for the popup — you can create these in any text editor.
  • Load your extension into Chrome by going to chrome://extensions, turning on Developer Mode, and clicking "Load unpacked" to point to your extension folder.
  • Test your extension by clicking its icon in the toolbar and checking the browser console for errors using Ctrl+Shift+J (Windows) or Cmd+Option+J (Mac).
  • The Chrome Web Store charges a one-time $5 fee to publish, but you can build and test extensions for free on your own computer indefinitely.
  • Common beginner mistakes include forgetting to reload the extension after making changes, using outdated Manifest V2 code instead of Manifest V3, and requesting more permissions than necessary.

Create the three core files for your extension

Start by creating a new folder on your computer. Name it something straightforward like "my-extension". Inside that folder, create three files: manifest.json, background.js, and popup.html. You can create these by opening your text editor, typing the code, and saving the file with the correct name and extension.

The manifest.json file tells Chrome what your extension is called, what version it is, and what it does. Here is a basic example that creates an extension with a popup window:

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

The "manifest_version": 3 line is important — this is the current standard. Older extensions used version 2, and Chrome no longer supports them. The "permissions" section lists what your extension is allowed to do. Start with just "activeTab" (which lets your extension see the current page) and add more only if you need them.

The popup.html file is what appears when someone clicks your extension's icon. Start with a straightforward version:

<!DOCTYPE html> <html> <head>   <title>My Extension</title> </head> <body>   <h1>Hello!</h1>   <p>This is my extension.</p> </body> </html>

The background.js file contains the code that runs behind the scenes. For now, you can leave it nearly empty — just a comment explaining what it does. As your extension grows, this is where you add the logic that makes it actually do something.

Load your extension into Chrome for testing

Open Chrome and go to chrome://extensions in the address bar. You will see a page listing all your installed extensions. In the top right corner, turn on the toggle for "Developer mode". This unlocks the ability to load extensions from your computer without publishing them.

Once Developer mode is on, a button labeled "Load unpacked" appears in the top left. Click it and navigate to the folder you created (the one containing manifest.json, background.js, and popup.html). Select that folder and click "Select Folder". Chrome will load your extension when ready.

If Chrome shows an error message, read it carefully — it usually tells you exactly what is wrong. Common mistakes at this stage are typos in the manifest.json file (especially missing commas or quotes) or file names that do not match what the manifest says to load. Fix the error, save the file, and come back to the chrome://extensions page. Click the reload icon (the circular arrow) next to your extension to load the updated version.

Once your extension loads without errors, you should see a small icon in the top right of your Chrome toolbar. Click it to see your popup.html appear. If nothing happens, check the browser console for error messages by pressing Ctrl+Shift+J (Windows) or Cmd+Option+J (Mac).

Add actual functionality with JavaScript

The popup you created is just a static page. To make your extension actually do something, you need to add JavaScript code. A common first project is an extension that counts how many times you have visited the current website. This teaches you how to store data and update it when the user does something.

Update your popup.html to include a button and a display area:

<!DOCTYPE html> <html> <head>   <title>My Extension</title> </head> <body>   <h1>Visit Counter</h1>   <p>You have visited this site <span id="count">0</span> times.</p>   <button id="resetBtn">Reset</button>   <script src="popup.js"></script> </body> </html>

Now create a new file called popup.js in the same folder. This file will run when the popup opens and handle the button click:

document.getElementById("resetBtn").addEventListener("click", function() {   chrome.storage.local.set({ count: 0 });   document.getElementById("count").textContent = "0"; }); chrome.storage.local.get(["count"], function(result) {   let currentCount = result.count || 0;   document.getElementById("count").textContent = currentCount; });

This code uses Chrome's storage system to save a number. When the page loads, it reads that number and displays it. When the user clicks the reset button, it sets the count back to zero. Update your manifest.json to include the storage permission and point to popup.js:

"permissions": ["activeTab", "storage"], "action": {   "default_popup": "popup.html",   "default_title": "Click me" }

Go back to chrome://extensions, reload your extension, and click its icon. You should now see a working counter with a reset button.

Common mistakes and how to avoid them

The most common mistake is forgetting to reload your extension after making changes. Every time you edit a file, go back to chrome://extensions and click the reload icon next to your extension. Without this step, Chrome is still running the old version.

The second mistake is requesting too many permissions. Every permission you ask for makes users less likely to install your extension because they worry about privacy. Only request what you actually need. If your extension does not need to see the content of web pages, do not ask for "scripting" permission. If it does not need to store data, do not ask for "storage".

The third mistake is using old code examples from the internet. Many tutorials teach Manifest V2, which Chrome stopped supporting in 2024. Always check that any code example you follow mentions "Manifest V3" or "MV3". If it does not, the code will not work.

The fourth mistake is not checking the console for errors. Press Ctrl+Shift+J (Windows) or Cmd+Option+J (Mac) to open the browser console. If your extension is not working, the error message there will tell you exactly what is wrong and which line of code caused it. Read the error message — it is usually more helpful than you think.

Publishing your extension to the Chrome Web Store

Once your extension works the way you want, you can publish it so other people can read it. Go to the Chrome Web Store developer dashboard at chrome.google.com/webstore/devconsole. You will need a Google account. The first time you publish, you pay a one-time $5 fee. After that, you can update your extension as many times as you want for free.

Before you publish, prepare a few things: a 128x128 pixel icon image (PNG format), a short description of what your extension does (under 132 characters), and a longer description (under 4,400 characters). You also need to decide what category your extension belongs in — for example, "Productivity" or "Developer Tools".

Upload your extension folder as a ZIP file. The developer dashboard will scan it, check that your manifest.json is correct, and verify that you are not asking for unnecessary permissions. If everything passes, your extension goes live in the Chrome Web Store within a few hours. People can then search for it by name and read it just like any other extension.

After publishing, you can update your extension by uploading a new version. Increment the version number in your manifest.json (for example, change "1.0" to "1.1"), then upload the updated ZIP file. Chrome will roll out the new version to all users over the next few days.

Resources for learning more

The official Chrome Extension documentation at developer.chrome.com/docs/extensions is the most reliable source. It includes tutorials, API references, and examples for every feature Chrome extensions support. Start with the "Getting started" section if you are new to extensions.

MDN Web Docs (developer.mozilla.org) has excellent explanations of JavaScript, HTML, and CSS. If you get stuck on a JavaScript concept, search MDN first — the explanations are clearer than most tutorials.

Stack Overflow (stackoverflow.com) is useful when you have a specific error message or problem. Search for your error message first — someone has probably solved it before. If you do not find an answer, you can ask a question, but read the site's guidelines first so your question is clear and specific.

Frequently Asked Questions

Can I build a Chrome extension if I do not know JavaScript?

You can build a very straightforward extension with just HTML and CSS, but most useful extensions need at least basic JavaScript. The good news is that JavaScript is one of the easiest programming languages to learn. Start with a tutorial on JavaScript basics, then explore what you learn to a small extension project. You will learn faster by building something real than by reading tutorials alone.

What is the difference between a content script and a background script?

A content script runs on the web pages you visit and can see and change the page content. A background script runs in the background and handles storage, timers, and communication between different parts of your extension. Most extensions use both. Start with just a background script and a popup, then add a content script only if you need to interact with the page itself.

How do I make my extension work on a specific website only?

Use the "host_permissions" field in your manifest.json to limit where your extension runs. For example, to make it work only on Google.com, add "host_permissions": ["*://google.com/*"]. This also reduces the permissions you are asking for, which makes users more likely to install it.

Can I use a framework like React or Vue in my extension?

Yes, but it adds complexity. For your first extension, stick with plain JavaScript, HTML, and CSS. Once you understand how extensions work, you can experiment with frameworks. Many developers use React for larger extensions, but the setup is more involved and the extension file size is larger.

What happens if my extension breaks after a Chrome update?

Chrome updates happen regularly, but they rarely break extensions. If your extension stops working, check the chrome://extensions page for error messages. Most often, the problem is a typo or a permission you forgot to add. If you cannot figure it out, search the Chrome Extension documentation for the feature you are using — the API may have changed slightly.