Skip to content

Development Guide

Jump to bottom
Jinny You edited this page Jan 29, 2026 · 4 revisions

Building and Testing ThorVG Web Packages

This document provides comprehensive guidance for building and testing ThorVG web packages locally.

Overview

The ThorVG.Web monorepo contains two complementary packages:

Both packages share the same ThorVG WASM core and support multiple render backends.

Prerequisites

Required Tools

  • Node.js 20+ and pnpm 10+
  • Emscripten SDK - For WASM compilation
  • Meson & Ninja - Build system for ThorVG core

Environment Setup

Set the EMSDK environment variable:

export EMSDK={absolute path}/emsdk

You may also need to add Emscripten to your PATH:

export PATH=$EMSDK/upstream/emscripten:$PATH

Packages

@thorvg/lottie-player

Build from Source

cd packages/lottie-player

# Install dependencies
pnpm install

# Build all preset variants (sw, gl, wg, sw-lite, gl-lite, wg-lite)
pnpm run build

# Watch mode for development
pnpm run build:watch

Build Output Structure

The dist/ directory contains multiple preset folders:

  • Main bundle (./)
  • Standard presets - sw/, gl/, wg/
  • Lite presets - sw-lite/, gl-lite/, wg-lite/

Each folder includes:

  • lottie-player.js - Browser bundle
  • lottie-player.esm.js - ES Module bundle
  • lottie-player.cjs.js - CommonJS bundle
  • lottie-player.d.ts - TypeScript declarations
  • thorvg.wasm - WebAssembly binary

Note: thorvg.js is automatically removed during build as it's embedded in the bundle.

Backend-Specific WASM Build

To rebuild WASM bindings for a specific backend:

cd packages/lottie-player

# Build specific backend
sh ./wasm_player_build.sh sw $EMSDK     # Software renderer
sh ./wasm_player_build.sh gl $EMSDK     # WebGL renderer
sh ./wasm_player_build.sh wg $EMSDK     # WebGPU renderer

# Build lite variants (smaller binary)
sh ./wasm_player_build.sh sw-lite $EMSDK
sh ./wasm_player_build.sh gl-lite $EMSDK
sh ./wasm_player_build.sh wg-lite $EMSDK

@thorvg/webcanvas

Build from Source

cd packages/webcanvas

# Install dependencies
pnpm install

# Build package
pnpm run build

# Watch mode for development
pnpm run build:watch

Build Output Structure

The dist/ directory contains:

  • webcanvas.js - Browser bundle
  • webcanvas.esm.js - ES Module bundle
  • webcanvas.cjs.js - CommonJS bundle
  • webcanvas.d.ts - TypeScript declarations
  • thorvg.wasm - WebAssembly binary (supports all backends: sw/gl/wg)

Rebuild WASM Bindings

WebCanvas WASM includes all rendering backends in a single binary:

cd packages/webcanvas

# Rebuild WASM with all backends
sh ./wasm_wcanvas_build.sh $EMSDK

The build process:

  1. Builds ThorVG core library from thorvg/ submodule
  2. Builds WASM bindings from wasm/webcanvas/
  3. Uses cross-compilation configs from wasm/wasm32*.txt
  4. Outputs thorvg.{wasm,js,d.ts} to build_wasm_wcanvas/

Testing & Development Tools

Playground

You can explore various examples with hosted playground.

Local Setup

cd playground

# Install dependencies
yarn install

# Development mode (localhost:3001)
yarn dev

# Production build
yarn build
yarn start

Using Local WebCanvas Build

To test with a locally modified @thorvg/webcanvas:

# 1. Build webcanvas package
cd packages/webcanvas
pnpm install
pnpm run build

# 2. Link to playground
cd ../../playground
yarn add ../packages/webcanvas

# 3. Start dev server
yarn dev

Performance Testing

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

Local Setup

cd perf-test

# Install dependencies
yarn install

# Development mode (localhost:3000)
yarn dev

# Production build
yarn build
yarn start

Using Local Lottie Player Build

To test with a locally modified @thorvg/lottie-player:

# 1. Build lottie-player package
cd packages/lottie-player
pnpm install
pnpm run build

# 2. Link to perf-test
cd ../../perf-test
yarn add ../packages/lottie-player

# 3. Start dev server
yarn dev

Local Examples Testing

Test packages directly using the included HTML examples.

Lottie Player Examples

cd packages/lottie-player

# Build in watch mode
pnpm run build:watch

# In another terminal, serve examples
npx http-server . -p 8080
# Visit http://localhost:8080/examples/

Available examples in examples/:

  • software.html - Software renderer preset
  • software-lite.html - Software lite preset
  • webgl.html - WebGL renderer preset
  • webgl-lite.html - WebGL lite preset
  • webgpu.html - WebGPU renderer
  • benchmark.html - FPS/memory monitoring

WebCanvas Examples

cd packages/webcanvas

# Build in watch mode
pnpm run build:watch

# In another terminal, serve examples
npx http-server . -p 8080
# Visit http://localhost:8080/examples/

Available examples in examples/:

  • basic-usage.html - Getting started with shapes
  • animation-example.html - Frame-based animations
  • scene.html - Hierarchical grouping
  • picture-example.html - SVG and image loading
  • text-example.html - Typography and fonts
  • live-editor.html - Interactive code playground

Framework Integration Testing

Test packages in real-world framework environments to ensure compatibility.

Replace Published Package with Local Build

cd /path/to/your/project

# For lottie-player
npm uninstall @thorvg/lottie-player
npm install /path/to/thorvg.web/packages/lottie-player

# For webcanvas
npm uninstall @thorvg/webcanvas
npm install /path/to/thorvg.web/packages/webcanvas

Framework Examples

Test with the included framework examples:

  • React - examples/react/
  • Vue - examples/vue/
  • Svelte - examples/svelte/

Or use these CodeSandbox templates:

ThorVG Viewer Testing

Test WebAssembly binaries with the ThorVG Viewer.

# Clone ThorVG Viewer
git clone https://github.com/thorvg/thorvg.viewer.git

# Copy WASM files
cp packages/lottie-player/dist/thorvg.wasm packages/lottie-player/dist/lottie-player.js /path/to/thorvg.viewer

# Run with Emscripten
cd /path/to/thorvg.viewer
$EMSDK/upstream/emscripten/emrun --browser chrome ./index.html

Clone this wiki locally