========================================================================
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/
# Unignore packages (Fix for parent gitignore)
!packages/
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にアクセスしても接続不可となるが，再度起動
コマンドを実行すればいつでも再開可能である．
