chrome-extension

Chrome extension (Manifest V3)

An MV3 extension is three isolated JavaScript contexts that never share memory and only talk via messages:

1. Service worker (background.service_worker) — the logic and lifecycle brain. Ephemeral: Chrome kills it when idle and restarts it on the next event. It has no DOM and no window.
2. Content scripts — run inside a web page, can read/write that page's DOM, live in an isolated JS world by default. No access to most chrome.* APIs except messaging and storage.
3. UI surfaces — popup (action.default_popup), options page, side panel. Normal web pages that load and unload as the user opens/closes them.

Internalize that picture first. Most extension bugs are someone treating one of these as if it shared state with another. They do not. The wire between them is chrome.runtime messaging and chrome.storage.

Manifest V3 is the only version the Chrome Web Store accepts; MV2 phase-out began June 2024 and is still rolling out. Build MV3 from the start.

Pick a skeleton

Setup	Pick when	Cost
Vanilla (raw files, load unpacked)	tiny extension, no npm imports, you want the fastest possible reload loop	no TS, no HMR, manual reloads
Vite + CRXJS (@crxjs/vite-plugin)	TS, npm imports, React/Vue popup, you want HMR	a build step; you ship dist/, not the repo

Default to Vite + CRXJS the moment you want TypeScript or a framework popup — it does the manifest wiring and HMR for you. Reach for vanilla only for a one-file experiment.

Minimal tree (Vite + CRXJS):

my-ext/
  manifest.json        # source of truth; CRXJS reads it
  src/
    background.ts       # service worker
    content.ts          # content script
    popup/
      index.html
      popup.tsx
  public/icons/         # 16, 48, 128 px PNGs
  vite.config.ts
  # build output -> dist/  (this is what you zip)

manifest.json — minimum viable shape

{
  "manifest_version": 3,
  "name": "Highlighter",
  "version": "1.0.0",
  "description": "Highlights selected text on the current page.",
  "icons": { "16": "icons/16.png", "48": "icons/48.png", "128": "icons/128.png" },
  "action": { "default_popup": "popup/index.html" },
  "background": { "service_worker": "background.js", "type": "module" },
  "permissions": ["activeTab", "storage", "scripting"],
  "host_permissions": [],
  "minimum_chrome_version": "120"
}