Tutorial: Build Your First .lottie File

In this tutorial, we'll set up a small Node.js project, use dotlottie-js to package a Lottie animation into a .lottie file, save it to disk, and then load that file back and inspect what's inside it.

By the end, you'll have a working .lottie file on your machine and a script that can both create and read .lottie archives.

Prerequisites

• Node.js 18 or later installed

• A Lottie animation JSON file. If you don't have one, download any free animation from LottieFiles as a .json file and rename it to animation.json

Step 1: Set up the project

Create a new folder for the project and set up a package.json:

mkdir my-first-dotlottie
cd my-first-dotlottie
npm init -y

Now place your animation.json file in this folder.

Step 2: Install dotlottie-js

npm install @dotlottie/dotlottie-js

Step 3: Create the build script

Create a new file called build.mjs:

import fs from "fs";
import { DotLottie } from "@dotlottie/dotlottie-js";

const animationData = JSON.parse(fs.readFileSync("./animation.json", "utf-8"));

async function buildDotLottie() {
  const dotlottie = new DotLottie();

  dotlottie.addAnimation({
    id: "my_animation",
    data: animationData,
  });

  await dotlottie.build();

  const buffer = await dotlottie.toArrayBuffer();

  fs.writeFileSync("output.lottie", Buffer.from(buffer));

  console.log("Created output.lottie");
}

buildDotLottie();

We're using .mjs so Node treats the file as an ES module without needing extra config in package.json.

Step 4: Run the build script

node build.mjs

You should see:

Created output.lottie

Notice that a new output.lottie file has appeared in your project folder. Open it with any archive tool (it's a ZIP file under the hood) and you'll find an animations/my_animation.json and a manifest.json inside.

Step 5: Load the file back

Now let's read the .lottie file we just created and confirm the animation is inside it. Create a second file called load.mjs:

import fs from "fs";
import { DotLottie } from "@dotlottie/dotlottie-js";

async function loadDotLottie() {
  const fileBuffer = fs.readFileSync("./output.lottie");

  const dotlottie = await new DotLottie().fromArrayBuffer(fileBuffer);

  console.log("Manifest:", dotlottie.manifest);
  console.log(
    "Animation IDs:",
    dotlottie.animations.map((animation) => animation.id)
  );
}

loadDotLottie();

Run it:

node load.mjs

You should see the manifest printed, followed by:

Animation IDs: [ 'my_animation' ]

This confirms that the animation you packaged in Step 3 round-tripped correctly through the .lottie file.

What you've built

You've created a Node.js script that packages a Lottie animation into a .lottie archive, and a second script that loads a .lottie archive and reads its contents. This create/build/export and load/inspect cycle is the foundation of everything else dotlottie-js does.

Next steps

• Add more than one animation, or bundle themes and state machines: see the how-to guides

• Look up every method and option on DotLottie: see the API reference

• Understand the .lottie archive structure and manifest schema: see Format Versions