threejs-dev-setup

このスキルを使用するタイミング

ユーザーが次の内容に言及した場合は、必ずこのスキルを使用してください。

• 新しい three.js プロジェクト、Vite/Webpack/Rollup のエントリーポイント、またはブラウザーの importmap の作成や設定
• three パッケージのインストール、ドキュメントに合わせたバージョンの統一、または TypeScript のセットアップ（該当する場合は @types/three）
• three/addons/...、examples/jsm のインポートエラー、ESM と CJS の相互運用、またはベアスペシファイアの解決

重要：このスキルとランタイムに関するトピックの違い

• threejs-dev-setup = インストール方法、バンドラー、モジュールグラフ、アドオンのインポート元。
• threejs-renderers = WebGLRenderer / WebGPURenderer、キャンバス、ピクセル比、レンダーループ — プロジェクトの読み込み後。
• threejs-loaders = GLTFLoader、DRACOLoader、進行状況コールバック — インポートの解決後。

トリガーとなるフレーズの例：

• 「vite three.js」、「webpack three」、「import map」、「three/addons」、「モジュールが見つからない」、「jsm」
• 「新建项目」、「安装 three」、「找不到模块」、「ESM」、「TypeScript three」

このスキルの使い方

1. 配布モデルを確認する：SPA バンドラー（Vite/Webpack）、Node のツール、または importmap を使った静的 HTML のいずれかです。それぞれ three/addons/ の解決方法が異なります。
2. ドキュメントでユーザーが参照している内容と互換性のあるリリースに three のバージョンを固定します。アドオンのパスは公開されているパッケージの構成に従います。
3. 標準的なインポートを示す：コアは three から、コントロール／ローダー／エフェクトは three/addons/... からインポートします（ソースツリーでは examples/jsm に対応）。examples/workflow-scaffold.md を参照してください。
4. 最小限のループ：レンダラー、シーン、カメラ、メッシュを 1 つ作成し、requestAnimationFrame を使います。threejs-renderers の詳細を重複させずにツールチェーンを検証するにはこれで十分です。
5. TypeScript：バンドラーに適した moduleResolution を有効にし、型定義には three パッケージに含まれるものを参照します。バンドラーを使用しない HTML を対象とする場合を除き、グローバルな script タグのパターンを重複させないでください。
6. 失敗時：依存関係の不足、パスの誤り、SSR コンテキスト（window／document がない）を区別します。
7. さらに学ぶには：スキャフォールドが動作した後、ユーザーに three.js manual の最初の章を案内します。

ドキュメントマップ（公式）

ドキュメントのセクション	代表的なリンク
マニュアル（入門）	https://threejs.org/manual/
ドキュメントのインデックス	https://threejs.org/docs/
パッケージ／インストールの概要	https://www.npmjs.com/package/three

対象範囲

• 対象範囲内： npm／インストール、バンドラー、インポートマップ、three の基本的な TypeScript 設定、アドオンのインポートパス、最小限の検証用スニペット。
• 対象範囲外： WebGL の理論、完全なレンダーターゲットやポストプロセッシングスタック（threejs-renderers、threejs-postprocessing）、物理演算、「ビルドが実行される」ことを超えるデプロイ。

よくある落とし穴とベストプラクティス

• 1 つのページで複数の three を混在させるとシングルトンが壊れます。バンドラーのエイリアスを使って重複を解消してください。
• node_modules/.../examples/jsm の深いパスからアドオンをインポートする方法は壊れやすいため、利用できる場合はパッケージのエクスポート three/addons/... を優先してください。
• スニペットのデフォルト値（出力色空間）を示す際は、必ず r152+ のカラー管理ドキュメントに合わせてください。詳細は threejs-renderers/textures を案内してください。
• SSR フレームワークでは、WebGL コンテキストに対して動的インポートまたはクライアント専用コンポーネントが必要です。

ドキュメントとバージョン

ツールチェーンとインポートパスは、ユーザーがインストールする three npm パッケージのバージョンに従います。マニュアルとドキュメントはライブラリに合わせて更新されます。アドオンのパス（three/addons/...）は、そのリリースのパッケージ構成に一致させる必要があります。迷った場合は、バージョン番号と、最新のドキュメントに記載された正確なインポート行を示してください。

エージェントの回答チェックリスト

このスキルを使用して回答する際は、次の点を優先してください。

1. バンドラーまたはランタイム（Vite、Webpack、素の ESM、importmap）と、想定する three のバージョンを明記します。
2. セットアップに関する信頼できる情報源として、https://threejs.org/manual/ および／または https://threejs.org/docs/ へのリンクを含めます。
3. threejs-dev-setup（解決）と threejs-renderers（ランタイム API）の問題を区別します。
4. ユーザーが CDN／バンドラーなしの HTML を明示的に使用している場合を除き、グローバルな script タグを前提にしないでください。
5. 重複するシングルトンの問題が発生した場合は、package.json／ロックファイル内の three を重複排除することを推奨します。

参考資料

• https://threejs.org/manual/
• https://threejs.org/docs/
• https://www.npmjs.com/package/three

キーワード

英語： three.js、vite、webpack、rollup、import map、typescript、npm、three/addons、examples jsm、モジュール解決、スキャフォールド

中国語： three.js のインストール、ビルド、importmap、モジュール解決、three/addons、スキャフォールド、Vite、Webpack