# inokawa/virtua architecture

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

- Interactive diagram: https://gitdiagram.com/inokawa/virtua
- Repository: https://github.com/inokawa/virtua

## Overview

##### Project type and purpose
- This is an open-source, framework-agnostic UI library (“virtua”) that provides zero-config virtual scrolling features (lists and grids) for multiple front-end frameworks: React, Vue, Solid, and Svelte.
- It consists of a “core” engine handling virtualization logic (measurement, scrolling, caching) and thin “adapter” layers that expose the core API to each framework.

##### File structure
- Top-level:
- src/core: core engine modules
– cache.ts, store.ts: caching and state management
– resizer.ts, scroller.ts: measurement and scroll position handling
– utils.ts, environment.ts: cross-browser abstractions, utilities
- src/{react,vue,solid,svelte}: adapter code
– Components (e.g., VList.tsx, Virtualizer.tsx)
– Hooks/utility files (e.g., useChildren.ts, utils.ts)
– Type definitions for each framework
- docs/: API references organized per framework
- stories/: Storybook examples per framework
- scripts/, rollup.config.mjs, package.json: build, publish, CI
- e2e/, vitest.config.ts, playwright.config.ts: QA and testing pipelines

##### README for additional insights
- Describes core features: zero-config, dynamic size, horizontal/vertical scrolling, reverse/infinite scroll, SSR support.
- Shows that core virtualization engine must integrate with ResizeObserver, manage overscan, dynamic measurements.
- Lists framework-specific exports: VList, Virtualizer, WindowVirtualizer, experimental_VGrid.

##### Main components and their interactions
a. Core Engine (src/core)
- Cache module: Memoize item sizes by key
- Store module: State container for scroll offset, viewport size, items
- Resizer module: Wraps ResizeObserver for dynamic measurement
- Scroller module: Manages scroll events and virtual window calculation
- Utils & Environment: Browser abstractions (isSSR, global scope), shared helpers
b. Adapter Layer (src/react, src/vue, src/solid, src/svelte)
- Framework components that import core methods
- Core state to framework rendering (hooks in React, reactive stores in Solid, Svelte, Vue)
- Provide API surface: VList, Virtualizer, WindowVirtualizer, experimental_VGrid
c. Build Pipeline
- Rollup config: bundle core + adapters into ESM/CJS, define package.json “exports”
- Babel/TypeScript: Transpile for each framework, generate type declarations
- Scripts: generate docs (typedoc), run tests (vitest, Playwright), publish to npm
d. Documentation & Examples
- docs/ folder: Markdown API reference for core and adapters
- stories/: Storybook setups per framework
- e2e/: end-to-end tests using Playwright for critical scenarios

##### Architectural patterns and design principles
- Separation of concerns: core virtualization logic is framework-agnostic; adapters are thin layers.
- Modular design: each core feature (cache, scrolling, resizing) is isolated in its own module.
- Single source of truth: store module centralizes state; adapters subscribe to it.
- Pluggable: experimental grid feature as a feature flag, new adapters can be added.
- Test-first & CI: vitest unit tests for core and adapters, Playwright e2e tests, Storybook demos.

##### Detail without overthinking
- Adapter files logically (e.g., React hooks vs. React components).
- Critical parts: build, docs, tests, CI, core internals, adapter externals.

