# adeeshsharma/react-single-spa-widget architecture

> Architecture diagram of the GitHub repository adeeshsharma/react-single-spa-widget, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/adeeshsharma/react-single-spa-widget
- Repository: https://github.com/adeeshsharma/react-single-spa-widget

## Overview

##### Project type and purpose
- This is a front-end “micro-frontend” style project composed of two parts:
a) **carousel-widget** – a standalone React widget/library packaged as a UMD bundle (built with Webpack/Vite).
b) **host-app** – a React application (Vite-powered) that dynamically loads and mounts the UMD widget at runtime (per the linked Single-SPA approach).

##### File structure
- Top-level directories:
- carousel-widget/ – source (`src/`), styles, bundler configs (`webpack.config.cjs`, `vite.config.js`), build output (public/), entry points (`index.js`, `index.html`).
- host-app/ – application source (`src/`), HTML shell (`index.html`), build config (`vite.config.js`), and dynamic loader logic in `App.jsx`.
- Config files: ESLint in both, package.json, bundler configs.
- Patterns: separation of library vs. consumer, use of UMD module for runtime integration.

##### README for additional insights
- The README links to a blog detailing building a standalone React widget (UMD) and loading it into another React app using Single-SPA.
- This confirms the architecture is a micro-frontend/widget integration scenario, not a monolith.

a. Main components:
- Developer Workstations (for widget & host)
- carousel-widget Build Pipeline
– Source code (Carousel.js, CSS)
– Bundlers: Webpack &/or Vite
– Output: UMD bundle (JS), CSS
– CDN or local dev-server
- host-app Build Pipeline
– Source (App.jsx, main.jsx)
– Vite dev server / production build
– index.html shell
- Runtime Environment (Browser)
– host-app container loads its own bundle
– Dynamically injects `<script>` tag pointing to carousel-widget UMD
– Mount point DOM node (e.g. `
`)
- External dependencies
– React, ReactDOM (peer-loaded by host or bundled by widget)

b. Relationships and interactions:
1. Developers → run `npm run build` in carousel-widget → Bundler outputs `carousel.umd.js` → published/served.
2. Developers → serve or build host-app → host code references the remote UMD URL.
3. Browser loads host-app code → at mount time, host injects `<script src="...carousel.umd.js">` → once loaded, calls widget’s UMD register function → widget mounts into the host’s DOM.
4. CSS styling loaded either via widget’s CSS file or inlined.

c. Architectural patterns / design principles:
- Micro-frontend / widget as a standalone module
- UMD packaging for broad compatibility
- Dynamic script injection (Single-SPA style)
- Clear separation of concerns: widget logic vs. host orchestration
- Peer dependencies (React) to avoid duplication

d. Key technologies / frameworks:
- React / ReactDOM
- Webpack (for UMD output)
- Vite (for both widget dev mode and host dev mode)
- Single-SPA dynamic loading pattern
- NPM scripts / package.json orchestrators

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Developer Workstations
    Dev["Developer Workstations"]:::external

    %% Build Pipelines
    subgraph "carousel-widget Build Pipeline"
        direction TB
        CW_SRC["Carousel.js"]:::source
        CW_CSS["carousel.css"]:::source
        CW_INDEX["index.js"]:::source
        CW_HTML["index.html"]:::source
        CW_WP["webpack.config.cjs"]:::config
        CW_VITE["vite.config.js"]:::config
        CW_BUNDLE["UMD Bundle"]:::artifact
        CW_PUBLIC["Public Assets"]:::artifact
    end

    subgraph "host-app Build Pipeline"
        direction TB
        HA_APP["App.jsx"]:::source
        HA_MAIN["main.jsx"]:::source
        HA_HTML["index.html"]:::source
        HA_VITE["vite.config.js"]:::config
        HA_BUNDLE["Host Static Assets"]:::artifact
    end

    %% CDN / Dev Servers
    CDN["CDN / Dev Server"]:::runtime
    Server["Vite Dev Server"]:::runtime

    %% Runtime Environment
    subgraph "Runtime (Browser)"
        direction TB
        Host_HTML["host-app/index.html"]:::artifact
        Host_JS["host-app Bundle.js"]:::artifact
        ScriptInject["Script Injection"]:::runtime
        WidgetRegister["widget.register()"]:::runtime
        WidgetMount["<div id='widget-root'>"]:::runtime
        ReactPeer["React / ReactDOM (Peer)"]:::external
    end

    %% Connections - Build Flow Carousel
    Dev -->|"npm run build"| CW_SRC
    CW_SRC --> CW_WP
    CW_CSS --> CW_WP
    CW_INDEX --> CW_VITE
    CW_WP --> CW_BUNDLE
    CW_VITE --> CW_BUNDLE
    CW_BUNDLE --> CW_PUBLIC
    CW_PUBLIC --> CDN

    %% Connections - Build Flow Host
    Dev -->|"npm run dev / build"| HA_APP
    HA_APP --> HA_VITE
    HA_MAIN --> HA_VITE
    HA_HTML --> HA_VITE
    HA_VITE --> HA_BUNDLE
    HA_BUNDLE --> Server

    %% Runtime Flow
    CDN -->|provides script| ScriptInject
    Server -->|serves host bundle| Host_HTML
    Host_HTML --> Host_JS
    Host_JS -->|inject carousel-widget script| ScriptInject
    ScriptInject --> WidgetRegister
    WidgetRegister --> WidgetMount
    ReactPeer -.->|peer dependency| WidgetRegister

    %% Click Events
    click CW_SRC "https://github.com/adeeshsharma/react-single-spa-widget/blob/main/carousel-widget/src/Carousel.js"
    click CW_CSS "https://github.com/adeeshsharma/react-single-spa-widget/blob/main/carousel-widget/src/carousel.css"
    click CW_INDEX "https://github.com/adeeshsharma/react-single-spa-widget/blob/main/carousel-widget/src/index.js"
    click CW_HTML "https://github.com/adeeshsharma/react-single-spa-widget/blob/main/carousel-widget/index.html"
    click CW_WP "https://github.com/adeeshsharma/react-single-spa-widget/blob/main/carousel-widget/webpack.config.cjs"
    click CW_VITE "https://github.com/adeeshsharma/react-single-spa-widget/blob/main/carousel-widget/vite.config.js"
    click CW_PUBLIC "https://github.com/adeeshsharma/react-single-spa-widget/tree/main/carousel-widget/public/"
    click HA_APP "https://github.com/adeeshsharma/react-single-spa-widget/blob/main/host-app/src/App.jsx"
    click HA_MAIN "https://github.com/adeeshsharma/react-single-spa-widget/blob/main/host-app/src/main.jsx"
    click HA_HTML "https://github.com/adeeshsharma/react-single-spa-widget/blob/main/host-app/index.html"
    click HA_VITE "https://github.com/adeeshsharma/react-single-spa-widget/blob/main/host-app/vite.config.js"
    click HA_BUNDLE "https://github.com/adeeshsharma/react-single-spa-widget/tree/main/host-app/public/"

    %% Styles
    classDef source fill:#D6E9FF,stroke:#4A90E2,color:#000
    classDef config fill:#FFE6A7,stroke:#E2A23F,color:#000
    classDef artifact fill:#DFF7D8,stroke:#4BB543,color:#000
    classDef runtime fill:#F0F0F0,stroke:#999,color:#000
    classDef external fill:#FBEFF2,stroke:#D14D72,color:#000
```
