# hulufei/electron-as-browser architecture

> Architecture diagram of the GitHub repository hulufei/electron-as-browser, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hulufei/electron-as-browser
- Repository: https://github.com/hulufei/electron-as-browser

## Overview

##### Project type and purpose
- This is an open-source Node module for Electron apps called “electron-as-browser.”
- It provides a BrowserLikeWindow class that you instantiate in the Electron main process to spin up a browser-style window using BrowserView, plus a pluggable control panel in the renderer process.

##### File structure
- Top level
- index.js / index.d.ts – exports the BrowserLikeWindow constructor and sets up the public API
- control.js / control.d.ts – IPC helper functions for sending browser-control commands
- useConnect.js – React hook that wraps IPC channels for control panels
- README.md, docs/ – documentation and static assets for the site
- example/ – a minimal Electron app showing how to wire up main and renderer
- babel.config.js, package.json – build and dependency definitions
- Patterns
- Main process code (index.js) instantiates BrowserWindow and BrowserViews
- Renderer code in example/renderer is a standalone UI that talks to the main process via IPC
- IPC channels for bi-directional communication of tab events and control commands

##### README for additional insights
- Features emphasize BrowserView over webview, pluggable control panel, exposed webContents and BrowserWindow, automatic resizing
- Usage section shows two distinct processes:
- Main: create BrowserLikeWindow, listen to events (‘new-tab’, ‘closed’)
- Renderer: implement control panel UI, subscribe to tabs and active-tab events via IPC or useConnect hook, send commands via functions from control.js

a. Main components
- Electron Main Process
– BrowserLikeWindow module
– Underlying Electron API: BrowserWindow + BrowserView + webContents
- Renderer Control Panel
– HTML/JS UI loaded as a BrowserView inside the same BrowserWindow
– Uses either raw ipcRenderer or useConnect hook
- Tab Content Views
– One BrowserView per tab, each with its own webContents loading external pages
- IPC Layer
– Channels for ‘control-ready’, ‘tabs-update’, ‘active-update’
– Channels for commands: sendNewTab, sendEnterURL, sendGoBack, etc.
- External Services
– Remote websites loaded in BrowserViews via HTTP/HTTPS

b. Relationships and interactions
1. On app start, main process loads controlPanel URL into a BrowserView
2. Renderer sends ‘control-ready’ to signal it’s listening
3. Main process emits ‘tabs-update’ and ‘active-update’ on state changes
4. Renderer UI dispatches commands (sendNewTab, sendReload, etc.) via ipcRenderer to main
5. Main process updates internal state, creates/destroys BrowserViews, adjusts BrowserWindow layout
6. New or switched tabs load external URLs in separate BrowserViews

c. Architectural patterns and design principles
- Event-driven architecture (IPC as the event bus)
- Separation of concerns: main process handles heavy lifting and window management; renderer handles user interface
- Pluggable UI: control panel can be any HTML/JS framework (React via useConnect or plain JS via control.js)
- Modular exports: index.js, control.js, useConnect.js as composable parts

d. Key technologies, frameworks, libraries
- Electron APIs: BrowserWindow, BrowserView, webContents, ipcMain, ipcRenderer
- Node.js module system (import/require)
- Optional React (via useConnect hook)
- Babel for transpilation

