# tengbao/vanta architecture

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

- Interactive diagram: https://gitdiagram.com/tengbao/vanta
- Repository: https://github.com/tengbao/vanta

## Overview

1. **What this repo is**
   - Vanta JS is a browser-only library for attaching animated visual backgrounds to an existing DOM element.
   - The core product is not a full app; it is a set of reusable effect modules plus a demo/gallery site and a build pipeline that produces distributable bundles in `dist/`.

2. **Primary runtime boundary**
   - The main integration point is a host element passed as `el`.
   - Each effect creates and manages its own canvas/WebGL/p5 rendering surface and appends it inside that element.
   - Foreground page content stays outside the effect and renders above it, so Vanta behaves like an embedded background subsystem rather than owning the whole page.

3. **Effect module architecture**
   - Each file in `src/vanta.*.js` is a standalone effect implementation: birds, cells, clouds, clouds2, dots, fog, globe, halo, net, rings, ripple, topology, trunk, and waves.
   - These modules are the public entry points that become `VANTA.BIRDS`, `VANTA.WAVES`, etc.
   - The effects are deliberately split so consumers can ship only the visuals they need.

4. **Shared lifecycle and abstraction layer**
   - `src/_base.js` provides common effect lifecycle behavior such as initialization, option handling, resizing, and destruction.
   - `src/_shaderBase.js` is the shared foundation for WebGL/three.js shader-driven effects.
   - `src/_p5Base.js` is the analogous base for effects implemented with p5.js.
   - This base-layer split is the main architectural boundary inside the library: shared lifecycle logic above, rendering-engine-specific logic below, and individual effects on top.

5. **Rendering technology boundary**
   - Some effects are built on **three.js/WebGL**, others on **p5.js**.
   - The README makes it explicit that `three.js` or `p5.js` is expected to be available externally, or can be passed in through options.
   - That means Vanta is not tightly bundling its rendering engines; it is designed to integrate with host-provided graphics runtimes.

6. **Input and interaction flow**
   - Effects can respond to mouse, touch, and optional gyro input.
   - Interaction is handled inside the effect instances and influences animation state, but the host app remains the source of the DOM element and page layout.
   - The configuration surface is effect-specific: common controls are shared, but visual parameters live with each effect module.

7. **Helpers and shared utilities**
   - `src/helpers.js` contains reusable utilities used across effects and base classes.
   - This is likely where common math, DOM, and option helpers live, reducing duplication across the many effect modules.

8. **Gallery/demo subsystem**
   - `src/gallery.js` plus `index.html` and the `src/styles.less` / `src/skeleton.less` styles support the demo gallery site.
   - This is separate from the core library runtime: it showcases effects, allows visual customization, and likely exercises the same effect modules in a browser UI.
   - The README references a gallery branch and local dev flow, which reinforces that the repo contains both library code and a demo experience.

9. **Build and packaging pipeline**
   - `webpack.config.js` and `webpack.build.js` define the development and production bundling process.
   - The compiled output goes to `dist/`, which is what consumers import or load via script tags.
   - This repo is structured for library distribution, not server deployment.

10. **External dependencies and integration model**
   - Consumers can use Vanta via plain script tags, or import individual effect bundles from `dist/`.
   - For framework integrations, the library is wrapped at the effect level, not via a framework-specific runtime.
   - The main external dependencies that affect architecture are `three.js`, `p5.js`, and Webpack for packaging.

11. **What to draw in an architecture diagram**
   - Show three layers: consumer page/app, Vanta effect modules, and rendering engine dependencies.
   - Inside Vanta, show shared base classes feeding multiple effect implementations.
   - Include the gallery/demo app as a separate consumer of the same effect modules.
   - Include `dist/` as the packaged output of the build system, not as source of truth.

