======================================================================== Pixel Paint War - 環境構築ガイド (Environment Setup Guide) ======================================================================== 1. 事前準備 (Prerequisites) ------------------------------------------------------------------------ 1-0. 目的 本ドキュメントは，「Pixel Paint War」のMonorepo構成による開発環境を構築 するための手順書である． ※ 本プロジェクトは Node.js v20 LTS 以上を必須とする． 1-1. 必須ツールのインストール 開発を開始する前に，以下のツールをインストールしバージョンを確認する． 1. Node.js (v20.x LTS) ・Nodesource リポジトリを使用してインストールする． # リポジトリのセットアップとインストール $ curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - $ sudo apt-get install -y nodejs ・確認コマンド: $ node -v # v20.x.x と表示されること 2. pnpm (Package Manager) ・Node.js 標準の npm ではなく pnpm を使用する． ・Corepack (Node.js同梱) を有効化してインストールする． $ sudo corepack enable $ corepack prepare pnpm@latest --activate ・確認コマンド: $ pnpm -v 2. プロジェクト初期化 (Project Initialization) ------------------------------------------------------------------------ 2-1. ディレクトリ作成と初期化 1. プロジェクトルートの作成 任意の場所にプロジェクトフォルダを作成し，移動する． $ mkdir SkillSemiWebGame $ cd SkillSemiWebGame 2. Gitの初期化 $ git init 3. pnpm の初期化 $ pnpm init 2-2. ワークスペース設定 (Monorepo Setup) ルートディレクトリに以下の設定ファイルを作成し，モノレポ構成を定義する． 1. pnpm-workspace.yaml ・packages/shared を共通ライブラリとし，apps 配下にアプリを配置する． ・内容: packages: - 'apps/*' - 'packages/*' 2. .npmrc ・依存関係解決の設定を行う (shamefully-hoist=true 推奨)． ・内容: shamefully-hoist=true 2-3. ディレクトリ構造の構築 以下の構成になるようにディレクトリを作成する． root/ ├── apps/ │ ├── client/ # フロントエンド (Browser) │ └── server/ # バックエンド (Node.js) └── packages/ └── shared/ # 共通ロジック (Shared Library) ・作成コマンド例: $ mkdir -p apps/client apps/server packages/shared 2-4. Git除外設定 (Git Ignore Setup) 不要なファイル（依存ライブラリやビルド成果物）がGit管理下に置かれないよう， 除外設定を行う． 1. 設定ファイルの作成 プロジェクトルートディレクトリに `.gitignore` ファイルを作成する． $ touch .gitignore 2. 除外ルールの記述 以下の内容をファイルに記述し保存する． ・node_modules: 依存ライブラリフォルダ． ・dist, build: ビルド生成物． ・.env: 環境変数ファイル（セキュリティ保持のため）． # Dependencies node_modules/ .pnpm-store/ # Build Outputs dist/ build/ out/ # Logs *.log npm-debug.log* pnpm-debug.log* # Environment Variables .env .env.local .env.*.local # Editor / OS .vscode/* !.vscode/extensions.json !.vscode/settings.json !.vscode/launch.json .idea/ .DS_Store Thumbs.db # Testing coverage/ 3. 設定の反映確認 Gitのステータスを確認し，`node_modules/` 等が含まれていないことを確認する． $ git status 2-5. 初回コミット (Initial Commit) 環境構築の区切りとして，現在の状態をリポジトリに保存する． 1. ステータス確認 `.gitignore` が正しく適用されているか確認する． $ git status ※ `node_modules/` が表示されていないことを確認する． 2. ステージング 変更された全てのファイルをコミット対象に追加する． $ git add . 3. コミット実行 構築内容を示すメッセージを付与してコミットする． $ git commit -m "chore: Project initialization (Monorepo, pnpm, Vite)" 3. パッケージ・ライブラリ導入 (Dependency Installation) ------------------------------------------------------------------------ 3-1. 共通ライブラリ (packages/shared) 共通ロジック用のパッケージ設定を行う． 1. 初期化とビルドツール導入 $ cd packages/shared $ pnpm init $ pnpm add -D typescript tsup 2. 設定ファイルの調整 (package.json) ・name: "@repo/shared" と命名する（推奨）． ・main: "./dist/index.js", types: "./dist/index.d.ts" を指定する． ・scripts: "build": "tsup src/index.ts --format cjs,esm --dts" を追加する． 3. エントリーポイントの作成 tsupがビルド対象とするファイルを作成する． $ mkdir src $ touch src/index.ts ※ 現時点では空ファイルでよいが，将来的に constants.ts 等を export する記述を行う． (例: export * from './constants';) 4. TypeScript設定ファイルの作成 (tsconfig.json) ビルドと型定義生成のための設定ファイルを作成する． ・ファイル: packages/shared/tsconfig.json ・内容: { "compilerOptions": { "target": "ES2020", "module": "ESNext", "moduleResolution": "Bundler", "lib": ["ES2020", "DOM", "DOM.Iterable"], "declaration": true, "declarationMap": true, "sourceMap": true, "outDir": "./dist", "rootDir": "./src", "strict": true, "esModuleInterop": true, "skipLibCheck": true, "forceConsistentCasingInFileNames": true }, "include": ["src/**/*"], "exclude": ["node_modules", "dist"] } 3-2. フロントエンド (apps/client) Vite プロジェクトとして初期化を行う． 1. プロジェクト作成 $ cd ../../apps/client $ pnpm create vite . --template preact-ts ※ 実行中に表示される選択肢には以下のように回答すること： ? Use rolldown-vite (Experimental)? » No ? Install with pnpm and start now? » No 2. 依存ライブラリのインストール ・Pixi.js (描画エンジン) を追加する． ・共通ライブラリへの依存を追加する． $ pnpm add pixi.js $ pnpm add @repo/shared --workspace 3-3. バックエンド (apps/server) Node.js アプリケーションとして初期化を行う． 1. 初期化 $ cd ../../apps/server $ pnpm init 2. 依存ライブラリのインストール ・ws (WebSocket) を追加する． ・開発用ツール (tsx, typescript, @types/node, @types/ws) を追加する． ・共通ライブラリへの依存を追加する． $ pnpm add ws $ pnpm add -D tsx typescript @types/node @types/ws $ pnpm add @repo/shared --workspace 3. サーバー用ディレクトリとファイルの作成 tsxが実行対象とするエントリーポイントを作成する． $ mkdir src $ touch src/index.ts 4. 実行スクリプトの定義 package.json にサーバー起動用のコマンドを追加する． ・編集ファイル: apps/server/package.json ・内容: "scripts": { "dev": "tsx watch src/index.ts" } 5. TypeScript設定ファイルの作成 (tsconfig.json) 開発時の実行環境とパス解決のための設定ファイルを作成する． ・ファイル: apps/server/tsconfig.json ・内容: { "compilerOptions": { "target": "ES2022", "module": "NodeNext", "moduleResolution": "NodeNext", "lib": ["ES2022"], "strict": true, "noEmit": true, "esModuleInterop": true, "skipLibCheck": true, "forceConsistentCasingInFileNames": true, "baseUrl": ".", "paths": { "@repo/shared": ["../../packages/shared/src/index.ts"] } }, "include": ["src/**/*"], "exclude": ["node_modules"] } 4. 開発ツール設定 (Dev Tools Setup) ------------------------------------------------------------------------ 4-1. VS Code 拡張機能 推奨エディタである VS Code に以下の拡張機能をインストールする． ■ 必須拡張機能 ・ESLint ・Prettier - Code formatter ・EditorConfig for VS Code ■ 推奨拡張機能 ・Hex Editor (バイナリパケットのデバッグ用・Microsoft公式) ・GitHub Copilot 4-2. AI アシスタント設定 開発効率化のため，以下のAIツールのアカウント設定を確認する． 1. Gemini Pro ・学校提供ライセンスでのアクセス権限を確認する． 2. GitHub Copilot Pro ・Student Developer Pack が有効化されているか確認する． ・VS Code 右下のアイコンからログイン状態を確認する． 5. 構成確認 (Configuration Check) ------------------------------------------------------------------------ 5-1. 最終ディレクトリ構成 構築完了時点で，以下のディレクトリおよびファイルが存在することを確認する． SkillSemiWebGame/ <-- プロジェクトルート ├── .git/ <-- git init で作成 ├── .gitignore <-- Git除外設定 ├── .npmrc <-- 依存解決設定 ├── package.json <-- ルート定義 ├── pnpm-lock.yaml <-- pnpm install で自動生成 ├── pnpm-workspace.yaml <-- ワークスペース定義 ├── node_modules/ <-- 依存ライブラリ │ ├── apps/ <-- アプリケーション格納用 │ ├── client/ <-- フロントエンド (Vite + Preact) │ │ ├── node_modules/ │ │ ├── src/ │ │ │ ├── main.tsx (または index.tsx) │ │ │ └── ... (Viteテンプレートファイル群) │ │ ├── index.html │ │ ├── package.json <-- pixi.js, @repo/shared 依存あり │ │ ├── tsconfig.json │ │ └── vite.config.ts │ │ │ └── server/ <-- バックエンド (Node.js) │ ├── node_modules/ │ ├── src/ │ │ └── index.ts <-- エントリーポイント │ ├── package.json <-- ws, @repo/shared 依存あり │ └── tsconfig.json <-- pnpm init 等で生成（または要作成） │ └── packages/ <-- 共通パッケージ格納用 └── shared/ <-- 共通ロジック ├── node_modules/ ├── dist/ <-- ビルド後に生成される (index.js, index.d.ts) ├── src/ │ └── index.ts <-- 空または定数export用 ├── package.json <-- buildスクリプト定義あり └── tsconfig.json <-- tsup/typescript設定用 5-2. 重要ファイル設定確認 各パッケージの連携設定が正しいか確認する． ■ root/pnpm-workspace.yaml packages: - 'apps/*' - 'packages/*' ■ packages/shared/package.json ・name: "@repo/shared" ・main: "./dist/index.js" ・types: "./dist/index.d.ts" ■ apps/client/package.json ・dependencies: "@repo/shared": "workspace:*" ■ apps/server/package.json ・dependencies: "@repo/shared": "workspace:*" 6. 動作確認 (Verification) ------------------------------------------------------------------------ 6-1. ビルド確認 ルートディレクトリから全体の依存関係をインストールし，ビルドを試行する． $ cd ../../ $ pnpm install $ pnpm --filter @repo/shared build ※ shared のビルドが成功することを確認する． 6-2. 開発サーバー起動 モノレポ構成のため，個別のディレクトリに移動せず，プロジェクトルートから --filter オプションを使用して各アプリを起動する． ※ ターミナルを2つ開き，両方を同時に起動した状態で開発を進めることを推奨． 1．Client (フロントエンド) の動作確認 ・ルートディレクトリにて以下のコマンドを実行する． $ pnpm --filter client dev ・ブラウザでの確認: ターミナルに「➜ Local: http://localhost:5173/」と表示されたら， Google Chrome等のブラウザを開き，アドレスバーに上記URLを貼り付けて実行する． ・正常動作の判断基準: 画面に「Vite + Preact」のロゴと「Vite + Preact + TypeScript」といった テキストが表示されていれば，フロントエンドの環境構築は成功である． 2. Server (バックエンド) の動作確認 ・テスト用コードの作成: 動作確認用のエントリーポイントを作成する． $ touch apps/server/src/index.ts ファイルに以下の内容を記述する． console.log("Server is running!"); ・コマンド: $ pnpm --filter server dev ・正常動作の判断基準: ターミナルに「Server is running!」と出力されれば構築成功である． 3．終了方法 (重要) ・動作確認を終了し，開発サーバーを停止させる場合は，ターミナル上で 「Ctrl + C」を押下する． ・停止後はブラウザでURLにアクセスしても接続不可となるが，再度起動 コマンドを実行すればいつでも再開可能である．