Skip to content
Tutorials Center
My learning

Topics

Lesson 2 of 36 ยท Getting Started

The Anatomy of a Chrome Extension

Meet every part of a Manifest V3 extension: manifest, service worker, popup, options page, content scripts and side panel, and see where each one runs.

A web page is usually one HTML file with its scripts. An extension is different: it is a folder of files that run in several separate places at once. Understanding those places is the key to everything else in this course, because each place has different powers, a different lifetime and a different way to talk to the others.

This lesson is a map. Later chapters zoom into each region.

The parts at a glance

Five places your code can run

Manifest manifest.json describes everything
Service worker Background brain, no DOM
Extension pages Popup, options, side panel
Content scripts Run inside web pages

Every part is optional except the manifest.

1 / 2

1. The manifest

manifest.json is the only required file. It names the extension, sets the version, lists permissions and tells Chrome which files play which role. Chrome reads it when the extension loads and does not run until it passes validation. You will study it in the manifest basics lesson.

2. The service worker

The service worker is the extension's event handler. It has no window and no DOM. It wakes up when something happens (the extension is installed, an alarm fires, a message arrives, a tab changes) and Chrome stops it again when it is idle. It is the only place that can respond to many chrome.* events even when no tab is open. See Service Worker Basics.

3. Extension pages

These are ordinary HTML pages served from chrome-extension://<id>/:

  • the popup, opened by clicking the toolbar icon (popup basics);
  • the options page, for settings (options page);
  • the side panel, a persistent panel next to the page;
  • any other page you open in a tab, like an onboarding screen or a new-tab override.

They have a DOM, can use most chrome.* APIs and are safe from the websites you visit.

4. Content scripts

A content script is a JavaScript (and optionally CSS) file Chrome injects into web pages. It sees the page DOM, but lives in an isolated world: its variables are separate from the page's own scripts. It can use only a few chrome.* APIs directly (messaging and storage), so it asks the service worker for anything else. See content scripts.

flowchart TB
    M["manifest.json"] -.describes.-> SW["Service worker<br/>(no DOM, event driven)"]
    M -.describes.-> P["Popup / options / side panel<br/>(extension pages)"]
    M -.describes.-> CS["Content scripts<br/>(inside web pages)"]
    P <-->|messages| SW
    CS <-->|messages| SW
    CS -->|DOM access| WP["Web page"]

Solid arrows are communication; dotted arrows are configuration.

A typical folder

A small real extension can be this simple:

TEXT
my-extension/
  manifest.json
  background.js        โ† service worker
  popup.html
  popup.js
  content.js
  options.html
  icons/
    16.png
    48.png
    128.png

Notice there is no build step required. You can write plain files and load them. Bundlers such as Vite are optional and help when you use TypeScript or frameworks.

Lifetimes differ

Part Starts when Ends when
Service worker An event it listens for happens About 30 seconds after it goes idle
Popup The user clicks the toolbar icon The popup loses focus (it closes!)
Options page The user opens it The tab is closed
Content script A matching page loads The page is closed or navigates

Because the popup and the service worker die, you cannot keep state in global variables. Persist data in chrome.storage instead (see the storage chapter).

A stand-in for the architecture

The stand-in below is a tiny event bus that models the parts as separate objects which only talk through messages. It is not a real extension, but the shape of the code matches what you will write.

JS Parts talk only by messages

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

No output.

JS Which part owns which job?

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

No output.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which file is the only one every extension must have?

    The manifest describes the extension to Chrome. Everything else is optional.
  2. 2. Why should you not store state in global variables of the popup or service worker?

    The popup closes when it loses focus and the service worker is stopped when idle, so persistent data belongs in chrome.storage.
  3. 3. What is special about the world a content script runs in?

    Content scripts run in an isolated world, so they can use the DOM but their JavaScript scope is separate from the page's scripts.
  4. 4. Which part can reach the DOM of a web page directly?

    Only content scripts (or functions injected into the page) work on the page's DOM.

Summary

  • An extension is a folder; manifest.json is mandatory and tells Chrome what everything else is.
  • Code runs in separate contexts: service worker, extension pages, content scripts.
  • Contexts talk by messages, not shared variables.
  • The popup and service worker are short-lived, so persist data in storage.
  • No build step is required to start.

Next: Your First Extension: Load It in Chrome