dotlottie-io: Rust-Powered Creation and Manipulation of .lottie Files

Introduction

dotlottie-io is a Rust-powered library for creating, reading, and modifying .lottie files, published to npm as @lottiefiles/dotlottie-io with native Node.js (N-API) bindings and a WebAssembly build for the browser. It gives you a complete, synchronous read/write API over the dotLottie container format, backed by a shared Rust core.

What is dotLottie?

A dotLottie (.lottie) file is an open-source, zipped archive format that bundles:

Multiple Lottie animations (JSON files)
Image, font, and audio assets used by animations
Themes and state machines (dotLottie V2 features)
A manifest describing the package contents

Learn more about the format itself at dotlottie.io or in this portal's dotLottie format reference.

Role in the Lottie Ecosystem

dotlottie-io: Creates, reads, merges, and modifies .lottie archives
Players: Render and play .lottie files (web, mobile, frameworks)

Key Capabilities & Features

Core Operations

Create dotLottie Archives: Bundle animations, themes, state machines, and assets into a single .lottie file with DotLottieBuilder
Read Files Two Ways: Fully load a package with DotLottie, or inspect it lazily and with low memory overhead using DotLottieReader
Merge Packages: Combine multiple .lottie files with configurable collision handling via DotLottieMerger
Manage Assets: Add and retrieve images, fonts, and audio, with automatic filename deduplication
Query Relationships: Ask which animations use a given theme, state machine, or asset
Password Protection: Encrypt and decrypt archives with AES-256

Platform Support

Environment	Support	Notes
Node.js	✅ Full	Prebuilt native binary selected automatically — no build toolchain needed
Browser	✅ Full	WebAssembly build, initialized once via `await init()`
Rust	✅ Full	Usable directly as the `dotlottie-io` crate — see the GitHub repository

Quick Start

Installation

# npm
npm install @lottiefiles/dotlottie-io

# pnpm
pnpm add @lottiefiles/dotlottie-io

# yarn
yarn add @lottiefiles/dotlottie-io

Basic Usage: Build and Save (Node.js)

const { writeFileSync } = require("node:fs");
const { DotLottieBuilder } = require("@lottiefiles/dotlottie-io");

const builder = new DotLottieBuilder();
builder.generator("my-tool");
builder.addAnimation("hero", JSON.stringify(myLottieJson));

const dl = builder.build();
writeFileSync("output.lottie", dl.toBytes());

Common Use Cases

1. Build Pipeline Automation

Bundle animation JSON files into .lottie packages as part of a CI/CD step:

const { DotLottieBuilder } = require("@lottiefiles/dotlottie-io");
const { readFileSync, writeFileSync } = require("node:fs");
const { glob } = require("glob");

async function bundleAnimations() {
  const builder = new DotLottieBuilder();
  builder.generator("build-pipeline");

  const files = await glob("src/animations/*.json");
  for (const file of files) {
    const id = file.match(/([^/]+)\.json$/)[1];
    builder.addAnimation(id, readFileSync(file));
  }

  const dl = builder.build();
  writeFileSync("dist/animations.lottie", dl.toBytes());
}

2. Server-Side Dynamic Generation

Assemble a customized .lottie file per request without blocking on async I/O:

const { DotLottieBuilder } = require("@lottiefiles/dotlottie-io");

function generateUserAnimation(baseAnimationBuffer, themeData) {
  const builder = new DotLottieBuilder();
  builder.addAnimation("base", baseAnimationBuffer);
  builder.addTheme("user-theme", "User Theme", JSON.stringify(themeData));

  return builder.build().toBytes();
}

3. Lazy Asset Extraction from Large Libraries

Use DotLottieReader to pull a single animation or asset out of a large .lottie file without loading the whole archive into memory:

const { DotLottieReader } = require("@lottiefiles/dotlottie-io");

const reader = DotLottieReader.open("large-library.lottie");
const heroJson = reader.getAnimationJson("hero"); // only this entry is read

4. Cross-Reference Auditing

Find unused assets or verify a theme is actually referenced before shipping:

const { DotLottie } = require("@lottiefiles/dotlottie-io");

const dl = DotLottie.fromFile("package.lottie");
const unusedImages = dl.imageFilenames().filter((filename) => dl.animationsUsingAsset(filename).length === 0);

Tool Comparison

dotlottie-io vs. dotlottie-js

Aspect	dotlottie-io	dotlottie-js
Core	Rust, with Node/WASM bindings	Pure JavaScript/TypeScript
API style	Synchronous, 4-class split	Async, single fluent `DotLottie` class
URL fetching	Not built in — you fetch, then pass bytes	Built in (`addAnimation({ url })`)
Lazy reading	✅ `DotLottieReader`	❌
Password protection	✅ AES-256	❌
Cross-reference queries	✅ 4 query methods	❌
npm package	`@lottiefiles/dotlottie-io`	`@dotlottie/dotlottie-js`

See the full migration guide for a detailed, code-for-code comparison.

Who Should Use dotlottie-io?

Use dotlottie-io when you need to:

Create .lottie files programmatically, in Node.js or the browser
Read or inspect .lottie files without loading the entire archive into memory
Merge multiple .lottie packages with predictable collision handling
Password-protect distributed .lottie files
Audit which animations reference a given theme, state machine, or asset

Not recommended for:

Simple animation playback — use a dedicated Player instead
Transforming or optimizing raw Lottie JSON structure — that's a separate concern from packaging

API Overview

The library exposes five main exports: DotLottie, DotLottieBuilder, DotLottieReader, DotLottieMerger, and the MergeStrategy enum.

Class	Purpose
`DotLottie`	Load, mutate, and serialize a `.lottie` package
`DotLottieBuilder`	Stateful builder for constructing a package
`DotLottieReader`	Lazy, read-only view — reads one entry at a time
`DotLottieMerger`	Merge multiple packages with a chosen collision strategy
`MergeStrategy`	`Rename`, `Skip`, or `Fail` — collision behavior

dotlottie-io