# lxieyang/chrome-extension-boilerplate-react architecture

> Architecture diagram of the GitHub repository lxieyang/chrome-extension-boilerplate-react, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/lxieyang/chrome-extension-boilerplate-react
- Repository: https://github.com/lxieyang/chrome-extension-boilerplate-react

## Overview

##### Project type & purpose
- This is a Chrome Extension (Manifest V3) boilerplate built with React 18 and Webpack 5.
- It supplies multiple extension entry points (popup, options page, new tab, devtools panel, background service worker, content script, in-extension panel) all bundled via Webpack.

A. Developer & Build Pipeline (local machine)
- Node.js & npm scripts (`package.json`)
- Webpack config (`webpack.config.js`) driving:
- Multiple entry points: popup, options, newtab, background, content, devtools, panel
- React Refresh & HMR in dev (`react-refresh-webpack-plugin`)
- Production bundling (`npm run build` → `build/` folder)
- Utility scripts under `utils/`:
- `build.js` (custom build orchestration)
- `webserver.js` (dev server)
- `env.js` (env var injection)
B. Build Output (`build/` folder)
- `manifest.json` (extension manifest)
- Bundled JS/CSS for each entry
C. Runtime contexts inside Chrome
1. Service Worker (Background)
- Source: `src/pages/Background/index.js`
- Managed by MV3; event-driven, listens to `chrome.runtime.onMessage`
2. Content Script
- Source: `src/pages/Content/index.js` + `modules/print.js`
- Injected into web pages via `content_scripts` in `manifest.json`
3. Popup UI
- Source: `src/pages/Popup/*.jsx`, `index.html`
4. Options Page
- Source: `src/pages/Options/*.tsx`, `index.html`
- Configurable settings UI
5. New Tab Override
- Source: `src/pages/Newtab/*.jsx`, `index.html`
- Replaces browser’s new tab page
6. DevTools Panel
- Source: `src/pages/Devtools/index.html` + `index.js`
- Embedded in Chrome DevTools via `devtools_page` manifest key
7. In-Page Panel
- Source: `src/pages/Panel/*.tsx`, `index.html`
- A sidebar/panel inside the browser UI or a host page
D. Shared code & assets
- React “Greetings” container (`src/containers/Greetings/Greetings.jsx`)
- Global styles, images (`src/assets/img`)
- TypeScript config (`tsconfig.json`) for Options & Panel

