sodcalculator

10 Tech How-To

How to Make a Simple Chrome Extension

Guide 10-54930 · Updated · Step by step

This guide walks you through building a basic Chrome extension from scratch—one that adds a custom toolbar button and displays a popup when clicked. You’ll create a working extension in about 15 minutes using just a few text files, no prior coding experience required.

What You’ll Need

  • A computer running Windows, macOS, or Linux
  • Google Chrome browser (any recent version)
  • A text editor (Notepad, TextEdit, VS Code, or any plain-text editor)
  • Basic familiarity with file folders and saving files

Step-by-Step

  1. Create a project folder. Make a new folder on your desktop named my-extension. This will hold all your extension files.
  2. Create the manifest file. Inside the folder, create a new file named manifest.json (make sure it’s not manifest.json.txt). Open it in your text editor.
  3. Write the manifest. Copy and paste the following code into the file, then save it:
    {
      "manifest_version": 3,
      "name": "My Simple Extension",
      "version": "1.0",
      "action": {
        "default_popup": "popup.html",
        "default_title": "Click me"
      }
    }

    This tells Chrome the extension’s name, version, and that it should show a popup when the toolbar icon is clicked.

  4. Create the popup HTML file. In the same folder, create a new file named popup.html. Open it and paste the following basic HTML:
    <!DOCTYPE html>
    <html>
    <head>
      <meta charset="utf-8">
      <style>
        body { width: 200px; font-family: Arial, sans-serif; }
        h1 { font-size: 16px; }
      </style>
    </head>
    <body>
      <h1>Hello, Extension!</h1>
      <p>This is my first Chrome extension.</p>
    </body>
    </html>

    Save the file.

  5. Open Chrome’s extension page. In Chrome, go to the address bar, type chrome://extensions, and press Enter. You’ll see a list of installed extensions.
  6. Enable Developer Mode. In the top-right corner of the extensions page, toggle the switch labeled Developer mode to the ON position. This reveals extra buttons.
  7. Load the extension. Click the Load unpacked button that appears. In the file picker, navigate to your my-extension folder and select it. Click Select Folder.
  8. Verify it works. Your extension should now appear in the list, and its icon will show up in the toolbar (top-right, near the address bar). Click the icon to see your popup.
  9. Make changes and reload. Edit popup.html to change the text, then save. Go back to chrome://extensions and click the circular arrow (reload) icon on your extension card to apply the changes.
  10. Pin the extension (optional). Click the puzzle piece icon in the toolbar to see all extensions, then click the pin icon next to yours to keep it visible.

Common Mistakes

  • Wrong file extension: Saving the manifest as manifest.json.txt instead of manifest.json is the most frequent error. Make sure your text editor isn’t appending .txt automatically.
  • Missing or invalid JSON: A missing comma, an extra quote, or a trailing comma in manifest.json will cause Chrome to reject the extension. Use a JSON validator if you’re unsure.
  • Forgetting to reload: After editing files, you must click the reload button in chrome://extensions (or press Ctrl+R / Cmd+R on that page) for changes to take effect.
  • Using the wrong manifest version: Chrome now requires manifest_version 3. Using version 2 will show an error.

Tips

  • Use a dedicated folder for each extension—never mix files from different projects.
  • Keep your popup HTML simple; Chrome ignores external JavaScript unless you declare it properly in the manifest.
  • If you plan to add more features later, study the official Chrome extension documentation for details on permissions, background scripts, and content scripts.
  • Test your extension in a fresh Chrome profile (create a new user) to avoid conflicts with other extensions.
  • Use Chrome’s built-in developer tools (right-click on the popup and select Inspect) to debug any JavaScript you add later.

Troubleshooting

  • Extension doesn’t appear in the toolbar: Click the puzzle piece icon to see all extensions; yours might be hidden. If it’s not there at all, go back to chrome://extensions and check for an error message on the card.
  • Error: “Manifest file is missing or unreadable”: Ensure the file is named exactly manifest.json and is in the top level of the folder you selected.
  • Error: “Could not load manifest”: Open manifest.json in a text editor and check for typos. Use a JSON linter online to validate the content.
  • Popup shows blank: Make sure popup.html is in the same folder as the manifest and that the filename matches exactly (case-sensitive on some systems). Try reloading the extension.
  • Changes don’t appear: After editing any file, click the reload icon on the extension card. Also, close and reopen the popup if it was open.
  • Chrome says “This extension is not secure”: This is normal for unpacked extensions in developer mode. It doesn’t affect functionality.

Frequently Asked Questions

Do I need to know JavaScript to make a simple extension?

No. The basic extension described here only uses HTML and a manifest file. JavaScript is only needed for interactive features like buttons that change web pages or respond to user input.

Can I distribute this extension to others?

Yes, but for public distribution you’ll need to package it as a .crx file and publish it to the Chrome Web Store. That requires a developer account and a review process.

Why is Developer Mode required?

Developer Mode allows Chrome to load unpacked extensions from your local disk, which is meant for testing and development. Regular users don’t need it because they install from the Web Store.

How do I add an icon to my extension?

Add an icons field in the manifest, specifying PNG files of sizes 16, 48, and 128 pixels. For example: "icons": { "16": "icon16.png", "48": "icon48.png", "128": "icon128.png" }.

Can I make the extension work on specific websites only?

Yes, you’d need to add permissions and content scripts in the manifest. That goes beyond this simple example, but the official documentation explains how to target URLs.

What if I want to change the popup’s width or height?

You can set the width and height in the CSS within popup.html. Chrome respects the width and height properties on the body element.

Related

General steps for current mainstream versions; menus can differ by device and version. See the disclaimer or report an error.

More in this bed

The whole Tech How-To bed →