How inokawa/virtua works
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”