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

// 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:

// 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:

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:

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:

npx mujoco-react codegen franka=models/panda/scene.xml

Legacy alias:

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