Main entry points: [`src/_base.js`](https://github.com/tengbao/vanta/blob/master/src/_base.js) (Base lifecycle), [`src/_p5Base.js`](https://github.com/tengbao/vanta/blob/master/src/_p5Base.js) (p5 base), [`src/_shaderBase.js`](https://github.com/tengbao/vanta/blob/master/src/_shaderBase.js) (Shader base), [`src/vanta.birds.js`](https://github.com/tengbao/vanta/blob/master/src/vanta.birds.js) (Birds)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_consumers["Consumers"]
  node_host_app["Host page<br/>consumer"]
end

subgraph group_library["Vanta library"]
  node_base["Base lifecycle<br/>shared base<br/>[_base.js]"]
  node_shader_base["Shader base<br/>webgl base<br/>[_shaderBase.js]"]
  node_p5_base["p5 base<br/>[_p5Base.js]"]
  node_helpers["Helpers<br/>utility module<br/>[helpers.js]"]
  node_birds["Birds<br/>effect module<br/>[vanta.birds.js]"]
  node_cells["Cells<br/>effect module<br/>[vanta.cells.js]"]
  node_clouds["Clouds<br/>effect module<br/>[vanta.clouds.js]"]
  node_clouds2["Clouds 2<br/>effect module<br/>[vanta.clouds2.js]"]
  node_dots["Dots<br/>effect module<br/>[vanta.dots.js]"]
  node_fog["Fog<br/>effect module<br/>[vanta.fog.js]"]
  node_globe["Globe<br/>effect module<br/>[vanta.globe.js]"]
  node_halo["Halo<br/>effect module<br/>[vanta.halo.js]"]
  node_net["Net<br/>effect module<br/>[vanta.net.js]"]
  node_rings["Rings<br/>effect module<br/>[vanta.rings.js]"]
  node_ripple["Ripple<br/>effect module<br/>[vanta.ripple.js]"]
  node_topology["Topology<br/>effect module<br/>[vanta.topology.js]"]
  node_trunk["Trunk<br/>effect module<br/>[vanta.trunk.js]"]
  node_waves["Waves<br/>effect module<br/>[vanta.waves.js]"]
end

subgraph group_demo["Demo site"]
  node_gallery_site["Gallery<br/>demo app<br/>[gallery.js]"]
  node_index_html["Index page<br/>demo shell<br/>[index.html]"]
  node_styles["Styles<br/>[styles.less]"]
  node_skeleton["Skeleton<br/>ui styles<br/>[skeleton.less]"]
end

subgraph group_build["Build & output"]
  node_webpack_dev["Dev build<br/>webpack config<br/>[webpack.config.js]"]
  node_webpack_prod["Prod build<br/>webpack config<br/>[webpack.build.js]"]
  node_dist[("Dist bundles<br/>published output")]
end

subgraph group_deps["External runtimes"]
  node_threejs(("three.js<br/>render engine"))
  node_p5js(("p5.js<br/>render engine"))
end

node_host_app -->|"uses"| node_dist
node_host_app -->|"embeds"| node_birds
node_host_app -->|"embeds"| node_waves
node_gallery_site -->|"showcases"| node_birds
node_gallery_site -->|"showcases"| node_waves
node_index_html -->|"boots"| node_gallery_site
node_styles -->|"skins"| node_index_html
node_skeleton -->|"skins"| node_index_html
node_base -->|"extends"| node_birds
node_base -->|"extends"| node_cells
node_base -->|"extends"| node_clouds
node_base -->|"extends"| node_dots
node_base -->|"extends"| node_fog
node_base -->|"extends"| node_globe
node_base -->|"extends"| node_halo
node_base -->|"extends"| node_net
node_base -->|"extends"| node_rings
node_base -->|"extends"| node_ripple
node_base -->|"extends"| node_topology
node_base -->|"extends"| node_trunk
node_base -->|"extends"| node_waves
node_shader_base -->|"supports"| node_globe
node_shader_base -->|"supports"| node_halo
node_shader_base -->|"supports"| node_rings
node_shader_base -->|"supports"| node_ripple
node_shader_base -->|"supports"| node_topology
node_shader_base -->|"supports"| node_waves
node_p5_base -->|"supports"| node_birds
node_p5_base -->|"supports"| node_cells
node_p5_base -->|"supports"| node_clouds
node_p5_base -->|"supports"| node_clouds2
node_p5_base -->|"supports"| node_dots
node_p5_base -->|"supports"| node_fog
node_p5_base -->|"supports"| node_net
node_p5_base -->|"supports"| node_trunk
node_helpers -->|"used by"| node_base
node_helpers -->|"used by"| node_shader_base
node_helpers -->|"used by"| node_p5_base
node_webpack_dev -->|"produces"| node_dist
node_webpack_prod -->|"produces"| node_dist
node_webpack_dev -->|"bundles"| node_gallery_site
node_webpack_prod -->|"bundles"| node_birds
node_webpack_prod -->|"bundles"| node_waves
node_threejs -->|"runtime for"| node_shader_base
node_p5js -->|"runtime for"| node_p5_base

click node_gallery_site "https://github.com/tengbao/vanta/blob/master/src/gallery.js"
click node_index_html "https://github.com/tengbao/vanta/blob/master/index.html"
click node_styles "https://github.com/tengbao/vanta/blob/master/src/styles.less"
click node_skeleton "https://github.com/tengbao/vanta/blob/master/src/skeleton.less"
click node_base "https://github.com/tengbao/vanta/blob/master/src/_base.js"
click node_shader_base "https://github.com/tengbao/vanta/blob/master/src/_shaderBase.js"
click node_p5_base "https://github.com/tengbao/vanta/blob/master/src/_p5Base.js"
click node_helpers "https://github.com/tengbao/vanta/blob/master/src/helpers.js"
click node_birds "https://github.com/tengbao/vanta/blob/master/src/vanta.birds.js"
click node_cells "https://github.com/tengbao/vanta/blob/master/src/vanta.cells.js"
click node_clouds "https://github.com/tengbao/vanta/blob/master/src/vanta.clouds.js"
click node_clouds2 "https://github.com/tengbao/vanta/blob/master/src/vanta.clouds2.js"
click node_dots "https://github.com/tengbao/vanta/blob/master/src/vanta.dots.js"
click node_fog "https://github.com/tengbao/vanta/blob/master/src/vanta.fog.js"
click node_globe "https://github.com/tengbao/vanta/blob/master/src/vanta.globe.js"
click node_halo "https://github.com/tengbao/vanta/blob/master/src/vanta.halo.js"
click node_net "https://github.com/tengbao/vanta/blob/master/src/vanta.net.js"
click node_rings "https://github.com/tengbao/vanta/blob/master/src/vanta.rings.js"
click node_ripple "https://github.com/tengbao/vanta/blob/master/src/vanta.ripple.js"
click node_topology "https://github.com/tengbao/vanta/blob/master/src/vanta.topology.js"
click node_trunk "https://github.com/tengbao/vanta/blob/master/src/vanta.trunk.js"
click node_waves "https://github.com/tengbao/vanta/blob/master/src/vanta.waves.js"
click node_webpack_dev "https://github.com/tengbao/vanta/blob/master/webpack.config.js"
click node_webpack_prod "https://github.com/tengbao/vanta/blob/master/webpack.build.js"
click node_dist "https://github.com/tengbao/vanta/tree/master/dist"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_host_app toneBlue
class node_base,node_shader_base,node_p5_base,node_helpers,node_birds,node_cells,node_clouds,node_clouds2,node_dots,node_fog,node_globe,node_halo,node_net,node_rings,node_ripple,node_topology,node_trunk,node_waves toneAmber
class node_gallery_site,node_index_html,node_styles,node_skeleton toneMint
class node_webpack_dev,node_webpack_prod,node_dist toneRose
class node_threejs,node_p5js toneIndigo
```

## Components

### Consumers

Host pages and the demo gallery that embed Vanta effects.

- **Host page**: consumer · An existing DOM page that passes a target element into Vanta.

### Vanta library

Shared lifecycle, helpers, and individual effect modules.

- [Base lifecycle](https://github.com/tengbao/vanta/blob/master/src/_base.js): shared base · Common initialization, options, resize, and destruction behavior. · `src/_base.js`
- [Shader base](https://github.com/tengbao/vanta/blob/master/src/_shaderBase.js): webgl base · Shared foundation for three.js/WebGL shader-driven effects. · `src/_shaderBase.js`
- [p5 base](https://github.com/tengbao/vanta/blob/master/src/_p5Base.js): p5 base · Shared foundation for effects implemented with p5.js. · `src/_p5Base.js`
- [Helpers](https://github.com/tengbao/vanta/blob/master/src/helpers.js): utility module · Shared math, DOM, and option utilities. · `src/helpers.js`
- [Birds](https://github.com/tengbao/vanta/blob/master/src/vanta.birds.js): effect module · Animated background effect entry point. · `src/vanta.birds.js`
- [Cells](https://github.com/tengbao/vanta/blob/master/src/vanta.cells.js): effect module · Animated background effect entry point. · `src/vanta.cells.js`
- [Clouds](https://github.com/tengbao/vanta/blob/master/src/vanta.clouds.js): effect module · Animated background effect entry point. · `src/vanta.clouds.js`
- [Clouds 2](https://github.com/tengbao/vanta/blob/master/src/vanta.clouds2.js): effect module · Animated background effect entry point. · `src/vanta.clouds2.js`
- [Dots](https://github.com/tengbao/vanta/blob/master/src/vanta.dots.js): effect module · Animated background effect entry point. · `src/vanta.dots.js`
- [Fog](https://github.com/tengbao/vanta/blob/master/src/vanta.fog.js): effect module · Animated background effect entry point. · `src/vanta.fog.js`
- [Globe](https://github.com/tengbao/vanta/blob/master/src/vanta.globe.js): effect module · Animated background effect entry point. · `src/vanta.globe.js`
- [Halo](https://github.com/tengbao/vanta/blob/master/src/vanta.halo.js): effect module · Animated background effect entry point. · `src/vanta.halo.js`
- [Net](https://github.com/tengbao/vanta/blob/master/src/vanta.net.js): effect module · Animated background effect entry point. · `src/vanta.net.js`
- [Rings](https://github.com/tengbao/vanta/blob/master/src/vanta.rings.js): effect module · Animated background effect entry point. · `src/vanta.rings.js`
- [Ripple](https://github.com/tengbao/vanta/blob/master/src/vanta.ripple.js): effect module · Animated background effect entry point. · `src/vanta.ripple.js`
- [Topology](https://github.com/tengbao/vanta/blob/master/src/vanta.topology.js): effect module · Animated background effect entry point. · `src/vanta.topology.js`
- [Trunk](https://github.com/tengbao/vanta/blob/master/src/vanta.trunk.js): effect module · Animated background effect entry point. · `src/vanta.trunk.js`
- [Waves](https://github.com/tengbao/vanta/blob/master/src/vanta.waves.js): effect module · Animated background effect entry point. · `src/vanta.waves.js`

### Demo site

Gallery UI and styles for exploring effects in the browser.

- [Gallery](https://github.com/tengbao/vanta/blob/master/src/gallery.js): demo app · Browser demo that showcases and configures effects. · `src/gallery.js`
- [Index page](https://github.com/tengbao/vanta/blob/master/index.html): demo shell · Entry HTML for the gallery/demo experience. · `index.html`
- [Styles](https://github.com/tengbao/vanta/blob/master/src/styles.less): ui styles · Gallery and layout styling for the demo site. · `src/styles.less`
- [Skeleton](https://github.com/tengbao/vanta/blob/master/src/skeleton.less): ui styles · Base presentation styles used by the demo shell. · `src/skeleton.less`

### Build & output

Webpack entry points and packaged distributable bundles.

- [Dev build](https://github.com/tengbao/vanta/blob/master/webpack.config.js): webpack config · Development bundling and local build workflow. · `webpack.config.js`
- [Prod build](https://github.com/tengbao/vanta/blob/master/webpack.build.js): webpack config · Production bundling and distributable packaging. · `webpack.build.js`
- [Dist bundles](https://github.com/tengbao/vanta/tree/master/dist): published output · Compiled artifacts consumed by script tags or imports. · `dist`

### External runtimes

Rendering engines provided by the host or bundled separately.

- **three.js**: render engine · WebGL runtime used by shader-driven effects.
- **p5.js**: render engine · Canvas runtime used by p5-based effects.

## Connections

- Host page → Dist bundles: uses · A host page loads packaged Vanta bundles.
- Host page → Birds: embeds · Effects attach to an existing DOM element and render behind content.
- Host page → Waves: embeds · Effects attach to an existing DOM element and render behind content.
- Gallery → Birds: showcases · The gallery reuses the same effect modules for demoing visuals.
- Gallery → Waves: showcases · The gallery reuses the same effect modules for demoing visuals.
- Index page → Gallery: boots · HTML shell loads the demo application.
- Styles → Index page: skins · Styles support the demo/gallery presentation.
- Skeleton → Index page: skins · Base layout styles support the demo shell.
- Base lifecycle → Birds: extends · Effects share lifecycle and option handling from the common base.
- Base lifecycle → Cells: extends · Effects share lifecycle and option handling from the common base.
- Base lifecycle → Clouds: extends · Effects share lifecycle and option handling from the common base.
- Base lifecycle → Dots: extends · Effects share lifecycle and option handling from the common base.
- Base lifecycle → Fog: extends · Effects share lifecycle and option handling from the common base.
- Base lifecycle → Globe: extends · Effects share lifecycle and option handling from the common base.
- Base lifecycle → Halo: extends · Effects share lifecycle and option handling from the common base.
- Base lifecycle → Net: extends · Effects share lifecycle and option handling from the common base.
- Base lifecycle → Rings: extends · Effects share lifecycle and option handling from the common base.
- Base lifecycle → Ripple: extends · Effects share lifecycle and option handling from the common base.
- Base lifecycle → Topology: extends · Effects share lifecycle and option handling from the common base.
- Base lifecycle → Trunk: extends · Effects share lifecycle and option handling from the common base.
- Base lifecycle → Waves: extends · Effects share lifecycle and option handling from the common base.
- Shader base → Globe: supports · Shader-driven effects build on the shared WebGL base.
- Shader base → Halo: supports · Shader-driven effects build on the shared WebGL base.
- Shader base → Rings: supports · Shader-driven effects build on the shared WebGL base.
- Shader base → Ripple: supports · Shader-driven effects build on the shared WebGL base.
- Shader base → Topology: supports · Shader-driven effects build on the shared WebGL base.
- Shader base → Waves: supports · Shader-driven effects build on the shared WebGL base.
- p5 base → Birds: supports · p5-based effects build on the shared p5 base.
- p5 base → Cells: supports · p5-based effects build on the shared p5 base.
- p5 base → Clouds: supports · p5-based effects build on the shared p5 base.
- p5 base → Clouds 2: supports · p5-based effects build on the shared p5 base.
- p5 base → Dots: supports · p5-based effects build on the shared p5 base.
- p5 base → Fog: supports · p5-based effects build on the shared p5 base.
- p5 base → Net: supports · p5-based effects build on the shared p5 base.
- p5 base → Trunk: supports · p5-based effects build on the shared p5 base.
- Helpers → Base lifecycle: used by · Shared utilities are consumed by the common lifecycle layer.
- Helpers → Shader base: used by · Shared utilities are consumed by engine-specific bases.
- Helpers → p5 base: used by · Shared utilities are consumed by engine-specific bases.
- Dev build → Dist bundles: produces · Development build outputs distributable artifacts.
- Prod build → Dist bundles: produces · Production build outputs distributable artifacts.
- Dev build → Gallery: bundles · Webpack builds the demo/gallery entry.
- Prod build → Birds: bundles · Webpack builds the effect entry points for distribution.
- Prod build → Waves: bundles · Webpack builds the effect entry points for distribution.
- three.js → Shader base: runtime for · three.js/WebGL is provided externally or via options.
- p5.js → p5 base: runtime for · p5.js is provided externally or via options.
