What a Chrome extension actually is, and what you can build

A Chrome extension is a small program that adds a feature to your browser. It lives in your browser toolbar, runs only when you want it to, and can do things like block ads on specific sites, save passwords to a personal vault, change how a webpage looks, or remind you to take a break. You write it in the same languages websites use — HTML, CSS, and JavaScript — which means if you can build a webpage, you can build an extension.

The extensions you download from the Chrome Web Store are built the same way. The difference is that you'll be building yours for yourself or a small group, not publishing it to millions of people. That means you don't need to worry about Chrome's store review process or reaching a massive audience — you just need to make something that works for you.

Most extensions start small: one person frustrated by something repetitive, building a tool to fix it. You might block a specific tracking domain, auto-fill a form you fill out every day, or highlight certain words on pages you read for work. The scope matters because it determines how much code you need to write.

Key Takeaways

  • A Chrome extension needs three files at minimum: a manifest file that tells Chrome what the extension does, an HTML file for the popup window, and a JavaScript file that contains the logic.
  • You test your extension by turning on Developer Mode in Chrome's extension settings, then loading your folder as an unpacked extension.
  • The manifest file is where you declare what permissions your extension needs — like access to certain websites or the ability to read what's on the page.
  • Most simple extensions use a popup that appears when you click the extension icon, but you can also run code in the background or modify the page itself.
  • Chrome extensions use Manifest V3, the current standard, which is stricter about security than older versions but still lets you build powerful tools.

The three files every extension needs

Create a new folder on your computer. Inside it, you need at least three files: manifest.json, popup.html, and popup.js. The manifest is a text file that tells Chrome what your extension is called, what version it is, what it does, and what permissions it needs. The HTML file is what appears when someone clicks your extension icon. The JavaScript file is where the actual work happens.

Start with the manifest. Open a text editor (Notepad on Windows, TextEdit on Mac, or any code editor) and save this as manifest.json in your folder:

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

Change the name and description to match what your extension does. The permissions field is where you tell Chrome what your extension is allowed to access. "activeTab" means it can see the current webpage. If you need to access data from all websites, you'd add "scripting" and list the sites you want to work on.

Next, create popup.html:

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

This is a normal HTML file. It creates a button and loads your JavaScript file. Finally, create popup.js:

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

This JavaScript listens for a click on the button and shows an alert. These three files are your foundation. Everything else builds from here.

Loading your extension into Chrome for testing

Put all three files in the same folder. Open Chrome and go to chrome://extensions in the address bar. In the top right corner, turn on Developer Mode — you'll see a toggle switch. Once it's on, a new button appears that says Load unpacked. Click it and select your folder.

Chrome will load your extension immediately. You should see it appear in your toolbar as a small icon. Click the icon and your popup should appear with the button you created. Click the button and you'll see the alert. If something doesn't work, check the console for errors: right-click the extension icon, select Inspect popup, and look at the Console tab.

Every time you change your code, you need to reload the extension. Go back to chrome://extensions, find your extension, and click the refresh icon. This loads your new code. You'll do this many times while building, so keep that page open in a tab.

What permissions mean and why they matter

The permissions field in your manifest is a contract between you and the user. It tells Chrome — and anyone who installs your extension — exactly what access you're asking for. If you ask for permission to read every website, Chrome will warn the user. If you only ask for permission to work on one specific site, the user knows your extension is limited.

Common permissions include "activeTab" (access to the current webpage), "scripting" (ability to run JavaScript on pages), "storage" (ability to save data locally), and "tabs" (ability to see what tabs are open). If you want to work on specific websites only, you list them in a "host_permissions" field instead of asking for all sites.

For example, if you're building an extension that only works on Gmail, your manifest would include:

"host_permissions": ["https://mail.google.com/*"]

This tells the user your extension only touches Gmail. If you ask for broad permissions you don't actually need, users won't trust your extension, and Chrome may reject it if you ever try to publish it. Ask for the minimum you need to do the job.

Building beyond the popup: content scripts and background workers

A popup is what appears when you click the extension icon, but it closes as soon as you click away. If you want your extension to run code on the page itself — like highlighting words or blocking elements — you need a content script. If you want something to run in the background even when the popup is closed, you need a background worker.

A content script is JavaScript that runs directly on the webpage. To add one, create a new file called content.js with your code, then add this to your manifest:

"content_scripts": [   {     "matches": ["<all_urls>"],     "js": ["content.js"]   } ]

Now your code runs on every webpage. You can modify the page, listen for user actions, or send messages back to your popup. A background worker is similar but runs separately from any webpage. It's useful for tasks like checking something every hour or storing data. Most simple extensions start with just a popup and add these later if needed.

Common mistakes and how to avoid them

The most common mistake is forgetting to reload your extension after making changes. You change your code, test it, nothing happens, and you think something is broken. It's not — you just need to hit refresh on the extension page. Make it a habit.

The second mistake is asking for too many permissions. If your extension only needs to work on one website, don't ask for permission to access all websites. Users will be suspicious, and Chrome will flag it. Be specific.

The third mistake is putting all your code in the manifest. The manifest is just configuration. Your actual logic goes in JavaScript files. Keep the manifest simple and focused on declaring what your extension does and what it needs.

The fourth mistake is not testing on different websites. Your extension might work perfectly on one site and break on another because of how that site's code is structured. Test on a few different pages to catch these issues early.

Where to learn more and what to build next

Google's official Chrome extension documentation is the authoritative source. Search for "Chrome extension documentation" and you'll find guides on every feature, API, and permission. The examples there are more complex than what you've built here, but they show you what's possible.

Start with something small and specific. Don't try to build the next big productivity tool. Build something that solves one problem for you. A tool that reformats dates on a website you use, a button that opens five tabs at once, a script that hides certain elements. Small projects teach you how the system works without overwhelming you.

Once you understand the basics, you can explore Chrome's APIs — the built-in functions that let your extension do more. The storage API lets you save data. The tabs API lets you control tabs. The alarms API lets you schedule tasks. Each one opens new possibilities, but you don't need them to start.

Frequently Asked Questions

Can I publish my extension to the Chrome Web Store?

Yes, but it requires a developer account, a one-time fee, and Chrome's review process. Your extension must follow Chrome's policies on privacy, security, and what it's allowed to do. Most people start by building for themselves and only publish if they think others would find it useful.

What's the difference between Manifest V2 and Manifest V3?

Manifest V3 is the current standard and is stricter about security. V2 is older and no longer supported. If you see old tutorials using V2, ignore them — build with V3. The basics are the same, but some features changed.

Can my extension access passwords or credit card numbers?

No. Chrome blocks extensions from accessing sensitive data like passwords and payment information. This is a security feature that protects users. Your extension can only access what the user's permissions allow.

Do I need to know advanced JavaScript to build an extension?

No. Basic JavaScript is enough to start. You need to understand variables, functions, and event listeners. You don't need to know frameworks or advanced patterns. Learn as you go and look up what you need.

What happens if my extension breaks after a Chrome update?

Chrome updates rarely break extensions, but it happens. If it does, check the console for error messages, compare your code to the current documentation, and update what's outdated. Most breaks are fixable with small changes.