How frederikb/bookmarksync works
Project Type and Purpose
• This is a browser extension (built with Web Extension Toolkit) that synchronizes browser bookmarks from JSON files stored in a GitHub (or GHES) repository.
• It comprises a background service worker that handles scheduling and syncing logic, two UI entrypoints (Options page and Popup), utility modules for GitHub interaction and bookmark processing, and relies on browser APIs (bookmarks, storage, notifications).
Main Components
a. Extension UIs (Frontend)
• Options Page (HTML/CSS/JS)
• Popup Page (HTML/CSS/JS)
b. Background Service Worker
• Entry: src/entrypoints/background.js
• Handles alarms, manual sync triggers, and coordination of modules
c. Utility Modules
• GitHub loader (src/utils/github-bookmarks-loader.js / Octokit)
• Bookmark parser & validator (src/utils/bookmarksync.js + JSON schema)
• Options storage (src/utils/options-storage.js)
• Error handling (src/utils/errors.js)
d. Browser APIs
• browser.storage (storing token, repo, path)
• browser.alarms (scheduling)
• browser.bookmarks (reading/updating bookmarks)
• browser.notifications (user feedback)
e. External Service
• GitHub or GitHub Enterprise API (via configurable API URL + PAT)
f. Static Assets
• Schema file (src/utils/bookmarks.1-0-0.schema.json)
Relationships and Data Flows
• At startup or on alarm → Background Worker reads config from browser.storage → calls GitHub API → fetches one or more JSON files → validates against schema → computes delta vs. existing bookmarks (browser.bookmarks) → writes new/updated bookmarks → fires browser.notifications
• Popup UI → sends a “manual sync” message to Background via runtime messaging → triggers immediate sync workflow
• Options UI → reads/saves user configuration to browser.storage via Options Storage module
• All components are bundled by wxt.config.ts and loaded per manifest definitions
Architectural Patterns & Design Principles
• Event-driven: browser.alarms and runtime messaging trigger actions
• Modular: clear separation between UI entrypoints, background orchestration, utility modules
• Single responsibility: each utils file handles one concern (storage, GitHub fetch, parsing, errors)
• External integration: Octokit for GitHub, JSON Schema for validation