Skip to content
Tutorials Center
My learning

Topics

Lesson 33 of 36 ยท Projects and Practice

Project: Page Notes Extension

Build a complete Manifest V3 extension that saves a note for any web page, shows it in a popup, lists all notes on an options page and syncs across extension pages with chrome.storage.

In this project you build Page Notes: click the toolbar icon on any page, write a note, and the extension saves it for that page's address. Open the page again later and your note is there. It combines storage, a popup, messaging and permissions from this chapter in one small, real extension.

The Chrome APIs run only inside an installed extension, so the full source is shown as files you can copy into a folder and load with Load unpacked (see Debugging every context). The interactive parts use a stand-in storage so you can try the logic here.

Plan

flowchart LR
    P["Popup<br/>(write and read note)"] --> L["notes.js<br/>(pure logic)"]
    L --> S["chrome.storage.local"]
    O["Options page<br/>(list all notes)"] --> S
    S -- "onChanged" --> P

One small logic module is shared by the popup and options page.

Features: save a note per page (keyed by URL without the #hash), delete it, list all notes, and keep a 2,000-character limit. Permissions needed: storage and activeTab (to read the current tab's URL). No host permissions at all.

Files

Text
page-notes/
  manifest.json
  notes.js
  popup.html
  popup.js
  options.html
  options.js

manifest.json

JSON
{
  "manifest_version": 3,
  "name": "Page Notes",
  "version": "1.0.0",
  "description": "Save a short note for any web page and see it when you return.",
  "permissions": ["storage", "activeTab"],
  "action": { "default_title": "Page notes", "default_popup": "popup.html" },
  "options_page": "options.html"
}

notes.js: the logic

The functions are pure, so they are easy to unit test (see Unit testing).

JavaScript
export const MAX = 2000;

export function keyFor(url) {
  const u = new URL(url);
  u.hash = "";
  return u.href;
}

export function setNote(notes, url, text) {
  const key = keyFor(url);
  const clean = text.trim().slice(0, MAX);
  const next = { ...notes };
  if (clean) next[key] = { text: clean, updated: Date.now() };
  else delete next[key];
  return next;
}

export function listNotes(notes) {
  return Object.entries(notes)
    .map(([url, n]) => ({ url, ...n }))
    .sort((a, b) => b.updated - a.updated);
}
Try the notes logic with a stand-in storage

Notice that the #section2 part of the address is dropped, so a note belongs to the page and not to one anchor on it.

popup.html and popup.js

HTML
<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <style>
    body { width: 300px; font: 14px system-ui; margin: 12px; }
    textarea { width: 100%; box-sizing: border-box; }
    #status { color: #666; min-height: 1.2em; }
  </style>
</head>
<body>
  <textarea id="note" rows="6" maxlength="2000" placeholder="Note for this page"></textarea>
  <button id="save">Save</button>
  <span id="status"></span>
  <script type="module" src="popup.js"></script>
</body>
</html>
JavaScript
// popup.js
import { setNote, keyFor } from "./notes.js";

const note = document.getElementById("note");
const status = document.getElementById("status");

const [tab] = await chrome.tabs.query({ active: true, currentWindow: true });
const url = tab.url;

if (!/^https?:/.test(url)) {
  note.disabled = true;
  status.textContent = "Notes work on web pages only.";
} else {
  const { notes = {} } = await chrome.storage.local.get("notes");
  note.value = notes[keyFor(url)]?.text ?? "";
}

document.getElementById("save").addEventListener("click", async () => {
  const { notes = {} } = await chrome.storage.local.get("notes");
  await chrome.storage.local.set({ notes: setNote(notes, url, note.value) });
  status.textContent = "Saved";
});

The popup reads tab.url thanks to activeTab, which grants access when the user clicks the icon. It refuses non-web pages such as chrome://extensions, where extensions are not allowed to act. The script is a module file with no inline code, so the default CSP is satisfied (CSP).

options.html and options.js

HTML
<!doctype html>
<meta charset="utf-8">
<title>Page Notes</title>
<h1>All notes</h1>
<ul id="list"></ul>
<script type="module" src="options.js"></script>
JavaScript
// options.js
import { listNotes, setNote } from "./notes.js";

const list = document.getElementById("list");

async function render() {
  const { notes = {} } = await chrome.storage.local.get("notes");
  list.replaceChildren(...listNotes(notes).map((n) => {
    const li = document.createElement("li");
    const a = document.createElement("a");
    a.href = n.url; a.textContent = n.url; a.target = "_blank";
    const p = document.createElement("span");
    p.textContent = " - " + n.text;               // text, never innerHTML
    const del = document.createElement("button");
    del.textContent = "Delete";
    del.addEventListener("click", async () => {
      await chrome.storage.local.set({ notes: setNote(notes, n.url, "") });
    });
    li.append(a, p, del);
    return li;
  }));
}

chrome.storage.onChanged.addListener((changes, area) => {
  if (area === "local" && changes.notes) render();
});
render();

The onChanged listener keeps the options page current when you save from the popup (Storage patterns). Note text is inserted with textContent because it is data the user typed, and the habit protects you if you later import notes from elsewhere (Secure messaging).

Run it

  1. Create the folder with the files above.
  2. Open chrome://extensions, enable Developer mode, click Load unpacked.
  3. Pin the icon, open any website, click it, type a note, press Save.
  4. Right-click the icon, choose Options to see the list.

Ideas to extend

  • Show a badge with chrome.action.setBadgeText when the page has a note (needs a small worker with tabs.onUpdated).
  • Add export to JSON, and an import with validation.
  • Migrate to a new data shape using a schema number.
  • Move notes to storage.sync for small text.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Why does Page Notes need no host permissions?

    activeTab grants temporary access to the current tab on a user gesture, enough to read its URL.
  2. 2. Why is the URL hash removed from the note key?

    A note should belong to the page, not to a particular #section.
  3. 3. How does the options page know a note changed in the popup?

    onChanged fires in every extension context after a write.
  4. 4. Why use textContent for the note text?

    Never turn data into markup; textContent keeps it inert.

Summary

  • Page Notes combines a popup, an options page, pure logic and chrome.storage.local.
  • activeTab + storage are the only permissions; no host access is needed.
  • onChanged keeps views in sync; textContent keeps data safe.
  • Pure functions in notes.js make the project easy to test.

Next: Project: Price Highlighter with a Content Script