How mengxi-ream/read-frog works
Project type and purpose
• This is a browser extension (Chrome, Edge, Firefox) named “Read Frog” for immersive language learning.
• It injects UI into pages (side.content, host.content), provides a popup UI, an options page, and runs a background script to orchestrate API calls, storage, and content extraction.
File structure
• Top-level entrypoints folder maps directly to extension components:
• background – service worker logic (index.ts, translation, new-user guide)
• side.content & host.content – content scripts that mount React UIs on the page
• popup – React UI for toolbar popup
• options – React UI for extension settings
• guide.content – in-page onboarding guide
• src/components, src/hooks, src/utils, src/types: shared React components, hooks, utility functions, type definitions.
• config files for bundler (wxt.config.ts), linter, testing (vitest).
• package.json & pnpm-lock through pnpm, changeset-driven releases, husky + commitlint, GitHub Actions for CI/CD.
README for additional insights
• Features: immersive translation, content extraction, multi-model support.
• Build commands: pnpm dev, pnpm zip, pnpm zip:firefox.
a. Main components:
• Extension Manifest (implicit)
• Background Service Worker
• Content Scripts
– side.content (injected sidebar UI)
– host.content (injected translation nodes)
– guide.content (onboarding overlay)
• UI Pages (Popup, Options)
• Storage Layer (browser.storage via utils/atoms/storage-adapter)
• External AI APIs (OpenAI, DeepSeek)
• Shared Libraries (React components, hooks, utils)
b. Relationships & data flow:
1. User interacts with Popup or Options → sends messages to Background.
2. Background loads/saves config to Storage.
3. Content Scripts detect page content → send extraction/translation requests to Background.
4. Background performs API calls (requests.ts) → returns results.
5. Content Scripts render translations via injected React components.
6. guide.content reads config from Background to show onboarding.
c. Architectural patterns:
• Message-based architecture between Background ↔ Content Scripts ↔ UI pages.
• Atomic design for UI (src/components/ui).
• Separation of concerns: extraction (host/dom), translation logic (utils/host/translate.ts), configuration + migration (utils/config).
d. Key technologies:
• TypeScript + React (TSX entrypoints)
• Tailwind CSS (postcss.config.cjs + utils/tailwind)
• pnpm + Changesets for releases
• Vitest for unit tests
• GitHub Actions for CI (lint, test, release)