Skip to content
Tutorials Center
My learning

Topics

Lesson 3 of 36 ยท Getting Started

Your First Extension, Loaded in Chrome

Create a Hello World Chrome extension with a manifest, popup and content script, load it with Load unpacked, and reload it after each change.

Time to build something you can click. In about ten minutes you will create a three-file extension, load it into Chrome without publishing anything, and see it work. This is the workflow you will use for the rest of the course: edit files, press reload, test.

Step 1: make a folder

Create a folder called hello-extension anywhere on your computer. Put three files in it.

manifest.json

JSON
{
  "manifest_version": 3,
  "name": "Hello Extension",
  "version": "1.0",
  "description": "My first Chrome extension.",
  "action": {
    "default_title": "Say hello",
    "default_popup": "popup.html"
  },
  "content_scripts": [
    {
      "matches": ["https://example.com/*"],
      "js": ["content.js"]
    }
  ]
}

popup.html

HTML
<!doctype html>
<html>
  <head>
    <meta charset="utf-8" />
    <style>
      body { width: 220px; font: 14px system-ui, sans-serif; padding: 12px; }
    </style>
  </head>
  <body>
    <h1>Hello!</h1>
    <p id="clock"></p>
    <script src="popup.js"></script>
  </body>
</html>

popup.js

JavaScript
document.getElementById("clock").textContent =
  "It is " + new Date().toLocaleTimeString();

content.js

JavaScript
document.body.style.border = "6px solid tomato";
console.log("Hello from the content script!");

Manifest V3 forbids inline scripts. That is why popup.html loads popup.js with src instead of writing code between <script> tags. You will see this rule again in the security chapter.

Step 2: load it

  1. Open chrome://extensions in Chrome (or Edge: edge://extensions).
  2. Turn on Developer mode (top right).
  3. Click Load unpacked and choose the hello-extension folder.

Your extension appears in the list with an ID (a 32-letter string). Pin it from the puzzle-piece menu in the toolbar, click it, and the popup opens. Now visit https://example.com: the page gets an orange-red border, and the DevTools console shows your message.

flowchart LR
    F["hello-extension/ folder"] --> L["Load unpacked"]
    L --> E["Extension appears<br/>at chrome://extensions"]
    E --> T["Test in browser"]
    T --> ED["Edit files"]
    ED --> R["Click reload icon"]
    R --> T

The development loop: edit, reload, test.

Step 3: change something and reload

Edit content.js, for example change tomato to royalblue. Chrome does not notice the change by itself. Go to chrome://extensions and click the circular reload icon on your extension card, then refresh the page you are testing. Remember both steps:

  • Changed manifest or service worker? Reload the extension.
  • Changed a content script? Reload the extension and the web page.
  • Changed a popup? Close and reopen the popup (it loads fresh each time), unless the manifest changed.

When something goes wrong, the extension card shows an Errors button with details. We cover this in depth in Testing and Debugging.

Stand-in: try the popup and page effect here

You cannot load an extension into this page, but you can try the same two ideas side by side. The left box is the popup; the button plays the content script.

Popup and content script, simulated

Common first-run problems

Symptom Likely cause
"Manifest file is missing or unreadable" You selected the wrong folder, or the file is not called exactly manifest.json
"Could not load manifest": JSON error A trailing comma or comment: JSON allows neither
Popup is blank popup.js path wrong, or the script is inline
Border does not appear The URL does not match matches, or you did not refresh the page
Extension shows an Errors button Click it: the message names the file and line

Because JSON mistakes are so common, here is a tiny checker that finds the problems above. It is a stand-in, but it behaves like Chrome's first validation step.

JS A mini manifest checker

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Check your understanding

Quick check ยท 3 questions

of 3 answered You scored / 3 ยท perfect!

  1. 1. Which button on chrome://extensions loads your folder as an extension?

    Load unpacked (visible with Developer mode on) installs an extension straight from a folder, which is the normal development workflow.
  2. 2. You edit a content script. What must you do to see the change on a page?

    Chrome does not watch files. Reload the extension on chrome://extensions and refresh the page so the new script is injected.
  3. 3. Why does popup.html use src="popup.js" instead of inline code?

    Manifest V3 extension pages block inline scripts for security, so scripts must be separate files.

Summary

  • A working extension needs only a folder with a manifest.json and the files it references.
  • Enable Developer mode and use Load unpacked at chrome://extensions.
  • Reload the extension after changes, and refresh pages for content script changes.
  • JSON must be strict: no comments or trailing commas.
  • Scripts go in separate files; inline scripts are blocked.

Next: Manifest V3 and Why It Exists