# ustbhuangyi/better-scroll architecture

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

- Interactive diagram: https://gitdiagram.com/ustbhuangyi/better-scroll
- Repository: https://github.com/ustbhuangyi/better-scroll

## Overview

##### Project type and purpose
- This is an open-source, monorepo JavaScript library (“better-scroll”) for mobile/PC scroll handling.
- It provides a core engine (@better-scroll/core) plus a rich plugin ecosystem (pull-up, pull-down, indicators, infinity, mouse-wheel, zoom, slide, nested-scroll, etc.).
- It also contains example integrations (Vue and React), documentation (VuePress), test suites (unit and E2E), build & release scripts, and CI/CD configurations.

##### File structure
- Top-level “lerna.json”, “package.json”, configs (.eslintrc.js, tsconfig.json, travis.yml, etc.), “scripts/” folder → monorepo management, build/test/release automation.
- “packages/” → each subfolder under packages is an independent npm package:
- core             – core scrolling engine
- better-scroll    – umbrella package bundling core + plugins
- indicators, infinity, mouse-wheel, movable, nested-scroll, observe-dom, observe-image, pull-down, pull-up, scroll-bar, slide, wheel, zoom, shared-utils → plugins or shared utilities
- examples (vue, react) → integration demos
- vuepress-docs → documentation site
- “tests/” and “jest.config.js” + “jest-e2e.config.js” → unit & end-to-end tests
- “scripts/” → build, release, check tooling
- CI/CD: .travis.yml, Gitpod config

##### README for additional insights
- Describes the core API, plugin mechanism, CDN usage, Vue/React integration.
- Mentions a plugin architecture: core is plugin-agnostic; features are enabled via plugin registration.

a. Components
- Monorepo Manager (Lerna + npm)
- Build & Release Scripts (scripts/, CI configs)
- Core Engine (@better-scroll/core)
- Plugin Modules (indicators, pull-up, pull-down, infinite, etc.)
- Umbrella Package (better-scroll): bundles core + selected plugins
- Examples (Vue-examples, React-examples)
- Documentation Site (VuePress)
- Test Suite (Unit tests, E2E tests)
- External Services: GitHub (repo), npm registry, TravisCI, Gitpod
b. Relationships & interactions
- Lerna orchestrates independent package versions, runs build scripts for each package and publishes to npm.
- Core Engine exposes hook points; each plugin registers itself with core via plugin APIs.
- Umbrella package imports core + a set of plugins and re-exports a unified API.
- Examples import either the umbrella package or individual packages to demonstrate usage.
- Documentation site pulls API definitions and code snippets from packages.
- CI pipeline (Travis/Gitpod) triggers lint → build → test → publish.
c. Architectural patterns & principles
- Monorepo via Lerna for unified versioning and dependencies.
- Plugin-based architecture: core engine + extension points.
- Separation of concerns: each feature in its own package, shared-utils for common helpers.
- Test-driven (unit & E2E) ensures reliability.
d. Technologies & frameworks
- JavaScript/TypeScript, Lerna, Jest, Puppeteer for E2E, VuePress for docs, Webpack/Rollup (in examples’ build scripts).
- CI/CD: TravisCI, Gitpod.

