# dotlottie-io
Discover dotlottie-io, a Rust-powered library for creating, reading, and modifying .lottie files, with native Node.js and WebAssembly bindings.

# 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`](https://www.npmjs.com/package/@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](https://dotlottie.io/) or in this portal's [dotLottie format reference](/docs/format/dotlottie).

### 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`](/docs/tools/dotlottie-io/api/dotlottie-builder-class)
- **Read Files Two Ways**: Fully load a package with [`DotLottie`](/docs/tools/dotlottie-io/api/dotlottie-class), or inspect it lazily and with low memory overhead using [`DotLottieReader`](/docs/tools/dotlottie-io/api/dotlottie-reader-class)
- **Merge Packages**: Combine multiple `.lottie` files with configurable collision handling via [`DotLottieMerger`](/docs/tools/dotlottie-io/api/dotlottie-merger-class)
- **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](https://github.com/lottiefiles/dotlottie-io) |

## Quick Start

### Installation

```bash
# 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)

```javascript
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:

```javascript
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:

```javascript
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`](/docs/tools/dotlottie-io/api/dotlottie-reader-class) to pull a single animation or asset out of a large `.lottie` file without loading the whole archive into memory:

```javascript
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:

```javascript
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](/docs/tools/dotlottie-io/guides/migrating-from-dotlottie-js) 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](/en/runtimes/) 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         |

## Next Steps

### Getting Started

- **[Introduction](/docs/tools/dotlottie-io/getting-started/introduction)**: What dotlottie-io is and why it exists
- **[Installation](/docs/tools/dotlottie-io/getting-started/installation)**: Set up dotlottie-io in your project
- **[Quick Start: Creating](/docs/tools/dotlottie-io/getting-started/creating)**: Build your first `.lottie` file
- **[Quick Start: Loading](/docs/tools/dotlottie-io/getting-started/loading)**: Load and inspect an existing file

### Core Concepts

- **[Architecture](/docs/tools/dotlottie-io/core-concepts/architecture)**: The four core classes and when to use each
- **[Managing Animations](/docs/tools/dotlottie-io/core-concepts/animations)**
- **[Managing Assets](/docs/tools/dotlottie-io/core-concepts/assets)**

### Guides

- **[Migrating from dotlottie-js](/docs/tools/dotlottie-io/guides/migrating-from-dotlottie-js)**
- **[Merging .lottie Files](/docs/tools/dotlottie-io/guides/merging-lottie-files)**
- **[Password-Protecting Files](/docs/tools/dotlottie-io/guides/password-protecting-files)**

### Reference

- **[API Reference](/docs/tools/dotlottie-io/api)**: Complete API documentation

### Ecosystem

- **[dotlottie.io](https://dotlottie.io/)**: Official format specification
- **[dotLottie Players](/en/runtimes/)**: Render `.lottie` files
- **[dotlottie-js](/docs/tools/dotlottie-js)**: The predecessor JavaScript library