##### Detail
- Lifecycle of a tab: command → view creation → tabs-update event → view destroyed on close
- Resizing logic (main process auto-resize of views when window changes)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Subgraph: Electron Main Process
    subgraph "Electron Main Process"
        direction TB
        BLW["BrowserLikeWindow Module"]:::core
        EWin["BrowserWindow (Electron API)"]:::electron
        BViewManager["BrowserView Management"]:::electron
        IPCMain["ipcMain Channels"]:::ipc
        BLW -->|instantiates| EWin
        BLW -->|manages| BViewManager
        BViewManager -->|uses| EWin
        IPCMain -->|listens to| BViewManager
    end

    %% Subgraph: Renderer Control Panel
    subgraph "Renderer Control Panel"
        direction TB
        ControlHTML["control.html"]:::example
        ControlJSX["control.jsx"]:::example
        StyleCSS["style.css"]:::example
        UseConnect["useConnect Hook"]:::core
        ControlJS["IPC Helper Functions"]:::core
        ControlHTML -->|loads| ControlJSX
        ControlJSX -->|imports| UseConnect
        ControlJSX -->|imports| ControlJS
        ControlHTML -->|includes| StyleCSS
    end

    %% Subgraph: BrowserView Tabs
    subgraph "BrowserView Tabs"
        direction TB
        Tabs["Multiple BrowserView Instances"]:::browser
        Tabs -->|each loads| RemoteSites
    end

    %% External Web Servers
    RemoteSites["External Web Servers"]:::external

    %% Example App Integration
    subgraph "Example App"
        direction TB
        ExampleMain["example/main.js"]:::example
        ExampleMain -->|uses| BLW
        ExampleMain -->|listens to| IPCMain
        ExampleRenderer["example/renderer/control.html"]:::example
        ExampleRenderer -->|UI| ControlJSX
        ExampleRenderer -->|sends IPC| IPCMain
    end

    %% IPC Communication
    ControlJSX -->|sendNewTab, sendReload, etc.| IPCMain
    IPCMain -->|tabs-update, active-update| ControlJSX

    %% Core Library Files
    subgraph "Core Library & Config"
        direction TB
        IndexJS["index.js"]:::core
        IndexDTS["index.d.ts"]:::core
        ControlDTS["control.d.ts"]:::core
        BabelConfig["babel.config.js"]:::config
        PackageJSON["package.json"]:::config
        README["README.md"]:::docs
        DocsEntry["docs/index.html"]:::docs
        DocsAssets["docs/assets/"]:::docs
        IndexJS --> IndexDTS
        ControlJS --> ControlDTS
    end

    %% Relationships: Main Process drives Tabs
    BViewManager -->|create/destroy views| Tabs
    EWin -->|auto-resize views| BViewManager

    %% Styling classes
    classDef core fill:#D0E6FF,stroke:#0366D6,stroke-width:1px
    classDef electron fill:#FFEB99,stroke:#C68C00,stroke-width:1px
    classDef ipc fill:#E2F0D9,stroke:#3D9140,stroke-width:1px
    classDef example fill:#DFF0FF,stroke:#007ACC,stroke-width:1px
    classDef browser fill:#F0F0F0,stroke:#888888,stroke-width:1px
    classDef external fill:#EEEEEE,stroke:#AAAAAA,stroke-width:1px
    classDef config fill:#FFF0F0,stroke:#D14,stroke-width:1px
    classDef docs fill:#F9F2FF,stroke:#8E44AD,stroke-width:1px

    %% Click Events
    click BLW "https://github.com/hulufei/electron-as-browser/blob/master/index.js"
    click IndexJS "https://github.com/hulufei/electron-as-browser/blob/master/index.js"
    click IndexDTS "https://github.com/hulufei/electron-as-browser/blob/master/index.d.ts"
    click ControlJS "https://github.com/hulufei/electron-as-browser/blob/master/control.js"
    click ControlDTS "https://github.com/hulufei/electron-as-browser/blob/master/control.d.ts"
    click UseConnect "https://github.com/hulufei/electron-as-browser/blob/master/useConnect.js"
    click ExampleMain "https://github.com/hulufei/electron-as-browser/blob/master/example/main.js"
    click ControlHTML "https://github.com/hulufei/electron-as-browser/blob/master/example/renderer/control.html"
    click ControlJSX "https://github.com/hulufei/electron-as-browser/blob/master/example/renderer/control.jsx"
    click StyleCSS "https://github.com/hulufei/electron-as-browser/blob/master/example/renderer/style.css"
    click DocsEntry "https://github.com/hulufei/electron-as-browser/blob/master/docs/index.html"
    click DocsAssets "https://github.com/hulufei/electron-as-browser/tree/master/docs/assets/"
    click BabelConfig "https://github.com/hulufei/electron-as-browser/blob/master/babel.config.js"
    click PackageJSON "https://github.com/hulufei/electron-as-browser/blob/master/package.json"
    click README "https://github.com/hulufei/electron-as-browser/blob/master/README.md"
```
