MuJoCo WASMをNext.js/Webプロジェクトに導入する環境構築ガイド。WASMファイル配置、webpack設定、依存関係の設定パターン。mujoco wasm setup nextjs webpack environment
MuJoCo物理シミュレーションエンジンをWebAssembly経由でNext.js/Webプロジェクトに導入するための環境構築ガイド。
public/mujoco/ ディレクトリにWASMファイルを配置するmujoco_wasm.js — EmscriptenのJSグルーコードmujoco_wasm.wasm — WASMバイナリ本体public/ ディレクトリから静的配信される（パスは /mujoco/mujoco_wasm.js 等）public/
mujoco/
mujoco_wasm.js
mujoco_wasm.wasm
{
"@react-three/fiber": "^9.5.0",
"@react-three/drei": "^10.7.7",
"three": "^0.183.2"
}
public/ ディレクトリに直接配置するパターンが安定@mujoco/mujoco、mujoco_wasm_contrib、mujoco-js、mujoco-react も存在するが、直接WASMファイル配置の方が制御しやすく依存関係の問題が起きにくいconst nextConfig: NextConfig = {
reactStrictMode: true,
webpack: (config, { isServer }) => {
if (!isServer) {
config.resolve.fallback = {
fs: false,
path: false,
crypto: false,
module: false,
worker_threads: false,
};
}
return config;
},
};
false に設定必須fs, path, crypto, module, worker_threads"target": "ES2017" 以上を指定（async/await、dynamic import対応のため）"moduleResolution": "bundler"（Next.js向け推奨設定）EmscriptenのJSグルーコードはデフォルトで同ディレクトリからWASMを探すが、Next.jsの配信パスと一致しない場合がある。locateFile コールバックでパスを明示的に指定する。
const mujoco = await load({
locateFile: (file: string) => `/mujoco/${file}`,
});
MuJoCoのWASMロードやThree.jsのWebGLコンテキストはブラウザAPIに依存するため、コンポーネントに "use client" を必ず付与する。
"use client";
import { useEffect, useRef } from "react";
| 症状 | 原因 | 対処 |
|---|---|---|
| WASMファイルが見つからない（404） | パスの不一致 | locateFile コールバックでパスを明示指定 |
Module not found: Can't resolve 'fs' | webpack fallback未設定 | next.config.ts の fallback設定を確認 |
| ハイドレーションエラー | SSRでブラウザAPIを呼び出している | コンポーネントに "use client" を付与 |
| WASMが初期化されない | dynamic importの非同期処理漏れ | useEffect 内で await を正しく使用 |
| WebGL contextエラー | Three.jsのCanvas重複 | <Canvas> の重複マウントを確認 |