Your First Chrome Extension: Run Hello World in 15 Minutes

💡 One-sentence summary: one folder, three files, Chrome developer mode—15 minutes to make your browser show your own extension's Hello World.

The previous lesson C1 What Is a Browser Extension covered the concepts: an extension is just HTML/CSS/JS plus a manifest.json. This lesson is hands-on—the most solid step in getting started with Chrome extensions isn't memorizing ten more terms, but making the browser actually pop up an extension of your own.

Don't skip these 15 minutes—even if you plan to have AI write all the code. The three actions of loading locally, refreshing, and viewing the popup will always be yours to perform, and Hello World is how you turn them into muscle memory.

What You'll Be Able to Do After This Lesson

• Build a real extension installed in Chrome: click the toolbar icon and a "Hello Extensions" popup appears
• Write out the official minimal manifest.json example character by character and explain what each field does
• Complete local loading in three steps: chrome://extensions → Developer mode → Load unpacked
• Pin the extension to the toolbar so it's always one click away
• Remember the reload rule: which file changes require refreshing the extension and which don't

Where You Are Right Now

• "I've memorized a pile of extension terms: manifest, MV3, popup... but I've never gotten a single line of code running in the browser"
• "The AI wrote the code, but I have no idea where these files go or how Chrome is supposed to recognize them"
• "I followed old tutorials online, but Load unpacked throws an error the moment I click it, and I don't know what's wrong"

When to Use This Technique

When you need to:

• Turn "build an extension" from an idea into reality—get the smallest version running first, then add features on top
• Verify your dev pipeline works: can create files, can load, can see the popup—pass all three checkpoints
• Give your AI requirements a concrete starting point: get Hello World running first, then have AI build on top in the next lesson

And when you don't want to:

• Chew through every manifest field right away—the next lesson C3 will break them down one by one
• Deal with packaging, publishing, or review—that's for C6
• Install any dev environment—one folder + Chrome's built-in developer mode is enough

🎒 Before You Start

