# preactjs/preact-iso architecture

> Architecture diagram of the GitHub repository preactjs/preact-iso, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/preactjs/preact-iso
- Repository: https://github.com/preactjs/preact-iso

## Overview

##### Project type and purpose
- This is an open‑source library (not a standalone app) that provides isomorphic (SSR+CSR) async utilities for Preact—namely `lazy`, `prerender`, `hydrate`, routing, and error boundaries.
- It is intended to plug into Preact applications or build tools (e.g. Vite with `@preact/preset-vite`) to enable code‑splitting, progressive hydration, async routing, and prerendering.

##### File structure
Top level:
- package.json, ts/jsconfigs, CI and metadata (.github/, LICENSE, etc.)
- src/ → implementation of each export (lazy.js, router.js, hydrate.js, prerender.js, internal.js, plus TypeScript definitions)
- test/ → unit tests exercising each feature in both browser and Node contexts
- web-test-runner.config.js → test runner setup

Patterns & clues:
- Each feature is factored into its own module in src/
- `internal.js` likely holds shared utilities for promise‑suspense integration
- No “frontend/backend” – it’s a library, so core components and utilities

##### README for insights
- Confirms the main exports: `lazy()`, `prerender()`, `hydrate()`, `<Router>`, `<LocationProvider>`, `<ErrorBoundary>`, and hooks `useLocation`, `useRoute`.
- Describes how client hydration and server prerendering interact.
- Mentions dependency on `preact-render-to-string` for SSR.
- Shows code examples with dynamic `import()` and async routing behavior.

a. Main components
- Consumer App (user’s Preact application)
- LocationProvider / Context Layer
- Router & Route Matching Engine
- Lazy Loader (dynamic import wrapper + Suspense boundary)
- ErrorBoundary
- CSR Hydrator (`hydrate`)
- SSR Prerenderer (`prerender` → preact‑render‑to‑string)
- Shared Internal Utilities
- External Dependencies (Preact core, dynamic import mechanism, preact‑render‑to‑string)

b. Relationships & interactions
1. Consumer App imports `preact‑iso` exports.
2. At build/SSR time:
– `prerender()` invokes internal utilities + `preact-render-to-string` to produce HTML + link list.
3. At runtime in browser:
– `hydrate()` checks for existing SSR markup → if present, calls Preact’s `hydrate`, else does fresh render.
– `<LocationProvider>` sets up URL context.
– `<Router>` consumes context, matches routes using router-engine.
– When a routed component is a `lazy()` wrapper, it suspends (throws a Promise) until the dynamic import resolves, enabling progressive hydration or seamless transitions.
– `<ErrorBoundary>` wraps around to catch rendering or loading errors.

c. Architectural patterns/design principles
- Modular single‑responsibility: each feature is in its own module.
- Suspense‑style async handling: `lazy()` components throw Promises for integration with SSR and CSR lifecycles.
- Context API for routing state (LocationProvider + Router).
- Clear separation of SSR vs CSR utilities (`prerender` vs `hydrate`).
- Hooks for location and route introspection.

d. Key technologies & libraries
- Preact core (vnode creation, hydrate/render)
- preact‑render‑to‑string (SSR)
- Dynamic `import()` for code splitting
- Web‑Test‑Runner for tests

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Consumer Application
    subgraph "Consumer Application"
        CA["Consumer App"]:::api
    end

    %% Library Modules
    subgraph "Library Modules"
        INDX["Public API Entry (src/index.js)"]:::api
        HYD["CSR Hydrator (hydrate())"]:::csr
        PRR["SSR Prerenderer (prerender())"]:::ssr
        RTL["Router & Context (Router, LocationProvider)"]:::routing
        RE["Route Matching Engine"]:::routing
        LZY["Lazy Loader (lazy())"]:::csr
        ERR["ErrorBoundary"]:::routing
        INT["Internal Utilities"]:::util
    end

    %% External Dependencies
    subgraph "External Dependencies"
        PREACT["Preact Core"]:::external
        SSRLIB["preact-render-to-string"]:::external
        DYN["Dynamic import()"]:::external
    end

    %% Connections
    CA -->|"imports public API"| INDX
    CA -->|"calls hydrate()"| HYD
    CA -->|"calls prerender()"| PRR

    INDX --> HYD
    INDX --> PRR
    INDX --> RTL
    INDX --> LZY
    INDX --> ERR

    HYD -->|"uses preact.hydrate/render"| PREACT
    PRR -->|"uses preact-render-to-string"| SSRLIB

    HYD --> INT
    PRR --> INT

    RTL --> RE
    RE --> LZY
    RTL --> ERR
    RTL --> INT

    LZY -->|"suspense promise"| INT
    LZY -->|"dynamic import"| DYN

    ERR --> INT

    %% Click Events
    click LZY "https://github.com/preactjs/preact-iso/blob/main/src/lazy.js"
    click PRR "https://github.com/preactjs/preact-iso/blob/main/src/prerender.js"
    click HYD "https://github.com/preactjs/preact-iso/blob/main/src/hydrate.js"
    click RTL "https://github.com/preactjs/preact-iso/blob/main/src/router.js"
    click INT "https://github.com/preactjs/preact-iso/blob/main/src/internal.js"
    click INDX "https://github.com/preactjs/preact-iso/blob/main/src/index.js"
    click ERR "https://github.com/preactjs/preact-iso/blob/main/src/index.js"

    %% Styles
    classDef api fill:#f9a8a8,stroke:#333,stroke-width:1px
    classDef csr fill:#a2fca2,stroke:#333,stroke-width:1px
    classDef ssr fill:#f9d2a8,stroke:#333,stroke-width:1px
    classDef routing fill:#a8d2f9,stroke:#333,stroke-width:1px
    classDef util fill:#d3a8f9,stroke:#333,stroke-width:1px
    classDef external fill:#f1f1f1,stroke:#333,stroke-width:1px
```
