======================================================================== Pixel Paint War - 管理者用環境構築手順 (Admin Setup Guide) ======================================================================== 1. はじめに (Introduction) ------------------------------------------------------------------------ 本ドキュメントは，プロジェクトを「ゼロから新規作成・再構築する管理者」向けの Monorepo構成およびDocker環境の構築ログである． ※ 一般の開発メンバー（Git Cloneして参加する人）は本ドキュメントを実施不要である． 2. 管理者用事前準備 (Prerequisites for Admin) ------------------------------------------------------------------------ 2-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 3. 新規プロジェクト構築 (Project Initialization) ------------------------------------------------------------------------ 3-1. プロジェクト初期化 1. ディレクトリ作成 $ mkdir SkillSemiWebGame $ cd SkillSemiWebGame 2. Git/pnpm 初期化 $ git init $ pnpm init 3-2. Monorepo構成設定 1. pnpm-workspace.yaml 作成 ルート直下に作成し、以下を記述する． packages: - 'apps/*' - 'packages/*' 2. .npmrc 作成 ルート直下に作成し、以下を記述する． shamefully-hoist=true 3-3. ディレクトリ構造の構築 以下の構成になるようにディレクトリを作成する． root/ ├── apps/ │ ├── client/ # フロントエンド (Browser) │ └── server/ # バックエンド (Node.js) └── packages/ └── shared/ # 共通ロジック (Shared Library) ・作成コマンド例: $ mkdir -p apps/client apps/server packages/shared 3-4. Git除外設定 (.gitignore) ルート直下に `.gitignore` を作成し、以下を記述する． node_modules/ .pnpm-store/ dist/ build/ .env .DS_Store .vscode/* !.vscode/extensions.json !.vscode/launch.json coverage/ !packages/ 4. アプリケーション雛形の作成 (Scaffolding) ------------------------------------------------------------------------ 4-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. エントリーポイントの作成 $ mkdir src $ touch src/index.ts ※ (例: 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"] } 4-2. フロントエンド (apps/client) 1. プロジェクト作成 $ cd ../../apps/client $ pnpm create vite . --template preact-ts ※ Use rolldown-vite? » No ※ Install with pnpm and start now? » No 2. 依存ライブラリのインストール $ pnpm add pixi.js $ pnpm add @repo/shared --workspace 4-3. バックエンド (apps/server) 1. 初期化 $ cd ../../apps/server $ pnpm init 2. 依存ライブラリのインストール $ pnpm add ws $ pnpm add -D tsx typescript @types/node @types/ws $ pnpm add @repo/shared --workspace 3. サーバー用ディレクトリとファイルの作成 $ mkdir src $ touch src/index.ts 4. 実行スクリプトの定義 (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-4. 初回コミット (Initial Commit) 1. ルートに戻る $ cd ../.. 2. ステータスの確認 (node_modulesが含まれていないこと) $ git status 3. Gitへ保存 $ git add . $ git commit -m "chore: Initialize project structure and dependencies" 5. Docker環境定義ファイルの作成 (Configuration) ------------------------------------------------------------------------ 5-1. Dockerfile の作成 プロジェクトルートに `Dockerfile` を作成する． ※ Node.js v20 をベースとし，pnpm を有効化した開発用イメージ定義． FROM node:20-slim # pnpmの準備 ENV PNPM_HOME="/pnpm" ENV PATH="$PNPM_HOME:$PATH" RUN corepack enable # 作業ディレクトリ設定 WORKDIR /workspace # 依存関係のコピーとインストール (キャッシュ活用) COPY . . RUN pnpm install # ポート公開 (Vite:5173, Server:3000) EXPOSE 5173 3000 # デフォルトコマンド (docker-composeで上書きするため待機) CMD ["sleep", "infinity"] 5-2. docker-compose.yml の作成 (開発用) プロジェクトルートに `docker-compose.yml` を作成する． ※ ローカルのソースコードをコンテナにマウントする設定． version: "3.8" services: app: container_name: pixel-paint-war-dev # 開発用イメージ: Node.js v20 (定義書準拠) image: mcr.microsoft.com/devcontainers/typescript-node:20 # 永続化とボリュームマウント volumes: # カレントディレクトリをコンテナ内の /workspace にマウント - .:/workspace:cached # 【重要】node_modules をホスト側と切り離して高速化・安定化させる設定 - node_modules:/workspace/node_modules # コマンドの上書き (コンテナを常時起動させる) command: sleep infinity # ネットワーク設定 # Client(5173) と Server(3000) のポートを開放 ports: - "5173:5173" - "3000:3000" # 環境変数 environment: - NODE_ENV=development # ユーザー権限 (Nodeイメージ推奨のユーザー) user: node volumes: node_modules: 5-3. .devcontainer 設定の作成 1. ディレクトリ作成 $ mkdir .devcontainer 2. .devcontainer/devcontainer.json 作成 VS Codeがコンテナを認識するための設定． { "name": "Pixel Paint War Dev", "dockerComposeFile": "../docker-compose.yml", "service": "app", "workspaceFolder": "/workspace", "features": { "ghcr.io/devcontainers/features/node:1": { "version": "20", "pnpm": "latest" } }, "customizations": { "vscode": { "extensions": [ "dbaeumer.vscode-eslint", "esbenp.prettier-vscode", "editorconfig.editorconfig", "ms-vscode.hexeditor", "github.copilot", "github.copilot-chat" ], "settings": { "editor.formatOnSave": true, "editor.defaultFormatter": "esbenp.prettier-vscode" } } }, // コンテナ起動後の初期化コマンド // 1. sudo chown ... : node_modules の所有権を node ユーザーに強制変更 // 2. pnpm install : その後，安全にインストールを実行 // 3. build : 最後に共通パッケージをビルド "postCreateCommand": "sudo chown -R node:node /workspace/node_modules && pnpm install && pnpm --filter @repo/shared build", // コンテナ内のユーザー "remoteUser": "node" } 5-4. docker-compose.prod.yml の作成 (本番確認用) プロジェクトルートに `docker-compose.prod.yml` を作成する． ※ 本番ビルド確認用にポートをずらし、ビルドコマンドを実行する設定． services: app: build: . ports: - "3001:3000" environment: - NODE_ENV=production command: pnpm start 6. 本番デプロイ構成の補足 (Deployment Config) ------------------------------------------------------------------------ 本番環境へデプロイする際は，上記 `Dockerfile` をマルチステージビルドに修正し， 軽量化を図ることが推奨される． 6-1. Dockerfile (本番用最適化例) ※ 必要に応じて `Dockerfile.prod` として作成する． FROM node:20-slim AS base ENV PNPM_HOME="/pnpm" ENV PATH="$PNPM_HOME:$PATH" RUN corepack enable COPY . /app WORKDIR /app FROM base AS prod-deps RUN --mount=type=cache,id=pnpm,target=/pnpm/store pnpm install --prod --frozen-lockfile FROM base AS build RUN --mount=type=cache,id=pnpm,target=/pnpm/store pnpm install --frozen-lockfile RUN pnpm run build FROM base COPY --from=prod-deps /app/node_modules /app/node_modules COPY --from=build /app/apps/server/dist /app/apps/server/dist COPY --from=build /app/apps/client/dist /app/apps/client/dist EXPOSE 3000 CMD [ "pnpm", "start" ]