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 special software or a degree in computer science — you need a text editor, a folder on your computer, and knowledge of three languages that work together: HTML (for structure), CSS (for appearance), and JavaScript (for behavior). If you have written any HTML before, you already know the hardest part.
The smallest working extension requires four files: a manifest.json file that tells Chrome what your extension does, an HTML file for any popup or settings page, a CSS file for styling, and a JavaScript file for the extension's logic. You can build these in any text editor — Notepad, Visual Studio Code, or even the default editor on your computer works fine. The only Chrome-specific tool you need is the browser itself.
Before you start, decide what your extension will do. The clearest first projects are simple ones: a button that changes the background color of every webpage, a tool that counts words on the current page, or a sidebar that shows the time. Avoid trying to build something that requires connecting to other websites or storing large amounts of data — those add complexity that can derail a first project.
Key Takeaways
- Every Chrome extension needs a manifest.json file that describes what it does, which permissions it needs, and what files it uses.
- You write extensions in HTML, CSS, and JavaScript — the same languages used to build websites.
- You test your extension by loading it directly into Chrome from a folder on your computer, without uploading it anywhere.
- The Chrome Web Store requires a developer account and a one-time $5 fee, but you can test and use your extension for free before publishing.
- Most beginner extensions fail because they ask for too many permissions or try to do too much — start with one clear feature.
Setting up your extension folder and manifest file
Create a new folder on your computer and name it something clear, like my-first-extension. Inside that folder, create a file called manifest.json. This file is the instruction manual for your extension — it tells Chrome the extension's name, version, what it does, which files to load, and what permissions it needs.
Open manifest.json in your text editor and paste this code:
{ "manifest_version": 3, "name": "My First Extension", "version": "1.0", "description": "A simple extension that does one thing", "permissions": ["activeTab", "scripting"], "action": { "default_popup": "popup.html", "default_title": "Click me" } }
The manifest_version must be 3 — that is the current standard Chrome uses. The name and description are what users see. The permissions section tells Chrome what your extension is allowed to do. "activeTab" means it can see the current webpage, and "scripting" means it can run JavaScript on that page. The action section points to your popup.html file, which is the window that opens when someone clicks your extension's button.
Creating the popup, styling, and script files
In the same folder, create a file called popup.html. This is the small window that appears when a user clicks your extension's icon. Paste this code:
<!DOCTYPE html> <html> <head> <link rel="stylesheet" href="styles.css"> </head> <body> <h1>Hello</h1> <button id="myButton">Click me</button> <script src="popup.js"></script> </body> </html>
Now create styles.css in the same folder to make the popup look clean:
body { width: 300px; padding: 10px; font-family: Arial, sans-serif; } button { padding: 10px 20px; background-color: #4CAF50; color: white; border: none; cursor: pointer; } button:hover { background-color: #45a049; }
Finally, create popup.js to make the button do something:
document.getElementById("myButton").addEventListener("click", function() { alert("Button clicked!"); });
You now have all four files your extension needs. Your folder should contain: manifest.json, popup.html, styles.css, and popup.js.
Loading 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 Developer mode by clicking the toggle.
Once Developer mode is on, three new buttons appear at the top left: "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 your extension immediately.
You should now see your extension listed on the extensions page with its name, version, and description. In the top right corner of Chrome, next to the address bar, you will see a small puzzle-piece icon. Click it, and you should see your extension listed. Click your extension's name, and the popup window will open showing the button you created. Click the button — it should show an alert that says "Button clicked!"
If something does not work, go back to the extensions page. You will see error messages in red text under your extension's name. Read the error carefully — it usually tells you exactly which file has the problem and what line the error is on.
Making your extension do something useful
The alert button is a proof of concept. To make your extension actually change webpages, you need a content script — a JavaScript file that runs on the pages you visit, not just in the popup.
Create a new file called content.js in your extension folder. Paste this code, which changes the background color of every webpage to light blue:
document.body.style.backgroundColor = "lightblue";
Now update your manifest.json to tell Chrome to run this script on webpages. Change the manifest to this:
{ "manifest_version": 3, "name": "My First Extension", "version": "1.0", "description": "A simple extension that does one thing", "permissions": ["activeTab", "scripting"], "content_scripts": [ { "matches": ["<all_urls>"], "js": ["content.js"] } ], "action": { "default_popup": "popup.html", "default_title": "Click me" } }
The content_scripts section tells Chrome to run content.js on every webpage (<all_urls>). Go back to chrome://extensions, find your extension, and click the refresh icon. Now visit any website — the background should turn light blue. Your extension is working on live webpages.
Publishing to the Chrome Web Store
Once your extension works the way you want, you can publish it so other people can install it. Go to the Chrome Web Store developer dashboard at https://chrome.google.com/webstore/devconsole. You will need a Google account.
The first time you use the developer dashboard, you must pay a one-time $5 developer registration fee. After that, you can upload as many extensions as you want. Click "Create new item" and upload a .zip file of your extension folder. You will need to provide a 128x128 pixel icon image, a short description, and screenshots showing what your extension does.
Chrome will review your extension to make sure it does not contain malware or violate their policies. This usually takes a few hours to a few days. Once approved, your extension appears in the Chrome Web Store and anyone can install it by searching for its name.
You do not have to publish to the Chrome Web Store. Many people build extensions just for themselves or to share with friends. You can use your extension indefinitely by keeping it loaded in Developer mode on your own computer.
Common mistakes and how to avoid them
The most common mistake is asking for too many permissions. If your extension only needs to change the color of text, do not ask for permission to access all data on all websites. Users will not trust an extension that asks for more power than it needs. Start with the smallest set of permissions that makes your extension work, and add more only if you have a real reason.
The second mistake is forgetting to refresh your extension after making changes. Every time you edit a file, go back to chrome://extensions and click the refresh icon next to your extension's name. Without refreshing, Chrome will still be running the old version of your code.
The third mistake is trying to do too much in your first extension. A button that changes one color is a complete, working extension. A tool that counts words on a page is a complete, working extension. A sidebar that shows the weather is a complete, working extension. Do not try to build all three at once — finish one, then move on to the next.
Frequently Asked Questions
Can I use JavaScript libraries like jQuery in my extension?
Yes. Download the library file, put it in your extension folder, and link to it in your HTML file the same way you would on a website. For example, add <script src="jquery.js"></script> before your own script tags. Many developers use libraries to make their code shorter and easier to read.
What is the difference between a popup and a content script?
A popup is the small window that opens when you click your extension's icon — it is separate from the webpage. A content script runs directly on the webpage itself and can change what the user sees. Most extensions use both: the content script does the real work, and the popup gives the user controls.
How do I make my extension work only on certain websites?
In manifest.json, change the "matches" line in content_scripts. Instead of "<all_urls>", write the website you want. For example, "matches": ["https://www.youtube.com/*"] makes your extension run only on YouTube. You can list multiple websites by separating them with commas.
Can I store data that persists between browser sessions?
Yes, using Chrome's storage API. Add "storage" to your permissions in manifest.json, then use chrome.storage.local.set() and chrome.storage.local.get() in your JavaScript to save and load data. This is how extensions remember user settings even after the browser closes.
What happens if my extension breaks after a Chrome update?
Chrome updates happen regularly, and sometimes they change how extensions work. If your extension stops working, check the error messages on chrome://extensions. The error message usually points you to the exact line of code that broke. You can also check the Chrome extension documentation to see if the API you used changed.