##### Architectural patterns & principles
- Modular multi-entry bundling: each extension page gets its own bundle
- MV3 event-driven background service worker instead of persistent background page
- Separation of concerns: UI pages (React) vs. background logic (vanilla JS service worker) vs. content scripts
- HMR in dev environment; full static build in production
- Type-safe pages (Options/Panel) via TypeScript

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Build & Packaging Lane
    subgraph "Build & Packaging" 
        direction TB
        pkg["package.json"]:::build
        wp["webpack.config.js"]:::build
        bld["utils/build.js"]:::build
        ws["utils/webserver.js"]:::build
        env["utils/env.js"]:::build
    end
    pkg --> wp
    wp --> bld
    wp --> ws
    wp --> env

    %% Shared Code & Assets
    subgraph "Shared Code & Assets"
        direction TB
        greet["Greetings Container\nsrc/containers/Greetings/Greetings.jsx"]:::shared
        assetsShared["Images\nsrc/assets/img"]:::shared
        ts["tsconfig.json"]:::shared
    end

    %% Build Output
    subgraph "Build Output" 
        direction TB
        manifest["manifest.json"]:::output
        bundles["JS/CSS Bundles"]:::output
        assets["Static Assets"]:::output
    end
    bld --> manifest
    bld --> bundles
    bld --> assets

    %% Chrome Runtime Lane
    subgraph "Chrome Extension" 
        direction TB
        sw["Service Worker\nsrc/pages/Background/index.js"]:::runtime
        cs["Content Script\nsrc/pages/Content/index.js\n+ modules/print.js"]:::runtime
        popup["Popup UI\nsrc/pages/Popup/*"]:::runtime
        options["Options Page\nsrc/pages/Options/*"]:::runtime
        newtab["New Tab Override\nsrc/pages/Newtab/*"]:::runtime
        devtools["DevTools Panel\nsrc/pages/Devtools/*"]:::runtime
        panel["In-Page Panel\nsrc/pages/Panel/*"]:::runtime
        storage["chrome.storage"]:::storage
    end

    %% Manifest links
    manifest --> sw
    manifest --> cs
    manifest --> popup
    manifest --> options
    manifest --> newtab
    manifest --> devtools
    manifest --> panel

    %% Shared dependencies
    greet -.-> popup
    greet -.-> options
    greet -.-> newtab
    greet -.-> panel
    assetsShared -.-> popup
    assetsShared -.-> options
    assetsShared -.-> newtab
    assetsShared -.-> panel
    ts -.-> options
    ts -.-> panel

    %% Runtime interactions
    popup -->|"chrome.runtime.sendMessage"| sw
    options -->|"chrome.runtime.sendMessage"| sw
    newtab -->|"chrome.runtime.sendMessage"| sw
    panel -->|"chrome.runtime.sendMessage"| sw
    cs <-->|"chrome.runtime.sendMessage/onMessage"| sw
    devtools -->|"chrome.devtools messaging"| sw
    popup -->|"read/write"| storage
    options -->|"read/write"| storage
    newtab -->|"read/write"| storage
    panel -->|"read/write"| storage
    sw -->|"read/write"| storage

    %% Click Events
    click pkg "https://github.com/lxieyang/chrome-extension-boilerplate-react/blob/master/package.json"
    click wp "https://github.com/lxieyang/chrome-extension-boilerplate-react/blob/master/webpack.config.js"
    click bld "https://github.com/lxieyang/chrome-extension-boilerplate-react/blob/master/utils/build.js"
    click ws "https://github.com/lxieyang/chrome-extension-boilerplate-react/blob/master/utils/webserver.js"
    click env "https://github.com/lxieyang/chrome-extension-boilerplate-react/blob/master/utils/env.js"
    click manifest "https://github.com/lxieyang/chrome-extension-boilerplate-react/blob/master/src/manifest.json"
    click greet "https://github.com/lxieyang/chrome-extension-boilerplate-react/blob/master/src/containers/Greetings/Greetings.jsx"
    click assetsShared "https://github.com/lxieyang/chrome-extension-boilerplate-react/tree/master/src/assets/img"
    click sw "https://github.com/lxieyang/chrome-extension-boilerplate-react/blob/master/src/pages/Background/index.js"
    click cs "https://github.com/lxieyang/chrome-extension-boilerplate-react/blob/master/src/pages/Content/index.js"
    click cs "https://github.com/lxieyang/chrome-extension-boilerplate-react/blob/master/src/pages/Content/modules/print.js"
    click popup "https://github.com/lxieyang/chrome-extension-boilerplate-react/blob/master/src/pages/Popup/index.html"
    click popup "https://github.com/lxieyang/chrome-extension-boilerplate-react/blob/master/src/pages/Popup/Popup.jsx"
    click popup "https://github.com/lxieyang/chrome-extension-boilerplate-react/blob/master/src/pages/Popup/index.jsx"
    click popup "https://github.com/lxieyang/chrome-extension-boilerplate-react/blob/master/src/pages/Popup/Popup.css"
    click popup "https://github.com/lxieyang/chrome-extension-boilerplate-react/blob/master/src/pages/Popup/index.css"
    click options "https://github.com/lxieyang/chrome-extension-boilerplate-react/blob/master/src/pages/Options/index.html"
    click options "https://github.com/lxieyang/chrome-extension-boilerplate-react/blob/master/src/pages/Options/Options.tsx"
    click options "https://github.com/lxieyang/chrome-extension-boilerplate-react/blob/master/src/pages/Options/index.jsx"
    click options "https://github.com/lxieyang/chrome-extension-boilerplate-react/blob/master/src/pages/Options/Options.css"
    click options "https://github.com/lxieyang/chrome-extension-boilerplate-react/blob/master/src/pages/Options/index.css"
    click newtab "https://github.com/lxieyang/chrome-extension-boilerplate-react/blob/master/src/pages/Newtab/index.html"
    click newtab "https://github.com/lxieyang/chrome-extension-boilerplate-react/blob/master/src/pages/Newtab/Newtab.jsx"
    click newtab "https://github.com/lxieyang/chrome-extension-boilerplate-react/blob/master/src/pages/Newtab/index.jsx"
    click newtab "https://github.com/lxieyang/chrome-extension-boilerplate-react/blob/master/src/pages/Newtab/Newtab.css"
    click newtab "https://github.com/lxieyang/chrome-extension-boilerplate-react/blob/master/src/pages/Newtab/index.css"
    click newtab "https://github.com/lxieyang/chrome-extension-boilerplate-react/blob/master/src/pages/Newtab/Newtab.scss"
    click devtools "https://github.com/lxieyang/chrome-extension-boilerplate-react/blob/master/src/pages/Devtools/index.html"
    click devtools "https://github.com/lxieyang/chrome-extension-boilerplate-react/blob/master/src/pages/Devtools/index.js"
    click panel "https://github.com/lxieyang/chrome-extension-boilerplate-react/blob/master/src/pages/Panel/index.html"
    click panel "https://github.com/lxieyang/chrome-extension-boilerplate-react/blob/master/src/pages/Panel/Panel.tsx"
    click panel "https://github.com/lxieyang/chrome-extension-boilerplate-react/blob/master/src/pages/Panel/index.jsx"
    click panel "https://github.com/lxieyang/chrome-extension-boilerplate-react/blob/master/src/pages/Panel/Panel.css"
    click panel "https://github.com/lxieyang/chrome-extension-boilerplate-react/blob/master/src/pages/Panel/index.css"
    click ts "https://github.com/lxieyang/chrome-extension-boilerplate-react/blob/master/tsconfig.json"

    %% Styles
    classDef build fill:#D0EBFF,stroke:#1C7ED6,color:#1C7ED6
    classDef shared fill:#E7F5FF,stroke:#339AF0,color:#1C7ED6
    classDef output fill:#FFF3BF,stroke:#F08C00,color:#F08C00
    classDef runtime fill:#D3F9D8,stroke:#2F9E44,color:#2F9E44
    classDef storage fill:#FFE3E3,stroke:#C92A2A,color:#C92A2A
```
