# Platform Notes
Differences between using dotlottie-io in Node.js versus the browser, including WASM initialization and asset handling.

# Platform Notes

The `DotLottie`, `DotLottieBuilder`, `DotLottieReader`, and `DotLottieMerger` classes have an **identical API surface** in Node.js and the browser. The differences are in setup and a few environment-specific behaviors.

## Node.js

- The correct prebuilt native binary is selected automatically at install time via `optionalDependencies` — no build toolchain required.
- The API is available immediately after `require`/`import` — there's no async initialization step.
- All methods are **synchronous**. There's no `Promise`-based build or export step for local file operations.
- `DotLottieReader.open(path)` is available and holds a live file handle for low-memory, on-demand reads.

```javascript
const { DotLottie } = require("@lottiefiles/dotlottie-io");
// Ready to use immediately
```

## Browser (WASM)

- The WASM module must be **initialized once** before any class is usable:

  ```javascript
  import { init } from "@lottiefiles/dotlottie-io/web";

  const { DotLottie, DotLottieBuilder, DotLottieMerger, DotLottieReader } = await init();
  ```

- Two bundle formats are available — see [Installation](/docs/tools/dotlottie-io/getting-started/installation) for when to use each:
  - **ESM** (`@lottiefiles/dotlottie-io/web`): bundlers (Vite, webpack, Rollup) resolve and copy the `.wasm` file automatically via `import.meta.url`.
  - **IIFE** (`release/browser/dotlottie-io.iife.js`): for a plain `<script>` tag with no build step. The `.wasm` file must be served alongside the script, or you can pass an explicit URL:

    ```javascript
    const { DotLottie } = await DotLottieIO.init("/assets/dotlottie-io.wasm");
    ```

- `DotLottieReader.open(path)` is **not available** — there's no filesystem in WASM. Use `DotLottieReader.fromBytes(uint8Array)` instead.

- Pass `Uint8Array` values directly; the wasm-bindgen runtime manages WASM memory automatically — no manual allocation needed.

  ```javascript
  const { DotLottie } = await init();

  // From a FileReader result
  const dotlottie = DotLottie.fromBytes(new Uint8Array(fileReaderResult));

  // From a fetched buffer
  const json = await fetch("/animations/hero.json").then((r) => r.arrayBuffer());
  dotlottie.addAnimation("hero", new Uint8Array(json));
  ```

## What neither platform does for you

Unlike `dotlottie-js`, `dotlottie-io` doesn't fetch remote URLs or trigger browser downloads on your behalf:

- There's no `addAnimation({ url })` — fetch the JSON yourself, then pass the bytes.
- There's no `.download()` — build a `Blob` and trigger a download yourself from the `Uint8Array`/`Buffer` returned by `toBytes()`.

See the [migration guide](/docs/tools/dotlottie-io/guides/migrating-from-dotlottie-js) if you're replacing `dotlottie-js` code that relied on either of these.

Next up: [Migrating from dotlottie-js](/docs/tools/dotlottie-io/guides/migrating-from-dotlottie-js)