How nubplayz/goodlib-zlib-goodreads-extension works
GoodLib is a Manifest V3 browser extension built with Plasmo, TypeScript, React, and Anime.js. Architecturally, it is a small, client-side-only extension with four main runtime surfaces:
1. A background service worker
2. A content script injected into supported book pages
3. A popup UI for quick source toggles
4. An options page for persistent configuration
There is no backend in this repo. All behavior happens in the browser, and the only persisted state is local extension storage for user preferences.
High-level purpose
The extension enhances Goodreads and Hardcover book pages by injecting badges/links that let the user open search results on external book sources:
• Anna’s Archive
• Z-Library
• Project Gutenberg
The data flow is straightforward:
• The content script runs only on supported book-page URLs.
• It reads page context such as the displayed book title/metadata.
• It uses the current source-toggle settings to decide which badges to render.
• Clicking a badge opens the corresponding external source URL in the browser.
Main subsystems
1. Content script subsystem
Files:
• content.ts
• content.css
This is the page-integrated layer. It is responsible for:
• Detecting supported book pages
• Reading the page’s book details
• Injecting UI elements directly into Goodreads/Hardcover pages
• Applying the associated styling via content.css
This is the main “in-page” boundary of the extension. It interacts with host websites’ DOM, so it is isolated from the extension’s internal UI surfaces.
2. Extension background subsystem
File:
• background.ts
This is the service-worker layer typical of MV3 extensions. In this repo, it is the natural place for:
• Shared orchestration logic
• Messaging between popup/options/content scripts
• Reading and writing extension storage
• Centralizing source enable/disable preferences or other cross-surface state
It acts as the bridge between the browser UI surfaces and the content script that modifies book pages.
3. Popup UI subsystem
Files:
• popup.tsx
• popup.css
This is the lightweight extension-action UI. Based on the README, its purpose is to let users quickly toggle which sources are active, for example:
• show only Anna’s Archive and Z-Library
• hide Project Gutenberg
This UI is React-based and likely uses extension messaging/storage to update preferences immediately. It is optimized for quick access rather than deep configuration.
4. Options UI subsystem
Files:
• options.tsx
• options.css
This is the settings page for the extension. It likely provides the same preference controls as the popup, but in a more persistent and full-page form. In extension architecture terms, this is the “configuration surface” for settings that must survive browser restarts.
5. Shared assets and type support
Files:
• assets/
• global.d.ts
assets/ contains packaged static resources such as the extension icon and other visual assets referenced by the UI or manifest.
global.d.ts indicates shared type declarations for the TypeScript build, likely used to satisfy Plasmo/browser-extension globals and shared module typings.
Important architectural boundaries
Extension-internal vs host-page boundary
The biggest boundary is between the extension and the websites it augments:
• Host pages: Goodreads and Hardcover book pages
• Extension code: content script, popup, options, background
Only the content script touches the host page DOM. The popup and options pages do not modify the site directly; they communicate through extension APIs.
UI vs logic boundary
The repo separates presentation from behavior:
• .tsx files: React UI surfaces (popup.tsx, options.tsx)
• .ts files: browser/extension logic (background.ts, content.ts)
CSS is kept alongside each surface, which makes the architecture easy to map:
• content.css for injected page UI
• popup.css for the extension popup
• options.css for the options page
Persistent state boundary
User preferences are stored locally using the extension storage permission. The README explicitly says the extension stores only source toggle preferences locally and collects/transmits no user data.
That means the persistent state is limited to:
• enabled/disabled sources
• possibly any future preferences added through the options page
Data flow
A typical end-to-end flow looks like this:
1. User opens a Goodreads or Hardcover book page.
2. The content script activates because the URL matches the supported patterns.
3. The script extracts the book title or relevant metadata from the page.
4. It consults stored preferences to determine which sources are enabled.
5. It renders source badges directly into the page.
6. A click on a badge sends the user to the corresponding external source search/result page.
A second flow concerns settings:
1. User opens the popup or options page.
2. The React UI shows source toggle controls.
3. The user changes preferences.
4. The new settings are stored locally.
5. The content script uses those settings the next time it renders badges, and possibly updates live via messaging.
Technologies and how they shape the architecture
Plasmo 0.90.5
Plasmo provides the MV3 extension scaffolding and entry-point conventions. This is why the repository is organized around named files like background.ts, content.ts, popup.tsx, and options.tsx rather than a custom build pipeline.
TypeScript 5.3.3
TypeScript is used across the extension, which implies:
• shared typing between surfaces
• safer message/storage contracts
• clearer separation of concerns for browser APIs
React
Only the popup surface is explicitly called out as React in the README, which suggests the richer UI is implemented there, while the content script may be more DOM-oriented.
Anime.js v4
The README mentions animated UI. This affects the user-facing surfaces, likely the injected badges or popup interactions, but it does not change the core data flow.
MV3 for Chrome and Firefox
This is a browser extension architecture, not a web app or server app. The presence of MV3 means:
• background logic runs as a service worker
• page interaction happens through content scripts
• permissions are declarative and host-scoped
Repository-level deployment/tooling
• package.json, pnpm-lock.yaml, package-lock.json: package management and dependency locking
• .github/workflows/submit.yml: automation for submission/release-related tasks, likely tied to extension publishing
• .prettierrc.mjs: formatting
• tsconfig.json: TypeScript build configuration
• .gitignore: standard repo hygiene
Summary architecture
At a diagram level, GoodLib should be drawn as:
• A browser extension shell built with Plasmo/MV3
• One content-script lane into Goodreads/Hardcover pages
• One background service worker coordinating state and messaging
• Two extension UI surfaces: popup and options
• Local-only storage for source toggles
• External navigation targets for Anna’s Archive, Z-Library, and Project Gutenberg
The key architectural idea is that the extension does not scrape or proxy through a server. It reads page context in the browser, combines it with local preferences, and renders links that take the user directly to external source pages.
Main entry points: content.ts Content script · background.ts Background · popup.tsx Popup · options.tsx Options
Components 19
Extension runtime
Browser-executed MV3 surfaces and the local state they share.
- Background · Central extension worker for shared orchestration, messaging, and storage coordination.
background.ts - Content script · Detects supported book pages, reads page context, and injects source badges into the host DOM.
content.ts - Content styles · Styling for the badges and page-integrated UI injected by the content script.
content.css - Local prefs · Persisted source-toggle preferences stored locally in the browser.
Extension UI
User-facing surfaces for quick toggles and persistent settings.
- Popup · Quick extension-action UI for toggling which sources are active.
popup.tsx - Popup styles · Styling for the popup surface.
popup.css - Options · Persistent configuration page for source and preference controls.
options.tsx - Options styles · Styling for the options surface.
options.css - Source toggles · Enabled/disabled source selections shared by popup, options, and content rendering.
Shared assets
Static assets and type declarations used across the extension.
Tooling
Repository-level build, formatting, and release automation.
- Plasmo MV3 · Extension scaffolding and entry-point conventions for the browser surfaces.
package.json - Workflow · Repository automation for submission or release-related tasks.
.github/workflows/submit.yml - TypeScript config · TypeScript compiler and project configuration.
tsconfig.json - Format config · Repository formatting configuration.
.prettierrc.mjs
Other components
- GoodLib · Client-side browser extension that injects book-source links into supported reading sites.
- Goodreads · Supported host page where the extension can inject source badges.
- Hardcover · Supported host page where the extension can inject source badges.
- Book sources · External destinations opened from badges: Anna’s Archive, Z-Library, and Project Gutenberg.
Connections 24
- GoodLib → Plasmo MV3: built with · Repository structure follows Plasmo's extension entry-point model.
- GoodLib → Background: contains · Background service worker is one of the main runtime surfaces.
- GoodLib → Content script: contains · Content script is the page-integrated runtime surface.
- GoodLib → Popup: contains · Popup provides quick extension controls.
- GoodLib → Options: contains · Options page provides persistent settings.
- Background → Local prefs: reads/writes · Background coordinates persisted extension preferences.
- Popup → Source toggles: edits · Popup changes which book sources are enabled.
- Options → Source toggles: edits · Options page exposes the same persistent preferences.
- Source toggles → Local prefs: persists to · Source-toggle state is stored locally in extension storage.
- Content script → Source toggles: consults · Content rendering uses the current source-toggle settings.
- Content script → Goodreads: injects into · Runs on supported Goodreads pages.
- Content script → Hardcover: injects into · Runs on supported Hardcover pages.
- Content script → Book sources: opens links · Badge clicks navigate the user to external book-source pages.
- Content script → Content styles: styles with · Injected page UI is styled separately from logic.
- Popup → Popup styles: styles with · Popup presentation is kept in its own stylesheet.
- Options → Options styles: styles with · Options page presentation is kept in its own stylesheet.
- Background → Popup: messages · Background serves as a coordination point for extension UI surfaces.
- Background → Options: messages · Background can coordinate settings updates and cross-surface state.
- Background → Content script: messages · Background can relay shared state to the page-integrated script.
- GoodLib → Assets: bundles · Static assets are packaged with the extension.
- GoodLib → Globals: uses · Shared declaration file supports TypeScript compilation.
- GoodLib → Workflow: automated by · Repository includes workflow automation.
- GoodLib → TypeScript config: configured by · TypeScript compilation is defined at the repository level.
- GoodLib → Format config: formatted by · Repository formatting is defined separately.