React Three Fiber ベストプラクティス

React Three Fiber と Poimandres エコシステムの包括的ガイド。12 カテゴリにわたる 70+ のルールを含み、影響度順に優先付けされています。

ソースとクレジット

Utsubo による 100 Three.js Tips からの追加ヒント

適用場面

以下の場合にこれらのガイドラインを参照してください：

• 新しい R3F コンポーネントを作成する時
• R3F パフォーマンスを最適化する時（再レンダリングが #1 の問題）
• Drei ヘルパーを正しく使用する時
• Zustand で状態を管理する時
• ポストプロセッシングまたはフィジックスを実装する時

エコシステムのカバレッジ

• @react-three/fiber - Three.js 用 React レンダラー
• @react-three/drei - 便利なヘルパーと抽象化
• @react-three/postprocessing - ポストプロセッシングエフェクト
• @react-three/rapier - フィジックスエンジン
• zustand - 状態管理
• leva - デバッグ GUI

ルールカテゴリー（優先度順）

優先度	カテゴリ	影響度	プレフィックス
1	パフォーマンス・再レンダリング	重大	perf-
2	useFrame・アニメーション	重大	frame-
3	コンポーネントパターン	高	component-
4	Canvas・セットアップ	高	canvas-
5	Drei ヘルパー	中-高	drei-
6	ローディング・Suspense	中-高	loading-
7	状態管理	中	state-
8	イベント・インタラクション	中	events-
9	ポストプロセッシング	中	postpro-
10	フィジックス（Rapier）	低-中	physics-
11	Leva（デバッグ GUI）	低	leva-

クイックリファレンス

1. パフォーマンス・再レンダリング（重大）

• perf-never-set-state-in-useframe - useFrame 内で setState を呼び出さない
• perf-isolate-state - React 状態が必要なコンポーネントを分離する
• perf-zustand-selectors - 全ストアではなく Zustand セレクターを使用する
• perf-transient-subscriptions - 連続値に一時的なサブスクリプションを使用する
• perf-memo-components - 高コストなコンポーネントをメモ化する
• perf-keys-for-lists - 動的リストに安定したキーを使用する
• perf-avoid-inline-objects - JSX 内でオブジェクト/配列を作成しない
• perf-dispose-auto - R3F の自動破棄動作を理解する
• perf-visibility-toggle - 再マウントではなく表示/非表示を切り替える
• perf-r3f-perf - パフォーマンス監視に r3f-perf を使用する

2. useFrame・アニメーション（重大）

• frame-priority - 実行順序に priority を使用する
• frame-delta-time - アニメーションに常に delta を使用する
• frame-conditional-subscription - 不要な場合は useFrame を無効にする
• frame-destructure-state - 必要な値だけを分割代入する
• frame-render-on-demand - オンデマンドレンダリングに invalidate() を使用する
• frame-avoid-heavy-computation - 重い処理は useFrame の外に移動する

3. コンポーネントパターン（高）

• component-jsx-elements - Three.js オブジェクトに JSX を使用する
• component-attach-prop - 非標準プロパティに attach を使用する
• component-primitive - 既存オブジェクトに primitive を使用する
• component-extend - カスタムクラスに extend() を使用する
• component-forwardref - 再利用可能なコンポーネントに forwardRef を使用する
• component-dispose-null - 共有リソースに dispose={null} を設定する

4. Canvas・セットアップ（高）

• canvas-size-container - Canvas は親コンテナいっぱいに表示される
• canvas-camera-default - Canvas prop 経由でカメラを設定する
• canvas-gl-config - WebGL コンテキストを設定する
• canvas-shadows - Canvas レベルでシャドウを有効にする
• canvas-frameloop - 適切な frameloop モードを選択する
• canvas-events - イベントハンドリングを設定する
• canvas-linear-flat - 正しい色のために linear/flat を使用する

5. Drei ヘルパー（中-高）

• drei-use-gltf - プリロード付き useGLTF
• drei-use-texture - テクスチャ読み込みに useTexture を使用する
• drei-environment - リアルなライティングに Environment を使用する
• drei-orbit-controls - Drei の OrbitControls
• drei-html - DOM オーバーレイに Html を使用する
• drei-text - 3D テキストに Text を使用する
• drei-instances - 最適化されたインスタンシングに Instances を使用する
• drei-use-helper - デバッグ可視化に useHelper を使用する
• drei-bounds - カメラをフィットさせるのに Bounds を使用する
• drei-center - オブジェクトを中央配置するのに Center を使用する
• drei-float - フローティングアニメーションに Float を使用する