##### Diagrammatic elements
- Rectangles for “packages” (core, plugins, umbrella)
- Parallelograms for examples and docs
- From Lerna to each package (build & versioning)
- From plugins to core (plugin registration)
- From umbrella to core + plugins (aggregation)
- From examples to package(s) (consumer)
- From CI/CD to build/test/publish and back to GitHub/npm
- Management & CI (e.g., blue)
- Core & Plugins (e.g., green)
- Examples & Docs (e.g., orange)
- External Services (e.g., gray)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Monorepo & Management
    subgraph "Monorepo & Management"
        direction TB
        Lerna["Lerna & npm<br/>(lerna.json, package.json)"]:::management
        ESLint["ESLint (.eslintrc.js)"]:::management
        TS["TypeScript Config (tsconfig.json)"]:::management
    end

    %% CI/CD & Scripts
    subgraph "CI/CD & Scripts"
        direction TB
        Travis["Travis CI (.travis.yml)"]:::ci
        Gitpod["Gitpod Config<br/>(.gitpod.yml, .gitpod.Dockerfile)"]:::ci
        Husky["Husky Hooks (.huskyrc.json)"]:::ci
        Scripts["Build & Release Scripts"]:::ci
    end

    %% Core & Plugins
    subgraph "Core & Plugins"
        direction TB
        Core["@better-scroll/core"]:::coreLayer
        Umbrella["better-scroll (umbrella)"]:::coreLayer
        subgraph "Plugin Modules"
            direction TB
            Indicators["indicators"]:::coreLayer
            Infinity["infinity"]:::coreLayer
            MouseWheel["mouse-wheel"]:::coreLayer
            Movable["movable"]:::coreLayer
            NestedScroll["nested-scroll"]:::coreLayer
            ObserveDom["observe-dom"]:::coreLayer
            ObserveImage["observe-image"]:::coreLayer
            PullDown["pull-down"]:::coreLayer
            PullUp["pull-up"]:::coreLayer
            ScrollBar["scroll-bar"]:::coreLayer
            Slide["slide"]:::coreLayer
            Wheel["wheel"]:::coreLayer
            Zoom["zoom"]:::coreLayer
            SharedUtils["shared-utils"]:::coreLayer
        end
    end

    %% Examples & Docs
    subgraph "Examples & Documentation"
        direction TB
        VueEx["Vue Examples"]:::examples
        ReactEx["React Examples"]:::examples
        Docs["VuePress Docs"]:::examples
    end

    %% Test Suite
    subgraph "Test Suite"
        direction TB
        Unit["Unit Tests"]:::tests
        E2E["E2E Tests"]:::tests
        DTS["Type Declaration Tests"]:::tests
    end

    %% External Services & CI Pipeline
    GitHub["GitHub Repo"]:::external
    Npm["npm Registry"]:::external
    CI["CI Pipeline"]:::ci

    %% Relationships
    GitHub -->|triggers| CI
    CI -->|runs| Travis
    CI -->|runs| Gitpod
    CI -->|executes| Scripts
    CI -->|runs| Unit
    CI -->|runs| E2E
    CI -->|runs| DTS
    CI -->|publishes| Npm

    Lerna -->|manages| Core
    Lerna -->|manages| Plugins
    Lerna -->|manages| Umbrella
    Lerna -->|manages| Examples
    Lerna -->|manages| Docs

    Scripts -->|builds| Core
    Scripts -->|builds| Plugins
    Scripts -->|builds| Umbrella

    Core -->|plugin API| Plugins
    Umbrella -->|aggregates| Core
    Umbrella -->|aggregates| Plugins

    VueEx -->|consumes| Umbrella
    ReactEx -->|consumes| Umbrella

    Docs -->|sources| Core
    Docs -->|sources| Plugins

    %% Click Events
    click Lerna "https://github.com/ustbhuangyi/better-scroll/blob/dev/lerna.json"
    click ESLint "https://github.com/ustbhuangyi/better-scroll/blob/dev/.eslintrc.js"
    click TS "https://github.com/ustbhuangyi/better-scroll/blob/dev/tsconfig.json"
    click Travis "https://github.com/ustbhuangyi/better-scroll/blob/dev/.travis.yml"
    click Gitpod "https://github.com/ustbhuangyi/better-scroll/blob/dev/.gitpod.yml"
    click Gitpod "https://github.com/ustbhuangyi/better-scroll/blob/dev/.gitpod.Dockerfile"
    click Husky "https://github.com/ustbhuangyi/better-scroll/blob/dev/.huskyrc.json"
    click Scripts "https://github.com/ustbhuangyi/better-scroll/tree/dev/scripts/"
    click Core "https://github.com/ustbhuangyi/better-scroll/tree/dev/packages/core/"
    click Indicators "https://github.com/ustbhuangyi/better-scroll/blob/dev/packages/indicators/src/index.ts"
    click Infinity "https://github.com/ustbhuangyi/better-scroll/blob/dev/packages/infinity/src/index.ts"
    click MouseWheel "https://github.com/ustbhuangyi/better-scroll/blob/dev/packages/mouse-wheel/src/index.ts"
    click Movable "https://github.com/ustbhuangyi/better-scroll/blob/dev/packages/movable/src/index.ts"
    click NestedScroll "https://github.com/ustbhuangyi/better-scroll/blob/dev/packages/nested-scroll/src/index.ts"
    click ObserveDom "https://github.com/ustbhuangyi/better-scroll/blob/dev/packages/observe-dom/src/index.ts"
    click ObserveImage "https://github.com/ustbhuangyi/better-scroll/blob/dev/packages/observe-image/src/index.ts"
    click PullDown "https://github.com/ustbhuangyi/better-scroll/blob/dev/packages/pull-down/src/index.ts"
    click PullUp "https://github.com/ustbhuangyi/better-scroll/blob/dev/packages/pull-up/src/index.ts"
    click ScrollBar "https://github.com/ustbhuangyi/better-scroll/blob/dev/packages/scroll-bar/src/index.ts"
    click Slide "https://github.com/ustbhuangyi/better-scroll/blob/dev/packages/slide/src/index.ts"
    click Wheel "https://github.com/ustbhuangyi/better-scroll/blob/dev/packages/wheel/src/index.ts"
    click Zoom "https://github.com/ustbhuangyi/better-scroll/blob/dev/packages/zoom/src/index.ts"
    click SharedUtils "https://github.com/ustbhuangyi/better-scroll/blob/dev/packages/shared-utils/src/index.ts"
    click Umbrella "https://github.com/ustbhuangyi/better-scroll/blob/dev/packages/better-scroll/src/index.ts"
    click VueEx "https://github.com/ustbhuangyi/better-scroll/tree/dev/packages/examples/vue/"
    click ReactEx "https://github.com/ustbhuangyi/better-scroll/tree/dev/packages/react-examples/src/"
    click Docs "https://github.com/ustbhuangyi/better-scroll/tree/dev/packages/vuepress-docs/docs/"
    click Unit "https://github.com/ustbhuangyi/better-scroll/blob/dev/jest.config.js"
    click E2E "https://github.com/ustbhuangyi/better-scroll/tree/dev/tests/e2e/"
    click DTS "https://github.com/ustbhuangyi/better-scroll/tree/dev/test-dts/"

    %% Styles
    classDef management fill:#D6EAF8,stroke:#1B4F72,color:#1B2631
    classDef ci fill:#AED6F1,stroke:#1B4F72,color:#1B2631
    classDef coreLayer fill:#D5F5E3,stroke:#145A32,color:#0B5345
    classDef examples fill:#FDEBD0,stroke:#B9770E,color:#7E5109
    classDef tests fill:#E8DAEF,stroke:#6C3483,color:#4A235A
    classDef external fill:#D5DBDB,stroke:#424949,color:#1C2833
```
