# frolant/react-ssr-pack architecture

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

- Interactive diagram: https://gitdiagram.com/frolant/react-ssr-pack
- Repository: https://github.com/frolant/react-ssr-pack

## Overview

##### Project type and purpose
- This is a monorepo toolkit (“React SSR Pack”) for adding server-side rendering (SSR) to React applications with minimal extra code.
- It consists of:
- A set of reusable npm packages under `packages/` (babel-plugin, resolve-plugin, server, tools, etc.)
- An example full-stack React/Redux/Redux-Saga/Express application under `example/`
- Build and development scripts and configs at the root.

##### File structure
- Top-level:
- `packages/`: individual libraries that implement core SSR behavior, plugin replacements, server runner, utilities.
- `example/`: a standalone client+server React app demonstrating integration.
- Build/tooling configs: webpack.*, lerna.json, tsconfig.json, run.js, and `tools/`.
- `src/`: implementation files
- `README.md`: package-specific docs
- `package.json`, tsconfig
- The example app has separate entry points (`src/client.ts`, `src/server.ts`), React components, store (Redux+Saga), rendering modules (`clientAppRender`, `serverAppRender`), and webpack configs for client/server.

##### Key insights from README
- Core flow:
1) Webpack server build uses `@react-ssr-pack/babel-plugin` to intercept `useEffect`.
2) `@react-ssr-pack/resolve-plugin` redirects imports of React hooks to SSR-aware implementations.
3) At runtime, `runAppServer` (from `@react-ssr-pack/server`) spins up Express, invokes `nodeAppRender` (from `@react-ssr-pack/tools`) to render the app to string, running all server-side `useEffect` hooks to completion, populating the Redux store.
4) Final HTML with preloaded state is sent to the client.
- Client build is a normal React SPA; hydration reuses the same hooks & store logic.

