What a Chrome extension actually is, and what you can build
A Chrome extension is a small program that runs inside your browser and changes how Chrome works. It can add a button to your toolbar, modify how a website looks, block ads, save passwords, or run code on pages you visit. You write it in JavaScript, HTML, and CSS — the same languages that make websites work — and Chrome reads a straightforward text file called a manifest to understand what your extension does.
Most people build extensions to solve a specific problem: highlight certain words on a page, auto-fill a form you use every day, block a particular tracker, or add a feature that a website should have but doesn't. You are not building something to sell or share widely. You are building something for yourself or a small team, which means you do not need to worry about app store review, user support, or making it polished for strangers.
The barrier to entry is low. You do not need special tools or a developer account. You write three or four text files, put them in a folder, and tell Chrome to load that folder. If you have ever edited a text file or looked at HTML, you can build a basic extension in an afternoon.
Key Takeaways
- A Chrome extension needs at least three files: a manifest (which tells Chrome what the extension does), a background script (which runs your code), and optionally a popup or content script (which interacts with web pages).
- You write extensions in JavaScript, HTML, and CSS, and test them by loading the folder directly into Chrome using Developer Mode.
- Content scripts let you modify pages you visit; background scripts run in the background and can listen for events like tab changes or button clicks.
- Extensions can read and modify page content, store data locally, send messages between scripts, and respond to user actions — but they cannot access files on your computer without permission.
The three files you need to start
Every extension needs a manifest.json file. This is a text file that tells Chrome the extension's name, version, what it does, and which files it uses. Open a text editor (Notepad on Windows, TextEdit on Mac, or any code editor), and create a file with this content:
{ "manifest_version": 3, "name": "My First Extension", "version": "1.0", "description": "A straightforward extension that does something useful", "permissions": ["scripting", "activeTab"], "action": { "default_popup": "popup.html", "default_title": "Click me" }, "background": { "service_worker": "background.js" } }
Save this file as manifest.json in a new folder. The folder name does not matter — call it something like "my-extension".
Next, create a popup.html file. This is what appears when you click the extension button in your toolbar. Start with this:
<!DOCTYPE html> <html> <head> <title>My Extension</title> </head> <body> <h1>Hello</h1> <button id="myButton">Click me</button> <script src="popup.js"></script> </body> </html>
Save this as popup.html in the same folder. Finally, create popup.js with this code:
document.getElementById("myButton").addEventListener("click", function() { alert("Button clicked!"); });
Save it as popup.js. You now have a working extension. It will not do much — just show a button that triggers an alert — but it will load and run.
Loading your extension into Chrome
Open Chrome and type chrome://extensions into the address bar. You will see a page listing all your installed extensions. In the top right corner, turn on Developer mode (there is a toggle switch).
Once Developer mode is on, you will see a button that says "Load unpacked". Click it, then navigate to the folder where you saved your three files and select it. Chrome will load your extension when ready. You should see a new icon in your toolbar — click it and you will see your popup with the button.
Every time you change the code in your files, refresh the extension. Go back to chrome://extensions, find your extension, and click the refresh icon. The changes take effect right away. This cycle — edit, save, refresh, test — is how you build and debug.
Modifying web pages with content scripts
A content script is code that runs on the web pages you visit. It can read the page, change what it looks like, or send information back to your extension. To add one, first update your manifest.json to include this section:
"content_scripts": [ { "matches": ["<all_urls>"], "js": ["content.js"] } ]
Then create a file called content.js with this code:
console.log("Content script loaded on " + document.title); document.body.style.backgroundColor = "lightblue";
Save it in your extension folder, refresh the extension in chrome://extensions, and visit any website. The background will turn light blue. That is your content script running. You can use this same approach to highlight text, hide elements, add buttons, or read information from the page and send it to your background script.
One important limit: content scripts cannot access files on your computer. They can only interact with the web page and send messages to your background script, which has more power.
Storing data so it persists between sessions
If your extension needs to remember something — a setting, a list of blocked words, a count of how many times you clicked the button — you use chrome.storage. Update your popup.js to this:
document.getElementById("myButton").addEventListener("click", function() { chrome.storage.local.get("clickCount", function(result) { let count = (result.clickCount || 0) + 1; chrome.storage.local.set({clickCount: count}); alert("Clicks: " + count); }); });
Also add this to your manifest.json permissions array: "storage". Now when you click the button, it will count how many times you have clicked it, and the count will survive even if you close and reopen Chrome.
The data is stored locally on your computer. Chrome does not sync it to your account, and no website can read it. It is private to your extension.
Common things extensions do and how to build them
Once you understand the three basic pieces — manifest, popup, and content script — you can build most straightforward extensions. Here are patterns for things people often want:
Highlight certain words on every page: In your content script, loop through the page text and wrap matching words in a span with a background color. Use a regular expression to find the words, and be careful not to break HTML tags.
Add a button to the page itself: In your content script, create a new button element with document.createElement, style it with CSS, and append it to the page. Attach a click listener to it.
Run code when you visit a specific website: In your manifest, change the "matches" pattern from "<all_urls>" to something like "https://example.com/*". Your content script will only run on that site.
Send data from the page to your popup: In your content script, use chrome.runtime.sendMessage to send data to your background script. In your popup, use chrome.tabs.query and chrome.tabs.sendMessage to ask the current tab for information.
Permissions and what your extension can and cannot do
Chrome asks you to declare what your extension needs to do. In the manifest, the "permissions" array lists these. Common ones are "scripting" (to run code on pages), "activeTab" (to access the current tab), "storage" (to save data), and "webRequest" (to see network traffic). Only request permissions you actually use.
Your extension cannot read files on your computer without the "downloads" permission, and even then it can only access files you have downloaded. It cannot access your passwords or credit cards. It cannot see what you type in password fields. It cannot run on Chrome's own pages like chrome://extensions or the Chrome Web Store.
When you load an extension in Developer mode, Chrome does not enforce these restrictions as strictly as it does for extensions from the Web Store. But it is good practice to only request what you need, because it makes your code clearer and safer.
Debugging and fixing problems
When something does not work, open the Chrome DevTools. For your popup, right-click the popup window and select "Inspect". For a content script, go to any page where it should run, press F12 to open DevTools, and look at the Console tab. Any errors will appear there.
If your extension does not load at all, check the manifest.json for typos. JSON is strict about commas and quotes. If you see an error message on the chrome://extensions page, read it carefully — it usually points to the exact line that is wrong.
Use console.log to print messages and track what your code is doing. In your popup.js, add console.log statements before and after key lines. Then open the popup inspector and look at the Console tab to see what printed. This is the fastest way to find bugs.
If your extension works sometimes but not always, the problem is usually timing. Your content script might run before the page finishes loading, or a message might arrive before the listener is set up. Add delays with setTimeout or wait for the page to load with document.addEventListener("DOMContentLoaded", ...).
Frequently Asked Questions
Can I use a library like jQuery or React in my extension?
Yes. read the library file, put it in your extension folder, and load it in your HTML before your own script. In popup.html, add <script src="jquery.js"></script> before <script src="popup.js"></script>. The same works for content scripts — list the library first in your manifest's "js" array.
How do I make my extension run on a specific website only?
In your manifest, change the "matches" pattern in content_scripts. Instead of "<all_urls>", use something like "https://twitter.com/*" or "https://mail.google.com/*". The asterisk means "any path on that domain". You can list multiple patterns in an array if you want it to run on several sites.
Can I share my extension with other people?
Yes, but not through the Chrome Web Store without review. You can share the folder with others, and they can load it in Developer mode the same way you did. For wider distribution, you would need to publish it to the Chrome Web Store, which requires a developer account and review by Google.
What happens to my extension when I close Chrome?
Your extension stays installed. The next time you open Chrome, it loads automatically. Any data you stored with chrome.storage persists. The only thing that resets is the popup window — it closes when you close Chrome and reopens when you click the icon again.
Can my extension access websites that require login?
Yes. Your content script runs with the same permissions as you do in that tab. If you are logged into a website, your content script can read the page and interact with it. But it cannot steal your password — that is stored in Chrome's password manager, which your extension cannot read.