========================================================================
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. Docker環境での開発開始 (推奨手順)
------------------------------------------------------------------------
本プロジェクトは VS Code の Dev Containers 機能を使用する．
これにより Node.js, pnpm, ESLint 等の環境が自動構築される．
4-1. プロジェクトを開く
1. VS Codeを起動し，「ファイル > フォルダを開く」からプロジェクトルートを選択する．
4-2. コンテナでの再起動 (Reopen in Container)
以下のいずれかの方法で，開発環境をコンテナ内に移行する．
【方法A: ステータスバーから】
1. ウィンドウ左下の緑色(または青色)の「><」アイコンをクリックする．
2. 表示されるメニューから「Reopen in Container」を選択する．
【方法B: コマンドパレットから】
1. [F1] または [Ctrl+Shift+P] を押下する．
2. "Reopen" と入力し，「Dev Containers: Reopen in Container」を選択する．
4-3. 初回ビルドの待機
1. 初回起動時は Dockerイメージのビルドと npmパッケージのインストールが行われる．
(数分〜十数分かかる場合がある)
2. 右下に "Starting Dev Container" 等の通知が表示されている間は待機する．
4-4. 起動確認
1. 左下のアイコンが「Dev Container: Pixel Paint War Dev」と表示されていることを確認する．
2. VS Codeのターミナルを開き (`Ctrl + @`)，パスを確認する．
成功例: node@...:/workspace$
(Windowsのパス C:\Users... ではなく Linux形式になっていれば成功)
3. 動作確認コマンドを実行する．
$ pnpm --filter client dev
ブラウザで http://localhost:5173 にアクセスし，画面が表示されれば環境構築完了である．
5. 開発ツールの確認 (Tools Verification)
------------------------------------------------------------------------
Dockerコンテナ起動完了後、定義済みのツールが正しく自動導入されているか確認する．
※ 手動でのインストールは不要である．
5-1. VS Code 拡張機能
拡張機能サイドバーを開き、"Dev Container: Pixel Paint War Dev" セクションに
以下がインストール済みであることを確認する．
・ESLint
・Prettier - Code formatter
・EditorConfig for VS Code
・Hex Editor
・GitHub Copilot
5-2. AI アシスタント設定
GitHub Copilot Pro
- VS Code 右下のアイコンから、GitHubアカウントへのログイン状態を確認する．
6. 構成確認 (Configuration Check)
------------------------------------------------------------------------
6-1. 最終ディレクトリ構成
構築完了時点で，以下のディレクトリおよびファイルが存在することを確認する．
SkillSemiWebGame/ <-- プロジェクトルート
├── .devcontainer/ <-- 【重要】Docker設定
│ └── devcontainer.json
├── .git/ <-- git init で作成
├── .gitignore <-- Git除外設定
├── docker-compose.yml <-- Docker構成
├── package.json <-- ルート定義
├── 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設定用
6-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:*"
7. 動作確認 (Verification)
------------------------------------------------------------------------
7-1. ビルド確認
※ 注意: 以下のコマンドは全て「Dev Container内のターミナル」で実行すること．
$ pnpm --filter @repo/shared build
※ shared のビルドが成功することを確認する．
7-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にアクセスしても接続不可となるが，再度起動
コマンドを実行すればいつでも再開可能である．
8. 本番デプロイ手順 (Production Deployment)
------------------------------------------------------------------------
本番環境（サーバー）へのデプロイは，Dockerを使用して最適化されたイメージを作成して行う．
8-1.
構成ファイルの準備
プロジェクトルートに以下のファイルが存在することを確認する．
1. Dockerfile (Multi-stage build構成)
- `pnpm prune` 後の `node_modules` コピー処理が含まれていること．
2. docker-compose.prod.yml (本番起動用)
- ポート設定: "3001:3000" (ホスト側3001番 -> コンテナ側3000番)
8-2.
ローカルでの本番稼働テスト
開発環境(Dev Container)と同時に起動する場合，ポート衝突を避けるために
ホスト側のポートをずらして起動する．
1. ビルドと起動 (WSL/ホスト側のターミナルで実行)
$ docker compose -f docker-compose.prod.yml up -d --build
2. 稼働確認
$ docker compose -f docker-compose.prod.yml ps
・Stateが "Up" であり，"Restarting" を繰り返していないことを確認する．
3. ログ確認
$ docker compose -f docker-compose.prod.yml logs -f
・"Pixel Paint War Server started on port 3000" と表示されれば成功．
4. ブラウザ接続確認
・URL: http://localhost:3001
・表示: "Upgrade Required" と表示されれば，WebSocketサーバーとして正常に稼働している．
8-3.
停止と削除
テストが終了したらリソースを解放する．
$ docker compose -f docker-compose.prod.yml down
