What you need to build a Chrome extension

A Chrome extension is a small program that adds features to your browser. You can build one with three things: a text editor (like Notepad or VS Code), basic knowledge of HTML, CSS, and JavaScript, and the Chrome browser itself. You do not need special software or permission from Google to start — you can test your extension on your own computer before deciding what to do with it.

The simplest extensions are just a few files in a folder. Chrome reads a file called manifest.json that tells it what your extension does, then loads the HTML, CSS, and JavaScript files that make it work. If you have never written code before, start with something very small — a button that changes the color of text on a page, or a counter that tracks how many times you click something.

Key Takeaways

  • Every Chrome extension needs a manifest.json file that describes what it does, what permissions it needs, and which files to load.
  • You write the extension code in HTML, CSS, and JavaScript, then test it in Chrome by loading the folder as an unpacked extension.
  • Chrome's developer tools let you see errors and debug your code while you test, so you can fix problems before sharing it.
  • Publishing to the Chrome Web Store requires a Google account and a one-time $5 fee, but you can keep your extension private and just use it yourself.

The manifest.json file that controls everything

The manifest.json file is the instruction manual for your extension. Chrome reads it first and uses it to understand what your extension is called, what it does, which files to load, and what permissions it needs. Without this file, Chrome will not recognize your extension at all.

A basic manifest for a simple extension looks like this: it starts with a version number (usually "3" for modern Chrome extensions), gives your extension a name and description, lists the files Chrome should load, and declares any permissions you need. If your extension changes the content of web pages, you need the content_scripts permission. If it adds a button to the toolbar, you need the action field. If it stores data, you need storage. Chrome will block your extension from running if you use a feature without declaring the permission first.

Creating the files your extension needs

Start by making a new folder on your computer — call it something like "my-first-extension". Inside that folder, create a manifest.json file and save it as plain text. Then create an HTML file (usually called popup.html or content.html depending on what your extension does), a CSS file for styling, and a JavaScript file for the logic that makes things happen.

The HTML file is where you write the visible part of your extension — buttons, text boxes, lists, whatever the user sees. The CSS file makes it look good. The JavaScript file contains the code that runs when someone clicks a button or when a page loads. For a very simple extension, you might only need one or two of these files, but the manifest.json is always required.

Save all these files in the same folder. Do not put them in subfolders unless your manifest.json tells Chrome exactly where to find them. Chrome looks for files relative to the manifest, so if you move a file and forget to update the manifest, your extension will break.

Loading your extension into Chrome to test it

Once you have your files ready, open Chrome and go to chrome://extensions in the address bar. This page shows all your installed extensions and has a button called "Load unpacked" in the top left. Click that button, then navigate to the folder where you saved your extension files and select it. Chrome will load your extension immediately and show it on the extensions page.

If Chrome shows an error message, read it carefully — it usually tells you exactly what is wrong. Common problems are a missing manifest.json file, a typo in the manifest, or a file path that does not match what you wrote. Fix the error, then click the refresh icon next to your extension on the extensions page. Chrome will reload it and try again.

While you are testing, keep the extensions page open in one tab and the web page you are testing in another. When you make changes to your code, save the file, then click the refresh button on the extensions page. This reloads your extension with the new code so you can see what changed.

Using Chrome's developer tools to find and fix problems

When something does not work the way you expected, Chrome's developer tools show you what went wrong. Right-click on your extension's button or popup and select "Inspect" — this opens the developer tools and shows you the HTML, CSS, and JavaScript for that part of your extension. The "Console" tab shows error messages in red, which tell you exactly which line of code has a problem and what the problem is.

If your extension runs code on web pages (called a content script), you need to inspect the page itself, not the extension. Open the developer tools on any web page with Ctrl+Shift+I (or Cmd+Option+I on Mac), go to the Console tab, and look for messages from your extension. You can also add console.log() statements in your JavaScript code to print out values and see what your code is actually doing at each step.

Deciding whether to publish or keep it private

You can use your extension just on your own computer without ever publishing it. The unpacked extension you loaded will stay in Chrome as long as you do not delete the folder. This is fine if you built it for yourself or to learn how extensions work.

If you want to share it with others or publish it officially, you can upload it to the Chrome Web Store. This requires a Google account and a one-time $5 developer fee. Google reviews your extension to make sure it does not steal data, inject ads, or do anything deceptive. The review usually takes a few hours to a few days. Once it is approved, anyone can find it in the Web Store and install it.

You do not have to publish to the Web Store to share your extension with others. You can give someone the folder and they can load it as an unpacked extension on their own computer using the same steps you used. This is common for extensions made for a small group of people or for learning purposes.

Common mistakes to avoid when building your first extension

The most common mistake is forgetting to declare permissions in the manifest.json. If your extension needs to read the current tab's URL, store data, or change what appears on a web page, you must list those permissions. Chrome will silently block your code from running if you do not, and you will spend hours wondering why nothing works.

Another frequent problem is using outdated code examples from the internet. Chrome extensions changed significantly in 2023 when Google moved from Manifest V2 to Manifest V3. If you find a tutorial that shows "manifest_version": 2, that code is old and will not work in modern Chrome. Look for examples that show "manifest_version": 3 instead.

A third mistake is not testing on different pages. Your extension might work perfectly on one website but break on another because of how that site's code is written. Test on at least a few different pages before you consider it done. Also test with the developer tools open so you catch error messages early.

Frequently Asked Questions

Do I need to know how to code to build a Chrome extension?

You need basic knowledge of HTML, CSS, and JavaScript. If you have never written code, you can learn the basics in a few weeks using free resources like freeCodeCamp or Codecademy. Start with something very simple — a button that shows a message when clicked — and build from there.

Can I build an extension that works on all browsers, not just Chrome?

Most of the code is the same, but each browser has slightly different rules. Firefox, Edge, and Safari all use a similar extension format, so you can often reuse most of your code. You will need to test on each browser and may need to adjust the manifest.json file for each one.

What if I want my extension to do something on every website I visit?

Use a content script in your manifest.json. This tells Chrome to run your JavaScript code on every page that matches a pattern you specify — for example, all pages that start with "https://". Be careful with permissions here: if your extension can see every page you visit, that is powerful and users will want to know why.

How do I make my extension show a button in the Chrome toolbar?

Add an "action" field to your manifest.json and point it to an icon image file. You can also add a popup.html file that Chrome will show when someone clicks the button. The manifest tells Chrome which HTML file to display and how big the popup should be.

Can I sell my extension or charge people to use it?

You can publish it on the Chrome Web Store and set a price. Google takes a percentage and handles payments. You can also keep it free but ask for donations, or charge for a more advanced version while offering a basic version for free. Check the Web Store policies for what is allowed.