# How to Create a .lottie File
A task-focused guide to building a .lottie package from scratch using DotLottieBuilder.

# How to Create a .lottie File

Use [`DotLottieBuilder`](/docs/tools/dotlottie-io/api/dotlottie-builder-class) whenever you're assembling a package from scratch rather than modifying one that already exists.

## Assemble the content

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

const builder = new DotLottieBuilder();
builder.generator("my-tool v1.0");
builder.initialAnimation("intro");

builder.addAnimation("intro", readFileSync("intro.json"));
builder.addAnimation("hero", readFileSync("hero.json"));
builder.addTheme("dark", "Dark Theme", readFileSync("dark-theme.json"));
builder.addAudio("click.mp3", readFileSync("click.mp3"));
```

## Build

```javascript
const dl = builder.build();

console.log(dl.animationIds()); // ['intro', 'hero']
console.log(dl.audioFilenames()); // ['click.mp3']
```

`build()` validates the queued content and throws if anything is invalid — for example, an audio file that isn't `.mp3`.

## Save the result

```javascript
writeFileSync("output.lottie", dl.toBytes());
```

## Adding more content after build()

`build()` returns a regular [`DotLottie`](/docs/tools/dotlottie-io/api/dotlottie-class) instance, so you can keep adding to it with the same methods used during building:

```javascript
dl.addImage("logo.png", readFileSync("logo.png"));
writeFileSync("output.lottie", dl.toBytes()); // re-serialize with the new image included
```

## Producing an encrypted file directly

If the package should be distributed encrypted, pass a password to `toBytes()` instead of a separate step — see [Password-Protecting Files](/docs/tools/dotlottie-io/guides/password-protecting-files).

## Related

- [Managing Animations](/docs/tools/dotlottie-io/core-concepts/animations)
- [Managing Assets](/docs/tools/dotlottie-io/core-concepts/assets)
- [`DotLottieBuilder` API reference](/docs/tools/dotlottie-io/api/dotlottie-builder-class)