# Tutorial: Build Your First .lottie File
A hands-on, start-to-finish tutorial that walks you through packaging a Lottie animation into a .lottie file with dotlottie-js, then loading it back.

# 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](https://lottiefiles.com/) 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`:

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

```bash
npm install @dotlottie/dotlottie-js
```

## Step 3: Create the build script

Create a new file called `build.mjs`:

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

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

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

```bash
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](/docs/tools/dotlottie-js/how-to-guides)
- Look up every method and option on `DotLottie`: see the [API reference](/docs/tools/dotlottie-js/reference)
- Understand the `.lottie` archive structure and manifest schema: see [Format Versions](/docs/tools/dotlottie-js/reference/format-versions)