How to Make Your First Chrome Extension with Manifest V3 – ██FR█████ █INTELL███████████

This content originally appeared on DEV Community and was authored by keith mark

Have you ever wanted to build your own Chrome extension? Maybe something small that adds a cool feature to your browser or automates a task? You’re in the right place.

In this guide, you’ll build a simple Chrome extension using Manifest V3 that changes the background color of a webpage. This tutorial assumes no prior experience with Chrome Extensions, so we’ll walk through everything step-by-step.

By the end of this tutorial, you’ll learn:

What a Chrome Extension is
How Manifest V3 works
How to use JavaScript to interact with web pages
How to install and test your extension locally

1. What is a Chrome Extension?

A Chrome extension is a small software program that customizes the browsing experience. Extensions can add new features to Chrome, modify web pages, automate repetitive tasks, or integrate with other services. They’re built using web technologies like HTML, CSS, and JavaScript, and are distributed through the Chrome Web Store or loaded locally for development.

Extensions are made up of several files:

manifest.json: The configuration file that tells Chrome about your extension.
HTML/CSS/JS files: For the popup UI and logic.
Background scripts: For persistent logic or event handling.
Icons: For branding in the toolbar and Chrome Web Store.

2. Understanding Manifest V3

The manifest is the heart of every Chrome extension. Manifest V3 (MV3) is the latest version, designed to improve security, privacy, and performance. MV3 introduces a new way to handle background logic (service workers), stricter permissions, and a more declarative approach to extension capabilities.

A basic manifest.json for our extension looks like this:

{
  "manifest_version": 3,
  "name": "ColorSwap",
  "version": "1.0",
  "description": "Change the background color of the current tab to light blue.",
  "permissions": ["scripting", "activeTab"],
  "host_permissions": ["<all_urls>"],
  "background": {
    "service_worker": "background.js"
  },
  "action": {
    "default_popup": "popup.html",
    "default_title": "ColorSwap"
  }
}

Key fields explained:

manifest_version: Must be 3 for new extensions.
name, version, description: Basic metadata.
permissions: What the extension can access. scripting lets us inject code, activeTab allows access to the current tab.
host_permissions: Specifies which sites the extension can interact with. "<all_urls>" means all sites.
background: Points to a service worker script (background.js). For this extension, it can be empty.
action: Defines the popup UI and its title.

3. Setting Up Your Project Folder

Create a new folder for your extension, e.g., ColorSwap. Inside, create these files:

ColorSwap/
├── manifest.json
├── popup.html
├── popup.js
├── background.js

The icons/ folder and icon files are optional for development.

4. Building the Popup UI (popup.html)

The popup is the small window that appears when you click your extension’s icon. Here’s a simple example:

<!DOCTYPE html>
<html>
  <head>
    <title>ColorSwap</title>
    <style>
      body { min-width: 200px; font-family: Arial, sans-serif; }
      button { margin-top: 10px; padding: 8px 16px; font-size: 16px; }
    </style>
  </head>
  <body>
    <h2>ColorSwap</h2>
    <button id="change-bg">Change Background</button>
    <script src="popup.js"></script>
  </body>
</html>

This creates a simple UI with a title and a button.

5. Adding JavaScript Logic (popup.js)

The JavaScript file handles the button click and changes the background color of the current tab. Here’s the code:

// Wait for the DOM to load
window.addEventListener('DOMContentLoaded', function () {
  const btn = document.getElementById('change-bg');
  btn.addEventListener('click', async function () {
    // Get the active tab
    let [tab] = await chrome.tabs.query({ active: true, currentWindow: true });
    // Inject code to change background color
    chrome.scripting.executeScript({
      target: { tabId: tab.id },
      func: () => {
        document.body.style.backgroundColor = '#ADD8E6';
        document.documentElement.style.backgroundColor = '#ADD8E6';
        document.body.style.backgroundImage = 'none';
        document.documentElement.style.backgroundImage = 'none';
      }
    });
  });
});

How it works:

Waits for the popup to load.
Adds a click event to the button.
Uses chrome.tabs.query to get the current tab.
Uses chrome.scripting.executeScript to inject a function that changes the background color and removes background images for better compatibility.

6. The Background Script (background.js)

For Manifest V3, background scripts are now service workers. In this extension, background.js can be empty or just a placeholder comment:

// background.js - Service worker placeholder for ColorSwap extension

7. Permissions and Security

Chrome extensions require explicit permissions for everything they do. This is for user safety. Our extension uses:

scripting: To inject JavaScript into web pages.
activeTab: To access the currently active tab when the popup is used.
host_permissions: To specify which sites the extension can interact with. Using "<all_urls>" allows it to work everywhere, but you can restrict this for more privacy.

Always use the minimum permissions needed for your extension’s functionality.

8. Loading and Testing Your Extension

Open Chrome and go to chrome://extensions
Enable “Developer mode” (toggle in the top right)
Click “Load unpacked” and select your extension folder
The extension should appear in your toolbar
Go to any site (e.g., https://www.google.com/)
Click the ColorSwap extension icon to open the popup
Click “Change Background” — the page background should turn light blue (#ADD8E6)

Troubleshooting:

If nothing happens, check the permissions in your manifest.
Some sites (like the Chrome Web Store) block script injection for security reasons.
Check for errors in the Chrome extension page (click “Errors” under your extension).

9. How It Works: Under the Hood

When you click the extension icon, Chrome opens the popup.html file. The popup.js script waits for you to click the button, then:

Finds the active tab
Injects a script into that tab
The injected script sets the background color and removes background images on both <body> and <html> elements

This approach works on most sites, but some with strict Content Security Policies (CSP) or special layouts may require more advanced techniques.

10. Next Steps and Ideas for Improvement

Now that you have a working extension, here are some ideas to take it further:

Let users pick their own color: Add a color input to the popup and use that value in the injected script.
Save user preferences: Use chrome.storage to remember the user’s chosen color.
Add a keyboard shortcut: Use the commands API to let users trigger the extension with a key combo.
Add an icon: Create an icons/ folder and add a 128×128 PNG for branding.
Publish to the Chrome Web Store: Follow the official publishing guide to share your extension with the world.

11. Resources

12. Conclusion

You’ve just built and tested your first Chrome extension using Manifest V3! You learned how to structure an extension, use the manifest, interact with web pages, and test your work. With these basics, you can now explore more advanced features and build powerful tools for your browser.

Happy coding!

This content originally appeared on DEV Community and was authored by keith mark