@vvfx/lottie2ir

Lottie to Animation IR converter.

Contents

• Install
• Usage
• API
• Project structure
• Contributing
• License

Install

Node.js 22 or later is required.

pnpm add @vvfx/lottie2ir

Usage

Convert JSON

import { convertLottieToIR } from '@vvfx/lottie2ir';

const result = convertLottieToIR(lottieJSON, {
  resourceBaseUrl: 'https://cdn.example.com/animations/data.json',
});

console.info(result.scene.format); // animation-ir

convertLottieToIR accepts either a Lottie JSON object or a serialized JSON string. Relative image and font paths are resolved against the absolute resourceBaseUrl.

Extract ZIP input

import { convertLottieToIR, extractLottieFromZip } from '@vvfx/lottie2ir';

const extracted = await extractLottieFromZip(zipArrayBuffer);
const result = convertLottieToIR(extracted.json, { zipResources: extracted });

API

convertLottieToIR(input, options?)

• input: a Lottie JSON object or serialized JSON string.
• options.resourceBaseUrl: absolute base URL for relative image and font paths.
• options.zipResources: ZIP resource directory and Data URL map returned by extractLottieFromZip.
• Returns { scene: IRScene; diagnostics: ConversionDiagnostic[] } after validating the IR scene.

extractLottieFromZip(zipData)

Accepts a ZIP ArrayBuffer and returns the serialized JSON, resource Data URL map, and JSON directory.

Errors

LottieConverterError and LOTTIE_CONVERTER_ERROR_CODES are exported from the package root for JSON, ZIP, conversion pipeline, and IR validation failures.

Project structure

src/
├── convert-lottie-to-ir.ts            # Public conversion flow and IR boundary validation
├── assemble-ir-scene.ts               # IRScene and Composition assembly
├── extract-lottie-from-zip.ts         # Lottie JSON and resource extraction from ZIP input
├── parser/                             # Input, layer stack, and property parsing
├── converter/                          # Layer, asset, mask, shape, text, and transform conversion
├── common/                             # Types, error model, and identifier generation
└── index.ts                            # Stable public entry

Contributing

Use repository issues for questions and bug reports. Pull requests are welcome. Run the following checks after changing conversion behavior:

pnpm --filter @vvfx/lottie2ir test
pnpm --filter @vvfx/lottie2ir build

License

MIT © 2019-present Ant Group Co., Ltd.