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 and state machines.
Introduce a more robust and consistent API centered around the DotLottie class (for V2) and DotLottieV1 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.

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.
To explicitly create a V1 instance, you can use either:
- new DotLottieV1(): Offers class-based methods for configuration. See DotLottieV1.
- makeDotLottie('v1'): A factory function that returns a DotLottieV1 instance when passed the version argument 'v1'. See makeDotLottie().

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: {
    /* ... */
  },
});

3. API Changes: V2 `DotLottie` Methods

Previously: V1 creation might have involved direct manipulation or simpler methods.

4. Asset Handling (Animations, Images, Audio)

Previously: Asset addition or handling might have been managed differently.
Now: Assets like images and audio are typically included within the Lottie JSON data you provide to dotlottie.addAnimation() (see Managing Animations and Managing Assets). The library automatically detects these assets during the await dotlottie.build() step and bundles them into the .lottie archive.
- You add animations using dotlottie.addAnimation({ id: 'anim1', data: lottieJsonWithAssets, /* ... */ }) or dotlottie.addAnimation({ id: 'anim1', url: '...', /* ... */ }).
- You generally do not call separate addImage or addAudio methods on the DotLottie instance itself. Asset management is implicit based on the content of the animations added.

5. Building the Archive: `dotlottie.build()`

Previously: The build or export step might have been different.
Now: After adding all content, you must call the asynchronous await dotlottie.build() method. This step finalizes the archive, processes assets, fetches data from URLs (if url was used in addAnimation), and generates the manifest. See The DotLottie Instance and DotLottie.build().

6. Exporting: `download()`, `toArrayBuffer()`, `toBlob()`, `toBase64()`

Previously: Export functions might have been named differently or had different capabilities.
Now: The DotLottie instance provides several asynchronous export methods after build(): See Exporting and DotLottie export methods.
- await dotlottie.download('filename.lottie') (Browser)
- await dotlottie.toArrayBuffer()
- await dotlottie.toBlob() (Browser)
- await dotlottie.toBase64()

7. Themes and State Machines (New V2 Features)

These were not primary features in pre-1.0.0 versions.
Now: The DotLottie class has dedicated methods for managing these: See Managing Themes and Managing State Machines.
- dotlottie.addTheme({ id: 'theme1', data: themeJson })
- dotlottie.addStateMachine({ id: 'sm1', data: stateMachineJson })
- Access them via dotlottie.themes and dotlottie.stateMachines.

8. Plugin System and Content Classes

Previously: The internal plugin system or specific content classes might have been exposed or used differently.
Now: The plugin system (addPlugins) and most individual content/error handling classes are generally internal utilities. Interact primarily through the main DotLottie (or DotLottieV1) class methods.

General Recommendations

Review the New API: Familiarize yourself with the DotLottie class methods detailed in the Core Concepts and API Reference sections.
Focus on DotLottie for V2: Use the DotLottie class for its comprehensive V2 support, unless specific V1 structure requirements exist.
Test Thoroughly: After migrating, test your workflows to ensure expected behavior.

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

Migration Guide for dotlottie-js