6. ローディング・Suspense（中-高）

• loading-suspense - 非同期コンポーネントを Suspense でラップする
• loading-preload - useGLTF.preload でアセットをプリロードする
• loading-use-progress - ローディング UI に useProgress を使用する
• loading-lazy-components - 重いコンポーネントを遅延ロードする
• loading-error-boundary - ローディングエラーを処理する

7. 状態管理（中）

• state-zustand-store - 焦点を絞った Zustand ストアを作成する
• state-avoid-objects-in-store - Three.js オブジェクトはストア内で注意する
• state-subscribeWithSelector - 細粒度のサブスクリプション
• state-persist - 必要に応じて状態を永続化する
• state-separate-concerns - 関心別にストアを分離する

8. イベント・インタラクション（中）

• events-pointer-events - メッシュにポインターイベントを使用する
• events-stop-propagation - イベントのバブリングを防ぐ
• events-cursor-pointer - ホバー時にカーソルを変更する
• events-raycast-filter - レイキャストをフィルタリングする
• events-event-data - イベントデータ構造を理解する

9. ポストプロセッシング（中）

• postpro-effect-composer - EffectComposer を使用する
• postpro-common-effects - 一般的なエフェクトリファレンス
• postpro-selective-bloom - 最適化されたグローに SelectiveBloom を使用する
• postpro-custom-shader - カスタムエフェクトを作成する
• postpro-performance - ポストプロセッシングを最適化する

10. フィジックス Rapier（低-中）

• physics-setup - 基本的な Rapier セットアップ
• physics-body-types - dynamic、fixed、kinematic
• physics-colliders - 適切なコライダーを選択する
• physics-events - 衝突イベントを処理する
• physics-api-ref - フィジックス API に ref を使用する
• physics-performance - フィジックスを最適化する

11. Leva（低）

• leva-basic - 基本的な Leva 使用法
• leva-folders - フォルダーで整理する
• leva-conditional - 本番環境では非表示にする

使用方法

詳細な説明とコード例については個別のルールファイルを参照してください：

rules/perf-never-set-state-in-useframe.md
rules/drei-use-gltf.md
rules/state-zustand-selectors.md

完全コンパイルドキュメント

すべてのルールを拡張した完全なガイド：../R3F_BEST_PRACTICES.md

重大パターン

useFrame 内で setState を使用しない

// 悪い例 - 1 秒に 60 回の再レンダリング！
function BadComponent() {
  const [position, setPosition] = useState(0);
  useFrame(() => {
    setPosition(p => p + 0.01); // これは絶対しないこと
  });
  return <mesh position-x={position} />;
}

// 良い例 - ref を直接ミューテートする
function GoodComponent() {
  const meshRef = useRef();
  useFrame(() => {
    meshRef.current.position.x += 0.01;
  });
  return <mesh ref={meshRef} />;
}

Zustand セレクター

// 悪い例 - ストアが変更されるたびに再レンダリング
const store = useGameStore();

// 良い例 - playerX が変更された時だけ再レンダリング
const playerX = useGameStore(state => state.playerX);

// より良い例 - 再レンダリングなし、直接ミューテーション
useFrame(() => {
  const { value } = useStore.getState();
  ref.current.position.x = value;
});

Drei useGLTF

import { useGLTF } from '@react-three/drei';

function Model() {
  const { scene } = useGLTF('/model.glb');
  return <primitive object={scene} />;
}

// 即座のロードのためプリロードする
useGLTF.preload('/model.glb');

Suspense ローディング

function App() {
  return (
    <Canvas>
      <Suspense fallback={<Loader />}>
        <Model />
      </Suspense>
    </Canvas>
  );
}

r3f-perf 監視

import { Perf } from 'r3f-perf';

function App() {
  return (
    <Canvas>
      <Perf position="top-left" />
      <Scene />
    </Canvas>
  );
}

表示/非表示を切り替える（再マウントではなく）

// 悪い例：再マウントすると破棄され再作成される
{showModel && <Model />}

// 良い例：可視性を切り替える、インスタンスを維持
<Model visible={showModel} />