Platform Notes

The DotLottie, DotLottieBuilder, DotLottieReader, and DotLottieMerger classes have an identical API surface in Node.js and the browser. The differences are in setup and a few environment-specific behaviors.

Node.js

The correct prebuilt native binary is selected automatically at install time via optionalDependencies — no build toolchain required.
The API is available immediately after require/import — there's no async initialization step.
All methods are synchronous. There's no Promise-based build or export step for local file operations.
DotLottieReader.open(path) is available and holds a live file handle for low-memory, on-demand reads.

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

Browser (WASM)

The WASM module must be initialized once before any class is usable:

import { init } from "@lottiefiles/dotlottie-io/web";

const { DotLottie, DotLottieBuilder, DotLottieMerger, DotLottieReader } = await init();

Two bundle formats are available — see Installation for when to use each:
- ESM (@lottiefiles/dotlottie-io/web): bundlers (Vite, webpack, Rollup) resolve and copy the .wasm file automatically via import.meta.url.
- IIFE (release/browser/dotlottie-io.iife.js): for a plain <script> tag with no build step. The .wasm file must be served alongside the script, or you can pass an explicit URL:
```
const { DotLottie } = await DotLottieIO.init("/assets/dotlottie-io.wasm");
```
DotLottieReader.open(path) is not available — there's no filesystem in WASM. Use DotLottieReader.fromBytes(uint8Array) instead.

Pass Uint8Array values directly; the wasm-bindgen runtime manages WASM memory automatically — no manual allocation needed.

const { DotLottie } = await init();

// From a FileReader result
const dotlottie = DotLottie.fromBytes(new Uint8Array(fileReaderResult));

// From a fetched buffer
const json = await fetch("/animations/hero.json").then((r) => r.arrayBuffer());
dotlottie.addAnimation("hero", new Uint8Array(json));

What neither platform does for you

Unlike dotlottie-js, dotlottie-io doesn't fetch remote URLs or trigger browser downloads on your behalf:

There's no addAnimation({ url }) — fetch the JSON yourself, then pass the bytes.
There's no .download() — build a Blob and trigger a download yourself from the Uint8Array/Buffer returned by toBytes().

See the migration guide if you're replacing dotlottie-js code that relied on either of these.

Next up: Migrating from dotlottie-js