> ## 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.

# Type-Safe Names

> Generate Register types from MJCF for typed bodies, joints, actuators, sensors, sites, geoms, and keyframes

mujoco-react uses TypeScript declaration merging for model resource names. The recommended workflow is to let the Vite plugin scan your model files and write a checked-in generated type artifact.

## Vite Plugin

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

export default defineConfig({
  plugins: [
    react(),
    mujocoReact({
      models: {
        franka: "models/panda/scene.xml",
      },
    }),
  ],
});
```

The plugin writes `src/mujoco-register.gen.ts` during dev and build. Commit it. Vite auto-loads this file, so application code imports generated values from `mujoco-react`, not from the generated file:

```ts theme={null}
// Auto-generated by mujoco-react. Do not edit.

import { registerModelResources } from "mujoco-react";

const generatedModelResources = {
  franka: {
    actuators: { joint1: "joint1", joint2: "joint2", gripper: "gripper" },
    sensors: { imu_gyro: "imu_gyro" },
    bodies: { link0: "link0", hand: "hand" },
    joints: { joint1: "joint1", joint2: "joint2" },
    sites: { tcp: "tcp" },
    geoms: { floor: "floor" },
    keyframes: { home: "home" },
  },
};

registerModelResources(generatedModelResources);

declare module "mujoco-react" {
  interface Register {
    models: {
      franka: {
        actuators: "joint1" | "joint2" | "gripper";
        sensors: "imu_gyro";
        bodies: "link0" | "hand";
        joints: "joint1" | "joint2";
        sites: "tcp";
        geoms: "floor";
        keyframes: "home";
      };
    };
    actuators: "joint1" | "joint2" | "gripper";
    sensors: "imu_gyro";
    bodies: "link0" | "hand";
    joints: "joint1" | "joint2";
    sites: "tcp";
    geoms: "floor";
    keyframes: "home";
  }
}
```

The package exports are then typed and populated:

```tsx theme={null}
import { ModelActuators, ModelBodies, ModelSites, useCtrl, useIkController } from "mujoco-react";

useCtrl(ModelActuators.franka.gripper);
useIkController({ siteName: ModelSites.franka.tcp });
api.applyForce(ModelBodies.franka.hand, force);
```

## Per-Model Helpers

The global unions keep existing hooks ergonomic. For reusable model-specific controllers, use generated resource values:

```tsx theme={null}
import { ModelActuators, ModelJoints, ModelSites, useCtrl, useIkController } from "mujoco-react";

function FrankaController() {
  const gripper = useCtrl(ModelActuators.franka.gripper);
  const ik = useIkController({
    siteName: ModelSites.franka.tcp,
    joints: [ModelJoints.franka.joint1, ModelJoints.franka.joint2],
    actuators: [ModelActuators.franka.actuator1, ModelActuators.franka.actuator2],
  });

  return null;
}
```

This keeps a Franka controller from accidentally depending on resources that are not part of the configured model. Generic helpers like `ModelActuators<"franka">` are still available for reusable library code.

## Multiple Models

Add more entries to `models` when an app ships multiple models. Names from all configured models are merged into the global `Register` unions, while `Register.models` keeps package exports such as `ModelActuators.franka.gripper` scoped to the right model.

## CLI Fallback

Use the CLI for non-Vite projects or one-off generation:

```bash theme={null}
npx mujoco-react codegen franka=models/panda/scene.xml
```

Legacy alias:

```bash theme={null}
npx mujoco-react-codegen franka=models/panda/scene.xml
```

## Options

| Option              | Type                                           | Default                      | Description                                                                 |
| ------------------- | ---------------------------------------------- | ---------------------------- | --------------------------------------------------------------------------- |
| `models`            | `string \| string[] \| Record<string, string>` | required                     | Entry MJCF/URDF files to scan. Use a record for stable per-robot type names |
| `generatedRegister` | `string`                                       | `src/mujoco-register.gen.ts` | Output generated resource module                                            |
| `moduleName`        | `string`                                       | `mujoco-react`               | Module to augment                                                           |
| `disableLogging`    | `boolean`                                      | `false`                      | Disable plugin console output                                               |