Skip to content

Development Guide

Jump to bottom
Jinny You edited this page Dec 22, 2025 · 2 revisions

Building and Testing @thorvg/lottie-player

This document provides comprehensive guidance on:

  • Steps for locally building the @thorvg/lottie-player web library
  • Methods for testing the @thorvg/lottie-player web library

Generate WebAssembly Code

1. Setup Emscripten

We compile ThorVG to WebAssembly using Emscripten.

You can find installation instructions from Download and install

Note: You may need to add the Emscripten path to your environment:

export PATH={absolute path}/emsdk/upstream/bin:$PATH

2. Build ThorVG with WASM Bindings

# Build ThorVG and WASM bindings using Emscripten
./wasm_build.sh {absolute path}/emsdk/

The build script will:

  1. Build the ThorVG core library from the thorvg submodule
  2. Build the WASM bindings from wasm/lottie-player/
  3. Use cross-compilation configurations from wasm/wasm32*.txt

Build Results: You will get the following build results thorvg.js and thorvg.wasm in the build_wasm/ folder.

Backend-Specific Builds

You can build for specific rendering backends:

# Software renderer (default)
./wasm_build.sh sw {absolute path}/emsdk/

# WebGL renderer
./wasm_build.sh gl {absolute path}/emsdk/

# WebGPU renderer
./wasm_build.sh wg {absolute path}/emsdk/

# Lite versions (smaller binary size)
./wasm_build.sh sw-lite {absolute path}/emsdk/
./wasm_build.sh gl-lite {absolute path}/emsdk/

Build the Web Component

We use npm package manager to build and package web components.

# Install dependencies
npm install

# Build library
npm run build

Important: The environment variable EMSDK needs to be configured:

export EMSDK={absolute path}/emsdk

Build Output Structure

You will have these folders in the ./dist directory:

  • ./ : Main library bundle
  • sw : Software Standard preset bundle
  • sw-lite : Software Lite preset bundle
  • gl : WebGL Standard preset bundle
  • gl-lite : WebGL Lite preset bundle

Each folder contains these bundle files:

  • lottie-player.js : Web component for browsers
  • lottie-player.js.map : Source map for lottie-player.js
  • lottie-player.esm.js : Web component for NPM, using ECMAScript module format
  • lottie-player.esm.js.map : Source map for lottie-player.esm.js
  • lottie-player.cjs.js : Web component for NPM, using CommonJS module format
  • lottie-player.cjs.js.map : Source map for lottie-player.cjs.js
  • lottie-player.d.ts : TypeScript type declaration file
  • thorvg.wasm : The ThorVG WebAssembly binary

Note: The thorvg.js file is automatically removed after the build process as it's not needed in the final bundle.

Testing Methods

To verify the results in the web library, you can use three different testing methods.

1. Local Testing

Build the library in watch mode, which will automatically rebuild it whenever files are changed.

# Build with watch mode
npm run build:watch

# Run local server to test (localhost:8080/example)
npx http-server .

Available Local Examples

The example/ directory contains the following test pages:

  • index.html : Default library example
  • benchmark.html : Monitor FPS/Memory Usage with multiple canvases
  • lottie.html : Multiple animation check
  • software.html : Example for software preset binary
  • software-lite.html : Example for software lightweight preset binary
  • webgl.html : Example for WebGL preset binary
  • webgl-lite.html : Example for WebGL lightweight preset binary
  • webgpu.html : Example for WebGPU engine

2. Frontend Framework Testing

Framework testing is necessary to ensure that new updates do not compromise the library's stability.

You can replace the published package with your local build:

cd /path/to/any/npm-project
npm uninstall @thorvg/lottie-player
npm install /path/to/thorvg.web

Framework Examples

We strongly recommend testing with major frameworks:

3. ThorVG Viewer Testing

You can test the ThorVG Viewer with the new WebAssembly code.

# Prepare the ThorVG viewer
git clone https://github.com/thorvg/thorvg.viewer.git

# Copy the ThorVG WebAssembly code to the ThorVG viewer
cp ./dist/thorvg.wasm ./dist/lottie-player.js /path/to/thorvg.viewer

# Move to the thorvg.viewer repo and run index.html in your browser
{absolute path}/emsdk/upstream/emscripten/emrun --browser chrome ./index.html

Performance Testing

ThorVG Performance Test

You can test the latest WASM binary with the hosted perf-test.

Local Performance Testing

  1. Follow the "Build the Web Component" section above
  2. Build local perf-test:
# Install local lottie-player component in perf-test
cd ./perf-test
npm install --save ../

# Build perf-test
npm run build

# After build step, you should have ./out directory in ./perf-test

# Host the built application
npx http-server ./out

Clone this wiki locally