Chrome Extension Beginners Guide | Build Your First Extension

Content Brief Summary

This guide explains exactly how to build a Google Chrome Extension from scratch, even if you've never written one before. It covers the core files you need, how to structure your project, and how to go from a blank folder to a working extension loaded in your browser. Whether you want to build a productivity tool, a simple UI tweak, or something more ambitious, this is where you start.

Introduction

You've probably used a Chrome Extension today without thinking twice — an ad blocker, a password manager, a tab organizer. And at some point, you may have thought: could I build one of those?

The answer is yes, and it's more achievable than most people expect.

Chrome Extensions are built with HTML, CSS, and JavaScript, the same technologies that power websites. You don't need a special framework, a backend server, or years of experience. What you do need is a clear understanding of how extensions are structured, and a step-by-step path through the parts that trip up beginners.

This Chrome Extension beginners' guide gives you exactly that. By the end, you'll have a working extension installed in your own browser and the knowledge to build on it.

What Is A Chrome Extension, Really?

Before writing a single line of code, it helps to understand what you're actually building.

A Chrome Extension is a small software program that runs inside the Google Chrome browser. It can interact with web pages, modify their content, add UI elements to Chrome itself (such as toolbar buttons), or run background logic that doesn't depend on any particular page.

Extensions have access to Chrome APIs that regular web pages don't have, like tabs, bookmarks, notifications, and storage. That's what gives them their power.

There are several types of extensions, but most beginners start with one of two things:

1. A pop-up — a small window that appears when you click an icon in the toolbar
2. A content script — code that runs on a web page and can read or change what's there

This guide focuses on building a pop-up-based extension first, since it's the clearest starting point.

What You Need Before You Start

You don't need much. Here's the list:

• 1. A text editor — VS Code is the most popular choice, but any editor works
• 2. Google Chrome — obviously
• 3. Basic HTML, CSS, and JavaScript knowledge — you don't need to be an expert, but you should know what a <div> is, how to write a function, and how CSS selectors work

That's it. No npm, no build tools, no frameworks required for a basic extension.

Understanding the Core Files

Every Chrome Extension starts with a folder. Inside that folder, you need at a minimum:

