Skip to content

Development Guide

Jump to bottom
Hermet Park edited this page Dec 22, 2025 · 4 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

# Enter ThorVG directory
cd ./thorvg

# If build_wasm exists, remove it
rm -rf ./build_wasm

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

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

Build the Web Component

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

# Enter the ThorVG web directory
cd ./thorvg.web

# 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

  • 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
cd ./thorvg.web
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 ./thorvg.web/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