• Finished C1 What Is a Browser Extension, and know that an extension = HTML/CSS/JS + manifest.json; for now we only write MV3
• Chrome browser installed on your computer
• A tool for creating and editing text files (the system's Notepad works; a code editor like VS Code is more comfortable)
• 15 minutes

Core Idea

The minimal form of a Chrome extension is one folder plus three files:

File	Purpose	Who Uses It
manifest.json	The extension's ID card + manual: its name, version, and what happens when you click the icon	Chrome reads it
hello.html	The little page that pops up when you click the toolbar icon	The user sees it
hello_extensions.png	The toolbar icon (can be omitted; Chrome will supply a generic one)	The user sees it

How it works in one sentence: Chrome recognizes your extension through manifest.json; inside the manifest, action.default_popup tells Chrome "when the toolbar icon is clicked, open hello.html".

Before we start, two ground rules:

1. manifest_version Only write 3. The official docs state plainly that the only supported value is 3; don't copy the 2 from old tutorials (C1 covered that MV2 has been fully disabled; field rules are detailed in C3 Explained).
2. Developer mode ≠ publishing to the store. Developer mode + Load unpacked is just a switch that "allows installing a local folder into the browser"; publishing to the Chrome Web Store requires developer registration and review—a separate path (see C6).

💡 Should You Type This Lesson by Hand?

The three files are small enough that typing them by hand takes only a few minutes—recommended for your first time. This is the step where people most often die on a single quote mark or a single field name; type it once yourself, and you'll know which parts of AI-written code to check later. From the next lesson on, the files keep multiplying—that's when AI takes the stage.

Follow Along

Step 1: Create the extension folder

Why: an extension is just "a few files inside one folder"—give them a home first.

How: on your desktop (or anywhere you can find it), create a new folder and name it hello-extensions.

If you want to compare against the finished result, the official sample source code is on GitHub: the functional-samples/tutorial.hello-world directory of the GoogleChrome/chrome-extensions-samples repository. But for this lesson, we recommend building it yourself—it's only three files in total.

You should see: an empty folder.

Step 2: Write manifest.json—the first file in your introduction to Chrome extensions

Why: Chrome only recognizes manifest.json. Without it, this folder is just an ordinary folder.

How: inside the folder, create manifest.json and copy the official sample content verbatim:

{
  "name": "Hello Extensions",
  "description": "Base Level Extension",
  "version": "1.0",
  "manifest_version": 3,
  "action": {
    "default_popup": "hello.html",
    "default_icon": "hello_extensions.png"
  }
}

What each of the six fields does:

Field	Value in this lesson	What it does
name	Hello Extensions	The extension name, shown on the extensions page and elsewhere
description	Base Level Extension	A one-line description
version	1.0	The version number (1-4 dot-separated integers)
manifest_version	3	Declares MV3—the only supported value
action.default_popup	hello.html	Clicking the toolbar icon pops up this page
action.default_icon	hello_extensions.png	The toolbar icon uses this image

⚠️ Two details

• In JSON you cannot write comments—both // and /* */ will make parsing fail outright. If you want to take notes, write them outside the file.
• Don't want to prepare an icon? Delete the entire "default_icon" line, and Chrome will automatically give the extension a generic icon.

You should see: a manifest.json sitting in the folder.

• Quick check: reopen it in your editor and confirm "manifest_version": 3, with every quotation mark paired

Step 3: Write hello.html, plus an icon

Why: the file that default_popup points to must actually exist, so there's something to pop up when you click the icon.

How: create hello.html and copy the official sample content:

<html>
  <body>
    <h1>Hello Extensions</h1>
  </body>
</html>

Pick one of two options for the icon:

• Option A (follow the official sample): download the sample icon from the official tutorial page, rename it hello_extensions.png and put it in the folder—the filename must match what default_icon says exactly.
• Option B (easier): if you deleted default_icon in the previous step, just skip this—Chrome will provide a generic icon.

You should see: two or three files in the folder: manifest.json, hello.html, plus the icon (if you chose Option A).

Step 4: Turn on Chrome Developer Mode and load locally with Load unpacked

Why: by default, Chrome only installs extensions from the store. Developer Mode is the switch that "allows local installation," and Load unpacked is what installs your folder into the browser.

How (the official three steps):

1. In a new tab, type chrome://extensions in the address bar and press Enter to open the extensions management page. Two other entrances: the toolbar puzzle button → Manage Extensions; or the Chrome menu → More Tools → Extensions.
2. Turn on the Developer mode switch.
3. Click Load unpacked and select your extension folder in the file picker.

Note: the folder you select must have manifest.json lying directly inside it—the official requirement is that it sit in the extension's root directory; with an extra subfolder in between, Chrome won't find it.

You should see: Hello Extensions appears in the extensions page list, with the message "The extension has been successfully installed."; if you didn't provide an icon, Chrome automatically assigned a generic one.

• Quick check: the Hello Extensions card displays normally, with no error dialog popping up

Step 5: Pin it to the toolbar and open your first popup

Why: locally loaded extensions are hidden in the puzzle menu by default, so you have to click an extra time each use; pinning it makes it convenient.

How: click the toolbar's puzzle button, find Hello Extensions, and click the pin icon (Pin) next to it to pin it to the toolbar. Then click this extension's icon on the toolbar.

You should see: a small popup appears, displaying Hello Extensions—your first Chrome extension is up and running.

Step 6: Change the code and learn to reload the extension

Why: extensions don't automatically read the files you've changed—most changes only take effect after a manual reload. This is the spot where beginners most easily misjudge it as "the AI wrote it wrong."

How: in manifest.json, change name to "Hello Extensions of the world!" and save. Go back to chrome://extensions and click the reload icon next to the on/off switch on the extension's card.

You should see: the extension's name changes to Hello Extensions of the world!. Without clicking reload, it stays the old name.

The official reload rules table—memorize it now:

What you changed	Reload the extension?
manifest	Yes
Service worker	Yes
Content scripts	Yes (and also reload the web page they're on)
Popup	No need
Options page	No need
Other plugin HTML pages	Not needed

This lesson's plugin has only two kinds of files, manifest and popup, so the rule is simple: change the manifest, go to the extensions page and click reload; change hello.html, no reload needed—reopen the popup and you'll see the new content.

Checkpoint ✅

• chrome://extensions shows the Hello Extensions card normally, with no errors
• The plugin is pinned to the toolbar, and clicking the icon pops up Hello Extensions
• After changing name, you went to the extensions page and clicked the reload icon, and the name changed
• You can state the reload rule: manifest, service worker, and content scripts need a reload; the popup and other HTML pages do not
• You know that Developer mode is just a switch for "local loading," and publishing requires registration + review (C6)

Pitfall warnings

❌ Writing comments in manifest.json

JSON does not support comments. If you write // or /* */, the manifest fails to parse——when loading locally, an error dialog pops up directly; the official docs also state that packaging and uploading JSON containing comments will report Cannot parse the manifest.

Correct approach: keep comments and notes outside the file; if unsure about a field's meaning, check C3 field quick reference.

❌ Copying old tutorials and writing manifest_version as 2

A large number of online tutorials were written in the MV2 era. The only supported value for manifest_version is now 3, and MV2 plugins have been fully disabled by Chrome—copying them is wasted work.

Correct approach: before starting, check whether this line is "manifest_version": 3; close any tutorial teaching MV2 immediately.

❌ Changing code without reloading the plugin and thinking "the AI got it wrong"

If you don't reload after changing the manifest, service worker, or content scripts, the browser still runs the old code——you'll mistakenly think the code is broken and make the AI repeatedly rewrite a completely correct piece of code.

Correct approach: after changes, first go through the reload rule table from step 6: for things needing a reload, go to the extensions page and click the reload icon; for popup changes, no reload needed. If it's still wrong, then go to C5 find logs.

❌ Thinking that turning on Developer mode counts as "published"

Developer mode is just a switch that allows local installation; at this point the plugin is usable only by you. Publishing to the Chrome Web Store requires developer registration (paying a one-time registration fee, with the amount subject to the actual payment page in the developer dashboard) and review.

Correct approach: after it works locally, follow C6 the full publishing workflow for registration, packaging, and submission for review.

Advanced tips (optional)

🚀 Add a line of logging to the popup and get an early taste of debugging. Add <script src="popup.js"></script> before </body> in hello.html, create a new popup.js and write console.log("This is a popup!"). Open the popup → right-click the popup → Inspect → Console panel, and you'll see this log. When you deliberately write broken code (e.g., missing a quote), an Errors button appears on the extensions page; click it for details. For where the logs of service workers and content scripts live, C5 has a complete map.

Project structure is up to you: the official docs explicitly say the organization is free-form, and the only hard requirement is that manifest.json be placed in the plugin's root directory. If you use TypeScript, installing the npm package chrome-types gives you Chrome API autocompletion——it updates automatically with the Chromium source, and the official docs remind you to upgrade it often.

Lesson summary

✅ In this first lesson on getting started with Chrome extensions, you have:

• Built and ran your first plugin: a folder + manifest.json + hello.html, clicking the icon pops up Hello Extensions
• Mastered the three steps of local loading: chrome://extensions → Developer mode → Load unpacked
• Can pin the plugin to the toolbar for use anytime
• Remembered the reload rule: after changing manifest, service worker, or content scripts, reload; popup doesn't need it
• Know the first entry point for logs: right-click the popup and Inspect

Review of key configuration fields:

Field	Value in this lesson	Description
manifest_version	3	The only supported value; don't write 2
name	Hello Extensions	Plugin name
description	Base Level Extension	Description
version	1.0	Version number, 1-4 dot-separated integer segments
action.default_popup	hello.html	The page that pops up when the icon is clicked
action.default_icon	hello_extensions.png	Icon; if omitted, a generic icon is used

Next lesson preview

In the next lesson C3 manifest.json in depth: we take this minimal instruction manual apart field by field. You will learn:

• Rules for the three required fields: name max 75 characters, format details of version
• Fields you must add before publishing: description (max 132 characters), icons
• content_scripts, permissions — how to write these frequently used optional fields
• Why, after uploading to the store, fixing even one typo requires bumping the version number and repackaging

When you're ready, head into C3 →