##### Components
a. Main components:
- Client build pipeline (webpack → babel/ts-loader, CSS, assets → `clientAppRender` → Browser)
- Server build pipeline (webpack → babel with `babel-plugin`, resolve-plugin → `serverAppRender`)
- Express server (`runAppServer`)
- SSR runtime: `nodeAppRender` + hook registry + Redux store + Redux-Saga
- Individual packages in `packages/` (grouped by role: plugins, server, tools, utilities)
- Example app code (App, Routes, Components, Store)
- External resources: API endpoints, data services (JSON files in `resources/data`), third-party libs.
b. Relationships & interactions:
- Runtime: Express → serverAppRender → SSR tools → React → Store & Sagas → HTML → Client.
- Client: browser bootstraps via `clientAppRender`, hydrates state, runs effects normally.
- Packages: show dependencies between `babel-plugin` → `resolve-plugin` → `tools` → `server`.
c. Architectural patterns & principles:
- Monorepo managed by Lerna.
- Plugin architecture: webpack plugins & Babel plugin for hook interception.
- SSR as progressive render iterations until no new effects.
- Separation of concerns: build plugins vs. runtime server vs. client hydration.
d. Key technologies & libraries:
- Webpack (multiple configs)
- Babel (with `@react-ssr-pack/babel-plugin`)
- `@react-ssr-pack/resolve-plugin`
- Express (`runAppServer`)
- React (v18+), Redux, Redux-Saga, React Hooks (`useEffect`)
- TypeScript, Lerna, Node utilities

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Build-Time Components"
        WX["Root Webpack Configs\n(webpack.config.js/*.js)"]:::build
        BP["Babel Plugin (@react-ssr-pack/babel-plugin)"]:::build
        RP["Resolve Plugin (@react-ssr-pack/resolve-plugin)"]:::build
        WX --> BP
        WX --> RP
    end

    subgraph "Runtime Server Components"
        SR["runAppServer"]:::server
        SAR["serverAppRender"]:::server
        NAR["nodeAppRender"]:::server
        NEF["nodeUseEffect"]:::server
        NES["nodeUseState"]:::server
        SDS["stateDataService"]:::server
        EDS["effectsDataService"]:::server
        RSH["redux-saga-handlers"]:::server
        SCS["stateCacheService"]:::server
        GPUC["getServerAppPageContent"]:::server
        GSSA["getServerAppState"]:::server

        SR --> SAR
        SAR --> NAR
        NAR --> NEF
        NAR --> NES
        NAR --> SDS
        NAR --> EDS
        NAR --> RSH
        SR --> SCS
        SR --> GPUC
        SR --> GSSA
    end

    subgraph "Client Components"
        CAR["clientAppRender"]:::client
        Browser["Browser"]:::client
        CAR --> Browser
    end

    subgraph "Example Application"
        ERV["Express Entrypoint\n(example/src/server.ts)"]:::example
        RUN["runAppServer Util"]:::example
        APP["React App (App.tsx)"]:::example
        ROUTES["Routes & Pages"]:::example
        STORE["Redux Store"]:::example
        SAGAS["Redux Sagas"]:::example

        ERV --> RUN
        RUN --> SR
        APP --> SAR
        APP --> STORE
        STORE --> SAGAS
    end

    %% Connections between layers
    WX --> CAR
    WX --> SAR
    BP --> SAR
    RP --> SAR

    %% Click Events
    click BP "https://github.com/frolant/react-ssr-pack/blob/master/packages/babel-plugin/src/NodeAppRenderingBabelPlugin.js"
    click RP "https://github.com/frolant/react-ssr-pack/blob/master/packages/resolve-plugin/src/ReactSSRPackResolvePlugin.js"
    click SR "https://github.com/frolant/react-ssr-pack/blob/master/packages/server/src/index.ts"
    click SAR "https://github.com/frolant/react-ssr-pack/blob/master/example/src/renders/serverAppRender/serverAppRender.tsx"
    click NAR "https://github.com/frolant/react-ssr-pack/blob/master/packages/tools/src/nodeAppRender/nodeAppRender.ts"
    click NEF "https://github.com/frolant/react-ssr-pack/blob/master/packages/tools/src/nodeUseEffect/nodeUseEffect.ts"
    click NES "https://github.com/frolant/react-ssr-pack/blob/master/packages/tools/src/nodeUseState/nodeUseState.ts"
    click SDS "https://github.com/frolant/react-ssr-pack/blob/master/packages/tools/src/stateDataService/stateDataService.ts"
    click EDS "https://github.com/frolant/react-ssr-pack/blob/master/packages/tools/src/effectsDataService/effectsDataService.ts"
    click RSH "https://github.com/frolant/react-ssr-pack/blob/master/packages/redux-saga-handlers/src/reduxSagaHandlers.ts"
    click SCS "https://github.com/frolant/react-ssr-pack/blob/master/packages/server/src/services/stateCacheService/stateCacheService.ts"
    click GPUC "https://github.com/frolant/react-ssr-pack/blob/master/packages/server/src/utils/getServerAppPageContent/getServerAppPageContent.ts"
    click GSSA "https://github.com/frolant/react-ssr-pack/blob/master/packages/server/src/utils/getServerAppState/getServerAppState.ts"
    click CAR "https://github.com/frolant/react-ssr-pack/blob/master/example/src/renders/clientAppRender/clientAppRender.tsx"
    click ERV "https://github.com/frolant/react-ssr-pack/blob/master/example/src/server.ts"
    click RUN "https://github.com/frolant/react-ssr-pack/blob/master/example/src/utils/runAppServer/runAppServer.ts"
    click APP "https://github.com/frolant/react-ssr-pack/blob/master/example/src/components/App/App.tsx"
    click ROUTES "https://github.com/frolant/react-ssr-pack/tree/master/example/src/pages/*"
    click STORE "https://github.com/frolant/react-ssr-pack/blob/master/example/src/store/index.ts"
    click SAGAS "https://github.com/frolant/react-ssr-pack/blob/master/example/src/store/sagas.ts"

    %% Styles
    classDef build fill:#E3F2FD,stroke:#90CAF9;
    classDef server fill:#E8F5E9,stroke:#A5D6A7;
    classDef client fill:#FFF3E0,stroke:#FFCC80;
    classDef example fill:#F3E5F5,stroke:#CE93D8;
```
