> ## Documentation Index
> Fetch the complete documentation index at: https://dadd.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Installation

> Install mujoco-react and its peer dependencies

## Install

```bash theme={null}
npm install mujoco-react @react-three/fiber @react-three/drei three
```

### Peer Dependencies

| Package              | Version   | Purpose                           |
| -------------------- | --------- | --------------------------------- |
| `@react-three/fiber` | `>=8`     | React renderer for Three.js       |
| `@react-three/drei`  | `>=9`     | R3F helpers (PivotControls, etc.) |
| `three`              | `>=0.180` | 3D rendering                      |
| `react`              | `>=18`    | React                             |

`@mujoco/mujoco` is installed by `mujoco-react` as the underlying MuJoCo WASM engine.

### TypeScript

```bash theme={null}
npm install -D @types/three
```

mujoco-react ships with full TypeScript types. No `@types/` package needed for the library itself.

## Bundler Setup

### Vite (Recommended)

`@mujoco/mujoco` ships a `.wasm` asset. Vite serves package WASM assets correctly with the standard React setup:

```ts theme={null}
// vite.config.ts
import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";

export default defineConfig({
  plugins: [react()],
});
```

### Next.js

Since MuJoCo uses WASM and browser APIs, it must run client-side only:

```tsx theme={null}
import dynamic from "next/dynamic";

const MujocoApp = dynamic(() => import("./MujocoApp"), { ssr: false });
```

### Create React App

Works out of the box. No additional configuration needed.

### Multi-Threaded WASM

`MujocoProvider` defaults to the single-threaded official MuJoCo WASM build. To opt into the official multi-threaded build:

```tsx theme={null}
import loadMujocoMt from "@mujoco/mujoco/mt";
import mtWasmUrl from "@mujoco/mujoco/mt/mujoco.wasm?url";

<MujocoProvider
  wasmVariant="auto"
  threadedLoader={loadMujocoMt}
  mtWasmUrl={mtWasmUrl}
>
  <App />
</MujocoProvider>
```

`"auto"` only loads the threaded build when `threadedLoader` and `mtWasmUrl` are provided and the browser reports `globalThis.crossOriginIsolated === true`. If you force `wasmVariant="threaded"`, your dev server and production host must send:

```txt theme={null}
Cross-Origin-Opener-Policy: same-origin
Cross-Origin-Embedder-Policy: require-corp
```

## Verify Installation

```tsx theme={null}
import { MujocoProvider, MujocoCanvas } from "mujoco-react";

function App() {
  return (
    <MujocoProvider>
      <MujocoCanvas
        config={{
          src: "https://raw.githubusercontent.com/google-deepmind/mujoco_menagerie/main/franka_emika_panda/",
          sceneFile: "scene.xml",
        }}
        style={{ width: "100%", height: "100vh" }}
        onReady={({ api }) => {
          console.log("MuJoCo loaded!", api.getBodies().map(({ name }) => name));
        }}
        onError={(err) => console.error("Load failed:", err)}
      >
        <ambientLight />
      </MujocoCanvas>
    </MujocoProvider>
  );
}
```

If you see a Franka Panda robot in your browser, everything is working.

<Note>
  The first load may take a few seconds as the WASM module initializes and model assets are fetched from GitHub. Subsequent loads are faster due to browser caching.
</Note>