# Migration Guide for dotlottie-js
Guide for migrating dotlottie-js from pre-1.0.0 versions. Learn about API changes, V2 focus, and new features like themes and state machines.

# Migration Guide (from pre-1.0.0)

This guide is for users migrating from `dotlottie-js` versions **prior to 1.0.0** to versions 1.0.0 and above.

Significant changes were introduced around the 1.0.0 release, primarily to:

- Fully embrace the **dotLottie V2 specification**, including support for [themes](/docs/tools/dotlottie-js/advanced/theming) and [state machines](/docs/tools/dotlottie-js/advanced/state-machines).
- Introduce a more robust and consistent API centered around the [`DotLottie`](/docs/tools/dotlottie-js/api/dotlottie-class) class (for V2) and [`DotLottieV1`](/docs/tools/dotlottie-js/api/dotlottie-v1-class) class (for V1 interaction).
- Streamline the library structure and export strategy.

## Key Changes and How to Adapt

### 1. Class-Based Approach: `DotLottie` (V2 Focus) & `DotLottieV1`

- **Previously:** Development might have relied more on standalone functions or potentially different class structures.
- **Now:** The primary interaction is through the `DotLottie` class (for V2 features and handling V1/V2 loading) and the `DotLottieV1` class (specifically for V1 creation).

### 1.1. Automatic V1 to V2 Conversion on Load

A key aspect of the modern `DotLottie` class is its ability to handle older V1 format files gracefully. When you load an `ArrayBuffer` from a V1 `.lottie` file using methods like `new DotLottie().fromArrayBuffer()` or `new DotLottie().fromURL()` on a `DotLottie` (V2) instance, the library **automatically converts the V1 data internally** into a V2-compatible structure.

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

// Assume 'v1ArrayBuffer' contains the ArrayBuffer of a V1 .lottie file
async function loadV1File(v1ArrayBuffer) {
  const dotlottie = new DotLottie().fromArrayBuffer(v1ArrayBuffer);
  // The 'dotlottie' instance now holds the data in a V2 structure
  // and can be interacted with using the V2 API.
  // Exporting this instance will result in a V2 .lottie file.
}
```

This means you can generally use the standard `DotLottie` class to load most `.lottie` files, and the library takes care of the underlying version handling for loading purposes. Exporting will always produce a V2 file from a `DotLottie` instance.

### 2. Creation

`new DotLottie()` Preferred for V2, `new DotLottieV1()` or `makeDotLottie('v1')` for V1

- **Previously:** Older utilities might have been the primary way to create V1 instances.
- **Now:**

  - For V2 features (themes, state machines) or loading unknown files, use: `new DotLottie()`. See [`DotLottie`](/docs/tools/dotlottie-js/api/dotlottie-class).
  - To explicitly create a V1 instance, you can use either:
    - `new DotLottieV1()`: Offers class-based methods for configuration. See [`DotLottieV1`](/docs/tools/dotlottie-js/api/dotlottie-v1-class).
    - `makeDotLottie('v1')`: A factory function that returns a `DotLottieV1` instance when passed the version argument `'v1'`. See [`makeDotLottie()`](dotlottie-js-API-Utilities#makedotlottie).

  ```javascript
  import { DotLottie, DotLottieV1, makeDotLottie } from "@dotlottie/dotlottie-js";

  // V2 Approach (Recommended for new projects / V2 features)
  const dlV2 = new DotLottie();
  dlV2.addAnimation({
    id: "anim",
    data: {
      /* ... */
    },
  });
  dlV2.addTheme({
    id: "dark",
    data: {
      /* ... */
    },
  });

  // Explicit V1 Creation (Option A: Class)
  const dlV1_class = new DotLottieV1();
  dlV1_class.addAnimation({
    id: "anim_v1",
    data: {
      /* ... */
    },
  });

  // Explicit V1 Creation (Option B: Utility Function)
  const dlV1_util = makeDotLottie("v1");
  dlV1_util.addAnimation({
    id: "anim_v1_alt",
    data: {
      /* ... */
    },
  });
  ```

If you encounter specific issues, refer to the library's GitHub repository for examples or consider opening an issue.

Next up: [Understanding the dotLottie Format Overview](/docs/tools/dotlottie-js/getting-started/format-overview)