##### Final checklist
- Clear component labels
- Annotations on the core part showing submodules and their interactions
- Title: “virtua System Architecture”

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Core Engine
    subgraph "Core Engine"
        direction TB
        CoreIndex["index.ts"] 
        CoreTypes["types.ts"]
        CoreUtils["utils.ts"]
        CoreEnv["environment.ts"]
        CoreCache["cache.ts"]
        CoreStore["store.ts"]
        CoreResizer["resizer.ts"]
        CoreScroller["scroller.ts"]
    end

    %% Internal Core Flow
    CoreResizer -->|"measures sizes"| CoreCache
    CoreCache -->|"stores item sizes"| CoreStore
    CoreStore -->|"state updates"| CoreScroller
    CoreScroller -->|"calculates window"| CoreStore
    CoreStore -->|"provides state"| CoreIndex

    %% Adapters
    subgraph "React Adapter" 
        direction TB
        ReactIndex["index.tsx"] 
        ReactTypes["types.ts"]
        ReactVList["VList.tsx"]
        ReactVirtualizer["Virtualizer.tsx"]
        ReactWindow["WindowVirtualizer.tsx"]
        ReactVGrid["VGrid.tsx"]
        ReactHooks["useChildren.ts"] 
        ReactUtils["utils.ts"]
    end

    subgraph "Vue Adapter"
        direction TB
        VueIndex["index.tsx"]
        VueVList["VList.tsx"]
        VueVirtualizer["Virtualizer.tsx"]
        VueWindow["WindowVirtualizer.tsx"]
        VueListItem["ListItem.tsx"]
        VueUtils["utils.ts"]
    end

    subgraph "Solid Adapter"
        direction TB
        SolidIndex["index.ts"]
        SolidTypes["types.ts"]
        SolidVList["VList.tsx"]
        SolidVirtualizer["Virtualizer.tsx"]
        SolidWindow["WindowVirtualizer.tsx"]
        SolidListItem["ListItem.tsx"]
        SolidUtils["utils.ts"]
    end

    subgraph "Svelte Adapter"
        direction TB
        SvelteIndex["index.ts"]
        SvelteTypes["types.ts"]
        SvelteVList["VList.svelte"]
        SvelteVirtualizer["Virtualizer.svelte"]
        SvelteWindow["WindowVirtualizer.svelte"]
        SvelteListItem["ListItem.svelte"]
        SvelteUtils["utils.ts"]
    end

    %% Core to Adapters
    CoreIndex -->|"exports core API"| ReactIndex
    CoreIndex -->|"exports core API"| VueIndex
    CoreIndex -->|"exports core API"| SolidIndex
    CoreIndex -->|"exports core API"| SvelteIndex

    %% Adapters to Runtimes (external)
    ReactIndex -->|"renders UI"| ReactRuntime{{"React Runtime"}}:::external
    VueIndex -->|"renders UI"| VueRuntime{{"Vue Runtime"}}:::external
    SolidIndex -->|"renders UI"| SolidRuntime{{"Solid Runtime"}}:::external
    SvelteIndex -->|"renders UI"| SvelteRuntime{{"Svelte Runtime"}}:::external

    %% Build Pipeline
    subgraph "Build Tools & Pipeline"
        direction TB
        Rollup["rollup.config.mjs"] 
        Scripts["scripts/"] 
        PackageJSON["package.json"]
        BuildArtifact[/Published Package/] 
    end

    Rollup -->|bundles| BuildArtifact
    Scripts -->|build scripts| BuildArtifact
    PackageJSON -->|exports field| BuildArtifact

    %% Documentation & Examples
    subgraph "Docs & Examples"
        direction TB
        APIDocs["docs/API.md"]
        ReactDocs["docs/react/"] 
        VueDocs["docs/vue/"]
        SolidDocs["docs/solid/"]
        SvelteDocs["docs/svelte/"]
        Stories["stories/"]
    end

    %% Testing & CI
    subgraph "Testing & CI"
        direction TB
        Vitest["vitest.config.ts"] 
        PlaywrightConfig["playwright.config.ts"]
        E2ETests["e2e/"] 
        Storybook["storybook"] 
        CI["GitHub Actions"] 
    end

    CI -->|runs| Vitest
    CI -->|runs| PlaywrightConfig
    CI -->|runs| E2ETests
    CI -->|runs| Storybook

    Vitest -->|tests| CoreIndex
    Vitest -->|tests| ReactIndex
    PlaywrightConfig -->|e2e| E2ETests

    %% External APIs
    ResizeObserverAPI{{"ResizeObserver API"}}:::external
    BrowserEvents{{"Browser Events"}}:::external

    CoreResizer -->|"uses"| ResizeObserverAPI
    CoreScroller -->|"listens to"| BrowserEvents

    %% Click Events
    click CoreCache "https://github.com/inokawa/virtua/blob/main/src/core/cache.ts"
    click CoreStore "https://github.com/inokawa/virtua/blob/main/src/core/store.ts"
    click CoreResizer "https://github.com/inokawa/virtua/blob/main/src/core/resizer.ts"
    click CoreScroller "https://github.com/inokawa/virtua/blob/main/src/core/scroller.ts"
    click CoreUtils "https://github.com/inokawa/virtua/blob/main/src/core/utils.ts"
    click CoreEnv "https://github.com/inokawa/virtua/blob/main/src/core/environment.ts"
    click CoreTypes "https://github.com/inokawa/virtua/blob/main/src/core/types.ts"
    click CoreIndex "https://github.com/inokawa/virtua/blob/main/src/core/index.ts"

    click ReactVList "https://github.com/inokawa/virtua/blob/main/src/react/VList.tsx"
    click ReactVirtualizer "https://github.com/inokawa/virtua/blob/main/src/react/Virtualizer.tsx"
    click ReactWindow "https://github.com/inokawa/virtua/blob/main/src/react/WindowVirtualizer.tsx"
    click ReactVGrid "https://github.com/inokawa/virtua/blob/main/src/react/VGrid.tsx"
    click ReactHooks "https://github.com/inokawa/virtua/blob/main/src/react/useChildren.ts"
    click ReactUtils "https://github.com/inokawa/virtua/blob/main/src/react/utils.ts"
    click ReactTypes "https://github.com/inokawa/virtua/blob/main/src/react/types.ts"
    click ReactIndex "https://github.com/inokawa/virtua/blob/main/src/react/index.ts"

    click VueVList "https://github.com/inokawa/virtua/blob/main/src/vue/VList.tsx"
    click VueVirtualizer "https://github.com/inokawa/virtua/blob/main/src/vue/Virtualizer.tsx"
    click VueWindow "https://github.com/inokawa/virtua/blob/main/src/vue/WindowVirtualizer.tsx"
    click VueListItem "https://github.com/inokawa/virtua/blob/main/src/vue/ListItem.tsx"
    click VueUtils "https://github.com/inokawa/virtua/blob/main/src/vue/utils.ts"
    click VueIndex "https://github.com/inokawa/virtua/blob/main/src/vue/index.ts"

    click SolidVList "https://github.com/inokawa/virtua/blob/main/src/solid/VList.tsx"
    click SolidVirtualizer "https://github.com/inokawa/virtua/blob/main/src/solid/Virtualizer.tsx"
    click SolidWindow "https://github.com/inokawa/virtua/blob/main/src/solid/WindowVirtualizer.tsx"
    click SolidListItem "https://github.com/inokawa/virtua/blob/main/src/solid/ListItem.tsx"
    click SolidUtils "https://github.com/inokawa/virtua/blob/main/src/solid/utils.ts"
    click SolidTypes "https://github.com/inokawa/virtua/blob/main/src/solid/types.ts"
    click SolidIndex "https://github.com/inokawa/virtua/blob/main/src/solid/index.ts"

    click SvelteVList "https://github.com/inokawa/virtua/blob/main/src/svelte/VList.svelte"
    click SvelteVirtualizer "https://github.com/inokawa/virtua/blob/main/src/svelte/Virtualizer.svelte"
    click SvelteWindow "https://github.com/inokawa/virtua/blob/main/src/svelte/WindowVirtualizer.svelte"
    click SvelteListItem "https://github.com/inokawa/virtua/blob/main/src/svelte/ListItem.svelte"
    click SvelteUtils "https://github.com/inokawa/virtua/blob/main/src/svelte/utils.ts"
    click SvelteTypes "https://github.com/inokawa/virtua/blob/main/src/svelte/types.ts"
    click SvelteIndex "https://github.com/inokawa/virtua/blob/main/src/svelte/index.ts"

    click Rollup "https://github.com/inokawa/virtua/blob/main/rollup.config.mjs"
    click Scripts "https://github.com/inokawa/virtua/tree/main/scripts/"
    click PackageJSON "https://github.com/inokawa/virtua/blob/main/package.json"
    click APIDocs "https://github.com/inokawa/virtua/blob/main/docs/API.md"
    click ReactDocs "https://github.com/inokawa/virtua/tree/main/docs/react/"
    click VueDocs "https://github.com/inokawa/virtua/tree/main/docs/vue/"
    click SolidDocs "https://github.com/inokawa/virtua/tree/main/docs/solid/"
    click SvelteDocs "https://github.com/inokawa/virtua/tree/main/docs/svelte/"
    click Stories "https://github.com/inokawa/virtua/tree/main/stories/"
    click Vitest "https://github.com/inokawa/virtua/blob/main/vitest.config.ts"
    click PlaywrightConfig "https://github.com/inokawa/virtua/blob/main/playwright.config.ts"
    click E2ETests "https://github.com/inokawa/virtua/tree/main/e2e/"

    %% Styles
    classDef coreModules fill:#D0E8FF,stroke:#0366d6,stroke-width:1px
    class CoreIndex,CoreTypes,CoreUtils,CoreEnv,CoreCache,CoreStore,CoreResizer,CoreScroller coreModules

    classDef react fill:#FFCDD2,stroke:#b71c1c
    class ReactIndex,ReactTypes,ReactVList,ReactVirtualizer,ReactWindow,ReactVGrid,ReactHooks,ReactUtils react

    classDef vue fill:#C8E6C9,stroke:#1b5e20
    class VueIndex,VueVList,VueVirtualizer,VueWindow,VueListItem,VueUtils vue

    classDef solid fill:#E1BEE7,stroke:#4a148c
    class SolidIndex,SolidTypes,SolidVList,SolidVirtualizer,SolidWindow,SolidListItem,SolidUtils solid

    classDef svelte fill:#FFECB3,stroke:#ff6f00
    class SvelteIndex,SvelteTypes,SvelteVList,SvelteVirtualizer,SvelteWindow,SvelteListItem,SvelteUtils svelte

    classDef tools fill:#F5F5F5,stroke:#757575
    class Rollup,Scripts,PackageJSON,BuildArtifact,APIDocs,ReactDocs,VueDocs,SolidDocs,SvelteDocs,Stories,Vitest,PlaywrightConfig,E2ETests,Storybook,CI tools

    classDef external stroke-dasharray: 5 5,stroke:#555,fill:#FFF
```
