Platform Notes for dotlottie-js

dotlottie-js is an isomorphic JavaScript library, running in various environments. Certain functionalities, especially I/O and specific web APIs, behave differently depending on the platform.

1. Browser Environment

When running in a web browser:

• Import: Use the standard package import.

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

• Loading Data: Create a new instance loaded with data from a .lottie file:

  • await new DotLottie().fromURL(url): Available for fetching .lottie files directly from URLs using the browser's fetch API. Returns a new DotLottie instance.

  • await new DotLottie().fromArrayBuffer(buffer): Use with ArrayBuffer obtained from fetch, <input type="file">, FileReader, etc.

• Exporting Data:

  • dotlottie.download(filename): Available to trigger a file download dialog.

  • dotlottie.toBlob(): Available to export as a Blob object.

  • dotlottie.toArrayBuffer() and dotlottie.toBase64() are also available.

• Dependencies: Relies on browser APIs like fetch, Blob, URL.createObjectURL, FileReader, TextEncoder/TextDecoder.

• Web Workers: dotlottie-js can potentially be used within Web Workers for background processing, assuming worker environment supports necessary APIs (like fetch if loading by URL).

2. Node.js Environment

When running in Node.js:

• Import: Similar to loading in a browser environment, use the standard package import.

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

  This ensures Node-specific dependencies or implementations (if any) are used and avoids importing browser-only APIs.

• Loading Data: Create a new instance by loading data from a buffer:

  • new DotLottie().fromURL() is NOT available.

  • await new DotLottie().fromArrayBuffer(buffer): Use this after reading a file into a Node.js Buffer using the fs module and converting it to an ArrayBuffer to get a new instance of DotLottie.

    import fs from "fs/promises";
    import { DotLottie } from "@dotlottie/dotlottie-js";
    
    async function loadFileNode(filePath) {
      const nodeBuffer = await fs.readFile(filePath);
      // Convert Node.js Buffer to ArrayBuffer
      const arrayBuffer = nodeBuffer.buffer.slice(nodeBuffer.byteOffset, nodeBuffer.byteOffset + nodeBuffer.byteLength);
      const dotlottie = new DotLottie().fromArrayBuffer(arrayBuffer);
      return dotlottie;
    }
    // loadFileNode("path/to/file.lottie");

• Exporting Data:

  • dotlottie.download() is NOT available.

  • dotlottie.toBlob() is NOT available.

  • dotlottie.toArrayBuffer() and dotlottie.toBase64() are available.

    • Use toArrayBuffer() to get the data and save it using fs.writeFile (converting back to a Node.js Buffer first).

      // Assuming 'dotlottie' is an instance that has been built
      // const dotlottie = await loadFileNode("path/to/file.lottie");
      // await dotlottie.build(); // Ensure it's built if modifications were made
      const outputBuffer = await dotlottie.toArrayBuffer();
      await fs.writeFile("output.lottie", Buffer.from(outputBuffer));

• Dependencies: Relies on Node.js APIs like Buffer and potentially assumes a file system is accessible for typical use cases (though the core library doesn't directly perform file I/O itself, examples often use fs).

Cross-Platform Consistency

The core API of dotlottie-js (methods for adding content like addAnimation, addTheme, addStateMachine, and the build() method) is consistent across environments. Differences primarily arise in loading initial data and handling output (e.g., filesystem vs. browser downloads).

Always be mindful of the available I/O methods for your target environment.

Next up: Development & Project Info