Browser Extension Starter - Page Notes & Reading List (Manifest V3, TypeScript)

A complete, working Manifest V3 browser extension written in TypeScript: save pages to a reading list, keep notes, highlight text on any page and search all of it. Everything is stored in the browser on the user's own device. There is no account, no sync, no server and no network request. Ship it as it is, reskin it, or use it as a clean reference for how the pieces of a modern extension fit together.

What is inside

• Toolbar popup (360 px): save the current page with a folder and tags, write a quick note, see the page status and the three most recent pages
• Side panel: reading list with folders and tags, read, unread and archived states, a detail view per page with notes and highlights, and a Notes view that lists every note and highlight grouped by page
• Full-text search over titles, addresses, tags, folders, descriptions, notes and highlights, with ranking, accent-insensitive matching, highlighted matches and operators such as tag:, folder:, is:unread, has:notes, domain:, -word and quoted phrases
• Keyboard-first panel: / to search, j and k to move, Enter for details, o, r, a, n, Delete, ? for help; delete has an Undo that restores the page with its notes and highlights
• Content script: select text and a floating toolbar (Highlight, Add note, four colors) appears. It is rendered in a closed Shadow DOM, so page CSS cannot break it. Highlights are drawn with the CSS Custom Highlight API, so the page DOM is never modified, and clicking one opens a small popover to recolor it, delete it or edit its note. Add note saves the highlight and opens the side panel, so notes are typed in the extension and never inside the web page
• Text anchoring that survives page changes: each highlight stores the quote, its surrounding text and its position, and is found again by position, exact quote, quote plus context, a whitespace and case tolerant match, or a fuzzy start and end match. Highlights that cannot be found are skipped without errors. Highlights are shown again when you open the extension on a page (toolbar icon, shortcut or right-click menu), or automatically on every page if you turn on the optional every-page mode
• Context menu items (save page, highlight selection, add note to selection, open the reading list) and four keyboard shortcuts for the popup, the side panel, saving the page and highlighting the selection
• Badge with the number of unread pages (can be switched off)
• Options page: light, dark or system theme, default folder, folder management, default highlight color, an optional "highlight on every page" mode, shortcut overview, storage meter with a warning near the quota, JSON export, JSON import with validation and a preview, and a confirmed "delete all data"
• Storage layer: a typed repository over chrome.storage.local with one key per record, a schema version, a tested migration framework (a version 1 to version 2 example is included), serialized writes from the service worker and handled quota errors
• Import and export that validates every field, upgrades older files, skips bad records with a readable report and refuses files from a newer schema
• i18n scaffold: every visible string goes through _locales/en/messages.json (English is the only shipped language); a test checks that every key used in code exists
• Build tooling: a small Vite build script you can read (pages and service worker as ES modules, the content script as one self-contained file), icons generated by a script from simple geometry, a manifest validation script and npm run pack, which zips the build for a store upload

Permissions and privacy

The manifest asks for storage, sidePanel, activeTab, scripting and contextMenus, with no host permissions. The highlight script is injected into a page when the user opens the popup, uses a shortcut or uses the right-click menu there. The optional mode "highlight on every page" asks the browser for optional host access first and can be turned off again. The extension pages use a strict content security policy: no inline scripts, no eval, no remote code and connect-src 'none'. The validation script checks these rules on every build.

Design

A compact "field notebook" look: cool slate surfaces with a warm amber accent, monospaced metadata labels, a 4 px grid, sticky headers, tag chips, row actions that appear on hover or keyboard focus, visible focus rings, light and dark themes from CSS custom properties. System fonts only and hand-drawn inline SVG icons, so nothing is loaded from the network.

Quality checks

• TypeScript in strict mode, ESLint, and 342 automated tests (Vitest with jsdom and a hand-written in-memory chrome.* mock): storage and migrations, import and export including hostile JSON, text anchoring on many DOM fixtures, search ranking, the message protocol, service worker behavior, the content script, and the popup, side panel and options UI. Tests use a fixed clock and do not depend on the date or time zone
• A seeded fuzz pass sends thousands of malformed messages, import files and queries and checks that nothing throws and stored data keeps its invariants
• The production build was also loaded as an unpacked extension in Chromium 153 and driven with an automated browser: popup, side panel, options page, the content script on a local test page, the real storage quota, and the strict content security policy with no console errors

Requirements and how to start

• Node.js 20.19+, 22.13+ or 24+ (this is the intersection of the engines fields of the dependencies; everything was run and tested on Node 24.18 only); Chrome 116 or newer for the side panel and highlight APIs. Edge uses the same Manifest V3 APIs but was not tested
• npm install, then npm run build, then in chrome://extensions turn on Developer mode, choose Load unpacked and select the dist folder
• npm run dev rebuilds on every change; npm run check runs type check, lint, tests and build; npm run pack creates the zip for a store upload

Good to know

• Notes are typed only in the popup, the side panel and the options page, never inside a web page, because scripts of a page can observe what is typed in it. Highlighting a passage is a click on the in-page toolbar, which the page can also observe, like any text selection
• With the every-page mode off, opening a saved page from the list does not show its highlights until you click the toolbar icon on that page; the extension reminds you after Go to highlight
• Only page address, title, description, your notes and your highlighted quotes are stored. Pages are not archived and no page text is saved beyond the quotes you highlight
• Storage is the browser's local extension storage (about 10 MB by default). Limits: 5000 pages, 200 notes and 500 highlights per page, highlights up to 2000 characters
• Not included: accounts or cloud sync, Firefox or Safari builds, translations beyond English, store listing texts and images, and browser-driven end-to-end tests (they were used to check the build but are not part of the download)
• The browser permission prompt of the optional "highlight on every page" mode was not exercised in the automated browser run

Download: one .zip with the source code only (TypeScript, Preact components, CSS, build and validation scripts, locale file, tests, and the package and lock files). No documentation files are included. Personal and Commercial licenses are explained on the store's license page.