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
- Create a project folder. Make a new folder on your desktop named
my-extension. This will hold all your extension files. - Create the manifest file. Inside the folder, create a new file named
manifest.json(make sure it’s notmanifest.json.txt). Open it in your text editor. - 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.
- 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.
- 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. - 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.
- Load the extension. Click the Load unpacked button that appears. In the file picker, navigate to your
my-extensionfolder and select it. Click Select Folder. - 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.
- Make changes and reload. Edit
popup.htmlto change the text, then save. Go back tochrome://extensionsand click the circular arrow (reload) icon on your extension card to apply the changes. - 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.txtinstead ofmanifest.jsonis the most frequent error. Make sure your text editor isn’t appending.txtautomatically. - Missing or invalid JSON: A missing comma, an extra quote, or a trailing comma in
manifest.jsonwill 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_version3. 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://extensionsand check for an error message on the card. - Error: “Manifest file is missing or unreadable”: Ensure the file is named exactly
manifest.jsonand is in the top level of the folder you selected. - Error: “Could not load manifest”: Open
manifest.jsonin a text editor and check for typos. Use a JSON linter online to validate the content. - Popup shows blank: Make sure
popup.htmlis 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
- Hogwarts Legacy Microsoft Visual C Runtime Error Fix
- Set Up UPI Payments Through WhatsApp
- Pair Oppo Enco Earbuds with Android, iPhone & Windows
- Fix Administrator Account Disabled Error in Windows 11
- How to Play Kodi on Smart TV from PC
- Factory Reset on Samsung Galaxy: What It Erases