What you're actually building

A Chrome extension is a small program that adds a feature to your browser. It lives in your extensions menu (the puzzle piece icon in the top right), and you control when it runs. You write it using the same languages you'd use for a website — HTML, CSS, and JavaScript — but instead of displaying on a server, it runs inside Chrome itself.

The smallest working extension needs three files: a manifest file that tells Chrome what the extension does, an HTML file for any popup window, and a JavaScript file for the actual work. You don't need to publish it to the Chrome Web Store to test it. You can load it directly into Chrome from a folder on your computer, which is how you'll develop and debug it.

Key Takeaways

  • Every extension starts with a manifest.json file that describes the extension's name, version, permissions, and what it does.
  • You write extension code in HTML, CSS, and JavaScript — the same languages used for websites — and test it locally before publishing.
  • Chrome's Developer Mode lets you load an unpublished extension directly from a folder on your computer so you can test changes immediately.
  • The extension runs in the background or in a popup window, and can read or modify web pages, store data, or respond to user clicks.
  • Debugging uses Chrome's built-in DevTools, the same inspector you'd use on a regular website.

Set up your extension folder and manifest file

Create a new folder on your computer. Name it something clear like "my-first-extension". Inside that folder, create a file called manifest.json. This file is required — Chrome won't recognize the folder as an extension without it.

Open manifest.json in a text editor (Notepad, VS Code, or any plain-text editor works) and paste this code:

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

The manifest tells Chrome the extension's name, what permissions it needs (in this case, permission to see the current tab), and that clicking the extension icon should open a popup window. If you want the extension to run in the background instead of showing a popup, you'd add a "background" section instead of "action". For now, the popup approach is simpler to test.

Create the popup window with HTML

In the same folder, create a file called popup.html. This is the window that appears when someone clicks your extension icon. Paste this code:

<!DOCTYPE html> <html> <head> <style> body { width: 300px; padding: 10px; font-family: Arial, sans-serif; } button { padding: 10px; background-color: #4CAF50; color: white; border: none; cursor: pointer; } </style> </head> <body> <h1>Hello</h1> <p>Click the button below.</p> <button id="myButton">Click Me</button> <script src="popup.js"></script> </body> </html>

This creates a simple popup with a button. The popup.js file (which you'll create next) will handle what happens when the button is clicked. The style section just makes it look reasonable — you can change the colors and size to whatever you want.

Write the JavaScript that makes it work

Create a file called popup.js in the same folder. This is where you write the code that actually does something. Paste this code:

document.getElementById("myButton").addEventListener("click", function() { alert("Button was clicked!"); });

This code finds the button by its ID ("myButton"), waits for someone to click it, and shows an alert box when they do. This is the bare minimum — it proves the extension works. Once you have this running, you can replace the alert with something more useful: reading the current web page, storing data, sending a message to a background script, or anything else JavaScript can do.

Now you have three files in your folder: manifest.json, popup.html, and popup.js. That's a complete, working extension. The next step is loading it into Chrome.

Load the extension into Chrome using Developer Mode

Open Chrome and go to chrome://extensions in the address bar. You'll see a page listing all your installed extensions. In the top right corner, toggle on the switch labeled Developer mode. New buttons will appear: "Load unpacked", "Pack extension", and "Update".

Click Load unpacked. A file browser will open. Navigate to the folder you created (my-first-extension) and select it. Chrome will load the extension immediately. You should see it appear in your extensions list, and the icon should show up in your browser's top right corner (in the extensions menu if there's no room in the main toolbar).

Click the extension icon. Your popup should appear with the button. Click the button and the alert should show. If nothing happens, check the browser console for error messages: right-click on the popup, select "Inspect", and look at the Console tab. Error messages will tell you what's wrong.

Test changes and debug problems

As you edit your files, Chrome won't automatically reload the extension. Go back to chrome://extensions, find your extension, and click the refresh icon (circular arrow) next to it. Your changes will load. This is the normal workflow: edit a file, refresh the extension, test it, repeat.

If something breaks, use the Inspector. Right-click on the popup window and select "Inspect element" to open DevTools. The Console tab shows error messages. The Elements tab shows the HTML structure. The Sources tab lets you set breakpoints and step through your JavaScript line by line, just like debugging a website.

Common mistakes: forgetting to refresh after editing, misspelling file names in the manifest, and forgetting to add required permissions. If the extension icon doesn't appear, check the manifest.json syntax — even a missing comma will break it. If the button doesn't work, check that the button's ID in the HTML matches the ID you're looking for in JavaScript.

Expand what your extension can do

Once the basic structure works, you can add real functionality. Some common patterns: read the current web page using the activeTab permission and modify it, store data using Chrome's storage API so settings persist between sessions, send messages between the popup and a background script, or respond to keyboard shortcuts.

Each of these requires adding permissions to the manifest and writing more JavaScript. The Chrome documentation has examples for each pattern. Start with one small feature, test it, then add the next one. Building extensions is the same as building websites — you write a little, test it, fix it, then write more.

Frequently Asked Questions

Do I need to publish my extension to the Chrome Web Store to use it?

No. You can load it directly from a folder using Developer Mode and use it privately. Publishing to the Web Store is optional and requires a one-time developer fee. Most people test and use extensions locally for months before publishing.

What's the difference between manifest version 2 and 3?

Manifest version 3 is the current standard. Version 2 is older and Chrome is phasing it out. Always use version 3 for new extensions. If you find old tutorials using version 2, the structure is slightly different — the code won't work without changes.

Can my extension run code on every website I visit?

Yes, but you need the right permissions in the manifest. Use "content_scripts" to inject JavaScript into web pages and "host_permissions" to specify which sites it runs on. Be careful — this is powerful and users should understand what sites your extension touches.

How do I debug if nothing is happening when I click the button?

Right-click the popup and select "Inspect". The DevTools console will show JavaScript errors. Check that the button's ID in the HTML exactly matches the ID in your JavaScript code — even capitalization matters. Refresh the extension after editing and try again.

Can I use external libraries like jQuery in my extension?

Yes. Download the library file, put it in your extension folder, and link to it in your HTML the same way you would on a website. Some libraries have restrictions in manifest version 3 around inline scripts, but most work fine. Start with plain JavaScript first to understand how extensions work, then add libraries once you're comfortable.