How tengbao/vanta works
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: _base.js Base lifecycle · _p5Base.js p5 base · _shaderBase.js Shader base · vanta.birds.js Birds
Components 28
Consumers
Host pages and the demo gallery that embed Vanta effects.
- Host page · An existing DOM page that passes a target element into Vanta.
Vanta library
Shared lifecycle, helpers, and individual effect modules.
- Base lifecycle · Common initialization, options, resize, and destruction behavior.
src/_base.js - Shader base · Shared foundation for three.js/WebGL shader-driven effects.
src/_shaderBase.js - p5 base · Shared foundation for effects implemented with p5.js.
src/_p5Base.js - Helpers · Shared math, DOM, and option utilities.
src/helpers.js - Birds · Animated background effect entry point.
src/vanta.birds.js - Cells · Animated background effect entry point.
src/vanta.cells.js - Clouds · Animated background effect entry point.
src/vanta.clouds.js - Clouds 2 · Animated background effect entry point.
src/vanta.clouds2.js - Dots · Animated background effect entry point.
src/vanta.dots.js - Fog · Animated background effect entry point.
src/vanta.fog.js - Globe · Animated background effect entry point.
src/vanta.globe.js - Halo · Animated background effect entry point.
src/vanta.halo.js - Net · Animated background effect entry point.
src/vanta.net.js - Rings · Animated background effect entry point.
src/vanta.rings.js - Ripple · Animated background effect entry point.
src/vanta.ripple.js - Topology · Animated background effect entry point.
src/vanta.topology.js - Trunk · Animated background effect entry point.
src/vanta.trunk.js - Waves · Animated background effect entry point.
src/vanta.waves.js
Demo site
Gallery UI and styles for exploring effects in the browser.
- Gallery · Browser demo that showcases and configures effects.
src/gallery.js - Index page · Entry HTML for the gallery/demo experience.
index.html - Styles · Gallery and layout styling for the demo site.
src/styles.less - Skeleton · Base presentation styles used by the demo shell.
src/skeleton.less
Build & output
Webpack entry points and packaged distributable bundles.
- Dev build · Development bundling and local build workflow.
webpack.config.js - Prod build · Production bundling and distributable packaging.
webpack.build.js - Dist bundles · Compiled artifacts consumed by script tags or imports.
dist
External runtimes
Rendering engines provided by the host or bundled separately.
- three.js · WebGL runtime used by shader-driven effects.
- p5.js · Canvas runtime used by p5-based effects.
Connections 45
- 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.