========================================================================
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" ]