1. manifest.json — the control file that tells Chrome everything about your extension
2. An HTML file — for the pop-up interface (if you're building one)
3. A JavaScript file — for your extension's logic
4. An icon — at least one image file Chrome can use as the toolbar icon

The manifest.json is the most important file. Chrome reads it first and uses it to understand what your extension does and what permissions it needs.

Step 1: Create Your Project Folder

Start by creating a new folder on your computer. Call it something like my-first-extension. Everything you build goes inside this folder.

Open it in your text editor. You're going to create four files:

• manifest.json
• popup.html
• popup.js
• An icon image (PNG format, 16×16 or 48×48 pixels)

You can use a simple square PNG as your icon for now — it doesn't need to be polished to test the extension.

Step 2: Write the Manifest File

The manifest.json file is a JSON document that defines your extension's identity and behavior. Here's a minimal example using Manifest V3 (the current standard):

{
  "manifest_version": 3,
  "name": "My First Extension",
  "version": "1.0",
  "description": "A simple Chrome extension built from scratch.",
  "action": {
    "default_popup": "popup.html",
    "default_icon": "icon.png"
  }
}

Let's break that down:

• "manifest_version": 3 — tells Chrome you're using the current MV3 standard (not the older MV2)
• "name" — the display name shown in Chrome's extension manager
• "version" — your extension's version number (used when you update it)
• "description" — a summary users see in the Chrome Web Store
• "action" — defines what happens when someone clicks your toolbar icon; here it opens popup.html

Save this file as manifest.json inside your project folder.

Step 3: Build the Popup HTML

Your popup is just an HTML page. Chrome opens it in a small window when the user clicks your extension icon.

Here's a simple example:

<body>
  <h2>Hello from my extension!</h2>
  <p>Click the button below.</p>
  <button id="myButton">Click me</button>
  <script src="popup.js"></script>
</body>

Notice the <script src="popup.js"> at the bottom. Chrome's Content Security Policy doesn't allow inline <script> tags in extension HTML files, so all JavaScript must live in a separate file.

Save this as popup.html.

Step 4: Write Your JavaScript Logic

Now create popup.js. This is where your extension does things. A simple example that responds to a button click:

document.addEventListener('DOMContentLoaded', function () {
  const button = document.getElementById('myButton');

  button.addEventListener('click', function () {
    button.textContent = 'You clicked it!';
    button.style.background = '#34a853';
  });
});

When the user clicks the button, the text changes and the button turns green. It's small, but it confirms your extension is working and your JS file is connected.

Save this as popup.js.

Step 5: Load Your Extension in Chrome

Here's where things get satisfying. You're going to install your unfinished extension directly in your browser:

• Open Chrome and go to chrome://extensions
• In the top right, toggle on Developer mode
• Click Load unpacked
• Select your project folder

Your extension icon should appear in the Chrome toolbar. Click it. Your popup opens.

If something doesn't show up, Chrome will usually display an error message on the extensions page that points you toward the problem, most often a typo in manifest.json.

Step 6: Use Chrome's Developer Tools to Debug

When your pop-up is open, you can right-click inside it and choose Inspect. This opens Chrome's DevTools for the popup context, where you can:

• See console errors
• Test JavaScript in the console
• Inspect and modify the popup's HTML and styles in real time

This is your primary debugging tool. Get comfortable with it early — it saves a lot of frustration.

Going Further: Content Scripts

Once you've got a popup working, the next step most developers take is writing a content script code that runs on web pages and can read or modify their content.

You declare content scripts in your manifest.json like this:

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

This tells Chrome to inject content.js into every web page the user visits. Your script can then interact with the page's DOM, change colors, extract text, add new elements, and more.

Content scripts run in an isolated environment, which means they can read and modify the page's DOM but can't directly access JavaScript variables defined on the page itself. Chrome's design keeps things sandboxed for security.

Permissions: Ask Only for What You Need

One of the most common mistakes beginners make is adding more permissions to manifest.json than the extension actually needs. Chrome warns users about permissions during installation, so a long permission list can reduce trust and installation rates.

Common permissions include:

• "storage" — lets your extension save and read data using Chrome's storage API
• "tabs" — gives access to tab URLs and metadata
• "activeTab" — safer alternative to "tabs"; grants access only to the current tab when the user interacts with your extension

When you publish to the Chrome Web Store, reviewers also scrutinize permissions. Only request what your extension genuinely uses.

Manifest V3: Why It Matters

If you're following older tutorials, they might reference Manifest V2 (MV2). Google has been phasing out MV2 support and has moved to Manifest V3 (MV3) as the required standard for new Chrome Web Store submissions.

The key differences that affect beginners:

• Background pages (MV2) are replaced by service workers (MV3)
• chrome.webRequest blocking rules work differently in MV3
• Remotely hosted code is no longer allowed

For a first extension, these differences mostly don't matter, as the popup and content script patterns work the same way. But if you start reading older guides and hit confusing errors, the MV2/MV3 difference is often the cause.

Packaging and Publishing (When You're Ready)

When your extension is ready to share with the world, you'll publish it through the Chrome Web Store Developer Dashboard. The process involves:

• Zipping your project folder
• Creating a developer account (there's a one-time $5 registration fee)
• Uploading the zip, adding store listing details, screenshots, and an icon
• Submitting for review

Google's review process typically takes a few days for new extensions. Extensions with broader permissions or access to sensitive data take longer.

If you want to explore what's already on the store, to get inspiration, or understand the landscape, webstoreextensions.com is a useful resource for discovering and comparing extensions across categories.

Common Beginner Mistakes (and How to Avoid Them)

Using inline scripts in HTML

Chrome blocks them by default. Always use an external .js file.

Typos in manifest.json

JSON is unforgiving. A missing comma or a mismatched bracket will stop your extension from loading entirely. Use a JSON validator if you're unsure.

Forgetting Developer Mode

Your extension won't load without it enabled on chrome://extensions.

Using alert() in your popup

alert() doesn't work inside Chrome Extension popups. Use console.log() or update the DOM to display messages.

Not reloading after changes

After editing your files, you need to click the reload button (↺) next to your extension on chrome://extensions for changes to take effect. The popup doesn't hot-reload automatically.

Conclusion

Building a Chrome Extension is one of the most rewarding projects a web developer can take on at any level. The gap between a blank folder and a working, installable browser tool is smaller than it looks, and every extension you build teaches you something new about how browsers, APIs, and user interfaces interact.

Start with the popup. Get it loading. Then experiment. Add a content script. Try the storage API. Browse the Chrome Extensions documentation and pick an API that interests you.

The best way to learn is to build something you'd actually want to use.

FAQ

Do I need to know a framework like React to build a Chrome Extension? No. A basic extension needs only HTML, CSS, and vanilla JavaScript. Frameworks can be useful for complex extensions with multiple views, but they're not required and add build complexity.

What is the difference between Manifest V2 and Manifest V3? MV3 is the current standard required by the Chrome Web Store. The biggest changes affect background scripts (now service workers) and network request blocking. For beginners building popup or content script extensions, the practical differences are minimal.

Can I build a Chrome Extension without paying anything? Yes, for personal use. Publishing to the Chrome Web Store requires a one-time $5 developer registration fee, but you can build, test, and use extensions locally for free.

How long does it take to build a basic Chrome Extension? A working popup extension can be built in under an hour if you're comfortable with HTML and JavaScript. More complex extensions with content scripts, storage, and API integrations take longer, depending on what they do.

Can my extension interact with any website?

With the right permissions declared in your manifest, yes. Content scripts can be injected into specific URLs or all URLs. Always request only the access your extension genuinely needs.

What happens after I submit to the Chrome Web Store?

Google reviews your submission, which can take anywhere from a few days to a couple of weeks. They check for policy compliance, permission justification, and functionality. You'll be notified of approval or any required changes.