The Problem

Web teams that need to display Lottie or dotLottie assets must choose between a handful of fragmented libraries, each tied to a specific rendering backend or framework. The result is duplicated effort, inconsistent feature support, and UI jank when animations run on the main thread.

What This Does

dotlottie-web supplies a single, Rust‑powered WASM core (via dotlottie‑rs) that can render to Canvas2D, WebGL2, or experimental WebGPU. The core lives in packages/web/src/dotlottie.ts and packages/web/src/worker/dotlottie.ts, exposing the DotLottie class used by all SDKs.

Framework bindings live under packages/:

  • React – packages/react/src/base-dotlottie-react.tsx
  • Vue – packages/vue/src/DotlottieVue.vue
  • Svelte – packages/svelte/src/Dotlottie.svelte
  • Solid – packages/solid/src/DotlottieSolid.tsx
  • Web Component – packages/wc/src/dotlottie-wc.ts

A demo viewer (apps/viewer) and a set of runnable examples (examples/) showcase the APIs and let developers experiment with rendering back‑ends, theming, and state machines.

How It Is Wired

Execution starts in apps/viewer/index.html, which loads a Vite bundle configured by apps/viewer/vite.config.ts. The bundle imports packages/web/src/dotlottie.ts to construct a DotLottie instance.

DotLottie (in dotlottie.ts) imports:

  • packages/web/src/worker/dotlottie.ts – spawns a Web Worker that runs the WASM core on an OffscreenCanvas.
  • packages/web/src/webgl/dotlottie-webgl.ts and packages/web/src/webgpu/dotlottie-webgpu.ts – provide the three rendering back‑ends.
  • packages/web/src/event-manager.ts and packages/web/src/types.ts – expose typed events and shared type definitions (both have 8 incoming imports, zero outgoing, i.e., stable leaves).

The most connected module is dotlottie.ts (6 inbound, 9 outbound, instability 0.6) and participates in a circular import with worker/dotlottie.ts and worker/types.ts. That cycle expands the blast radius: a change in any of those three files can ripple through the entire rendering pipeline.

Framework SDKs import the core (dotlottie.ts) and re‑export a thin wrapper component, so the bulk of the logic stays in a single place. The viewer UI (apps/viewer/src/components/*) consumes the public API but does not influence the core rendering flow.

How To Use It

# Clone the repo
git clone https://github.com/moses-y/dotlottie-web
cd dotlottie-web

# Install all workspace packages (pnpm is the declared manager)
pnpm install

# Run the React example (similar commands work for Vue, Svelte, Solid)
pnpm --filter examples/react dev   # starts Vite dev server at http://localhost:5173

No additional configuration files are required; the examples point at public .lottie URLs. To embed the player in your own project, install the framework‑specific package (e.g., npm i @lottiefiles/dotlottie-react) and import DotLottieReact as shown in the README.

Real‑World Use

A marketing site can replace a GIF carousel with a DotLottieReact component that loads a .lottie bundle containing multiple themed animations. Switching themes is a single runtime call:

import { DotLottieReact } from '@lottiefiles/dotlottie-react';

<DotLottieReact src="/assets/hero.lottie" theme="dark" autoplay loop />

The animation runs off‑main‑thread, preserving UI responsiveness even on low‑end devices.

Code Health & Issues

  • High – Cognitive load – packages/web/src/dotlottie.ts, worker/dotlottie.ts, core/dotlottie-player.js each exceed 1,400 lines; a single edit touches many downstream modules.
  • High – Soundness – Circular import among dotlottie.ts, worker/dotlottie.ts, worker/types.ts increases maintenance risk.
  • High – Clarity – Repeated 6‑line blocks across 40 files (e.g., player wrappers) suggest a DRY opportunity.
  • Low – Clarity – Three TODO/FIXME markers remain in dotlottie.ts.
  • Medium – Dependency‑review missing – No vulnerability scan in .github/workflows/ci.yml.
  • Medium – Install script – preinstall script runs automatically; CI should disable scripts or run them explicitly.
  • Low – Job timeout – CI jobs lack timeout-minutes, risking overlapping runs.

The repository includes a full test suite (63 test files), a license, lockfile, and CI, but lacks a Dockerfile and any committed secrets.

The Bottom Line

dotlottie-web delivers a unified, high‑performance animation player across the major web frameworks, backed by a proven Rust/WASM engine. The core is solid, but the monolithic source files, import cycle, and duplicated UI helpers raise the cost of future changes. Teams that need cross‑framework Lottie support and are comfortable managing a moderately complex codebase will benefit most.