# Platform Notes
Learn about platform-specific behaviors and considerations for using dotlottie-js in Browser and Node.js environments.

# 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.
  ```javascript
  import { DotLottie } from "@dotlottie/dotlottie-js";
  ```
- **Loading Data:** Create a new instance loaded with data from a .lottie file:
  - [`await new DotLottie().fromURL(url)`](/docs/tools/dotlottie-js/reference/dotlottie-class#async-fromurlurl-string-promisethis): Available for fetching `.lottie` files directly from URLs using the browser's `fetch` API. Returns a new DotLottie instance.
  - [`await new DotLottie().fromArrayBuffer(buffer)`](/docs/tools/dotlottie-js/reference/dotlottie-class#async-fromarraybufferarraybuffer-arraybuffer-promisethis): Use with `ArrayBuffer` obtained from `fetch`, `<input type="file">`, `FileReader`, etc.
- **Exporting Data:**
  - [`dotlottie.download(filename)`](/docs/tools/dotlottie-js/reference/dotlottie-class#downloadfilename-string-promisevoid): Available to trigger a file download dialog.
  - [`dotlottie.toBlob()`](/docs/tools/dotlottie-js/reference/dotlottie-class#toblob-promiseblob): Available to export as a `Blob` object.
  - [`dotlottie.toArrayBuffer()`](/docs/tools/dotlottie-js/reference/dotlottie-class#toarraybuffer-promisearraybuffer) and [`dotlottie.toBase64()`](/docs/tools/dotlottie-js/reference/dotlottie-class#tobase64-promisestring) 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.
  ```javascript
  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)`](/docs/tools/dotlottie-js/reference/dotlottie-class#async-fromarraybufferarraybuffer-arraybuffer-promisethis): 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.

    ```javascript
    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()`](/docs/tools/dotlottie-js/reference/dotlottie-class#toarraybuffer-promisearraybuffer) and [`dotlottie.toBase64()`](/docs/tools/dotlottie-js/reference/dotlottie-class#tobase64-promisestring) are available.
    - Use `toArrayBuffer()` to get the data and save it using `fs.writeFile` (converting back to a Node.js `Buffer` first).
      ```javascript
      // 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`](/docs/tools/dotlottie-js/reference/dotlottie-class#addanimationanimationoptions-animationoptions-this), [`addTheme`](/docs/tools/dotlottie-js/reference/dotlottie-class#addthemetheme-theme-this), [`addStateMachine`](/docs/tools/dotlottie-js/reference/dotlottie-class#addstatemachinestatemachineoptions-statemachineoptions-this), and the [`build()`](/docs/tools/dotlottie-js/reference/dotlottie-class#build-promisethis) 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: [Migrate from pre-1.0](/docs/tools/dotlottie-js/how-to-guides/migrate-from-pre-1.0)