# propagande-studio/lenis architecture

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

- Interactive diagram: https://gitdiagram.com/propagande-studio/lenis
- Repository: https://github.com/propagande-studio/lenis

## Overview

##### Main components
- Core Smooth Scroll Engine (packages/core): This is the backbone of the library. It contains the core logic for handling smooth scrolling (functions like animate, debounce, emitter, virtual-scroll logic, etc.) and exposes methods (raf, scrollTo, on, etc.).
- Framework Integrations:
– React Package (packages/react): A wrapper/provider for using Lenis with React. It imports and extends the core functionality with React-specific logic (e.g., hooks, context providers).
– Vue Package (packages/vue): Similar to the React package, this package adapts the core library for Vue (including a Nuxt module and runtime adapter).
– Snap Package (packages/snap): Provides alternative scroll behavior, likely to support snap scrolling scenarios.
- Playground / Demo Applications: There are several “playground” directories showing how the library can be used in different environments (Astro, Nuxt, React, Vue, static HTML demos). These illustrate usage examples and are important external consumers of the core packages.
- External Integrations: The README mentions compatibility with GSAP ScrollTrigger (where Lenis’s scroll events are integrated into GSAP’s animation frame). In addition, there’s integration with npm (via package.json, pnpm workspace) and typical browsers (global scripts, CSS imports).

##### Relationships and Interactions
- The “Core” module stands at the center. Both the framework adapters (React, Vue, Snap) consume this core functionality.
- The playground/demo projects “consume” these packages and act as entry points or testing environments. They can be shown as external applications interacting with your packages.
- External dependencies (like GSAP for ScrollTrigger integration) attach to the output of the core or to the integrations. You may want to show a connection between GSAP and the core’s “raf” and event system.

##### Architectural Patterns & Design Principles
- Modular Design / Separation of Concerns: The project is split into multiple packages (core, react, snap, vue), emphasizing clear boundaries between the core scrolling logic and framework-specific wrappers.
- Reusability and Extensibility: The core is designed to be used in various contexts; the integration layers abstract the differences of React, Vue, or vanilla JS usage.
- Monorepo Structure: Demonstrate the workspace structure (using pnpm) that holds all these packages in one repository, emphasizing streamlined development and maintainability.
- Event-Driven Architecture: The core leverages an event emitter model to propagate scroll and virtual-scroll events to connected components or external libraries like GSAP.

##### Relevant Technologies
- JavaScript/TypeScript for the implementation.
- CSS (with the lenis.css file and related recommended setups).
- Frameworks: React, Vue (and Nuxt) as front-end frameworks.
- External Libraries: GSAP ScrollTrigger integration.
- Tools: pnpm for dependency management and the monorepo structure; additionally, configuration files (.github workflows, tsconfig, tsup configuration) that support the build and CI/CD.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Core Module
    CORE["Core (Smooth Scroll Engine)"]:::core

    %% Integration Adapters
    subgraph "Integration Adapters"
        REACT["React Integration"]:::integration
        VUE["Vue Integration (and Nuxt)"]:::integration
        SNAP["Snap Integration"]:::integration
    end

    %% Playground / Demo Applications
    PLAYGROUND["Playground / Demo Applications"]:::demo

    %% External Dependencies
    GSAP["GSAP ScrollTrigger"]:::external

    %% Relationships: Integrations depend on Core
    REACT -->|"uses"| CORE
    VUE -->|"uses"| CORE
    SNAP -->|"uses"| CORE

    %% Relationships: Playground projects consume integrations
    PLAYGROUND -->|"tests"| REACT
    PLAYGROUND -->|"tests"| VUE
    PLAYGROUND -->|"tests"| SNAP

    %% External integration with GSAP
    GSAP -->|"integratesWith"| CORE

    %% Click Events for Core Module
    click CORE "https://github.com/propagande-studio/lenis/tree/main/packages/core"
    click CORE "https://github.com/propagande-studio/lenis/tree/main/packages/core/src"

    %% Click Events for React Integration
    click REACT "https://github.com/propagande-studio/lenis/tree/main/packages/react"
    click REACT "https://github.com/propagande-studio/lenis/tree/main/packages/react/src"

    %% Click Events for Vue Integration
    click VUE "https://github.com/propagande-studio/lenis/tree/main/packages/vue"
    click VUE "https://github.com/propagande-studio/lenis/tree/main/packages/vue/nuxt"
    click VUE "https://github.com/propagande-studio/lenis/tree/main/packages/vue/src"

    %% Click Events for Snap Integration
    click SNAP "https://github.com/propagande-studio/lenis/tree/main/packages/snap"
    click SNAP "https://github.com/propagande-studio/lenis/tree/main/packages/snap/src"

    %% Click Events for Playground / Demo Applications
    click PLAYGROUND "https://github.com/propagande-studio/lenis/tree/main/playground"
    click PLAYGROUND "https://github.com/propagande-studio/lenis/tree/main/playground/core"
    click PLAYGROUND "https://github.com/propagande-studio/lenis/tree/main/playground/nuxt"
    click PLAYGROUND "https://github.com/propagande-studio/lenis/tree/main/playground/react"
    click PLAYGROUND "https://github.com/propagande-studio/lenis/tree/main/playground/snap"
    click PLAYGROUND "https://github.com/propagande-studio/lenis/tree/main/playground/vue"
    click PLAYGROUND "https://github.com/propagande-studio/lenis/tree/main/playground/www"

    %% Styles
    classDef core fill:#fef9c7,stroke:#fbb034,stroke-width:2px;
    classDef integration fill:#c7f5fe,stroke:#034fbb,stroke-width:2px;
    classDef demo fill:#d1f7c4,stroke:#3bb403,stroke-width:2px;
    classDef external fill:#fcd4d4,stroke:#a80000,stroke-width:2px;
```
