BLOG - MY PORTFOLIO DevContainerでのReact開発環境構築 - サメの備忘録
サメの備忘録 :samenobibouroku

さめによる技術ブログ

DevContainerでのReact開発環境構築

DevContainer環境でのReact開発環境構築ガイド

本記事は、Visual Studio CodeのDevContainer機能を使用してReact開発環境を構築する際の手順とトラブルシューティングをまとめたものです。実際の構築過程で発生した問題と解決策を含み、効率的な開発環境セットアップのための実践的なガイドとなっています。

前提条件

開始する前に、以下の環境が整っていることを確認してください：

• Docker Desktop または Docker Engine がローカル環境にインストール済み • Visual Studio Code がインストール済み • VS Code拡張機能「Dev Containers」がインストール済み • WSL2環境（Windows環境の場合）

基本的な手順

1. プロジェクトディレクトリの準備

プロジェクトルートに .devcontainer ディレクトリを作成し、設定ファイルを配置します。

2. devcontainer.json の設定

最初に試行した設定は以下の通りでした：

{
  "name": "React Map App",
  "image": "node:18-bullseye",
  "workspaceFolder": "/workspace",
  "forwardPorts": [3000],
  "mounts": [
    "source=${localWorkspaceFolder},target=/workspace,type=bind,consistency=cached"
  ],
  "customizations": {
    "vscode": {
      "extensions": [
        "ms-vscode.vscode-typescript-next",
        "esbenp.prettier-vscode"
      ]
    }
  },
  "postCreateCommand": "cd /workspace && npm install",
  "remoteUser": "node"
}

3. VS Codeでのコンテナ起動

コマンドパレット（Ctrl+Shift+P）から「Dev Containers: Reopen in Container」を選択してコンテナ環境を起動します。

発生した問題と解決策

問題1: npmコマンドが見つからない

症状： DevContainer内でnpmコマンドを実行すると「bash: npm: command not found」エラーが発生しました。

原因： 使用したNode.jsベースイメージ（node:18-bullseye）では、npmが期待通りにインストールまたは設定されていませんでした。

解決策： コンテナ内でNode.jsを手動インストールしました：

curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt-get install -y nodejs

問題2: sudo権限がない

症状： パッケージのインストールやファイルの権限変更時に「sudo: command not found」エラーが発生しました。

原因： Dockerコンテナでは、セキュリティ上の理由からsudoが標準でインストールされていません。

解決策： Dockerfileを作成してsudoをインストールし、nodeユーザーに権限を付与しました：

FROM node:18-bullseye

# 必要なツールのインストール（sudoを追加）
RUN apt-get update && apt-get install -y \
    git \
    curl \
    sudo \
    && rm -rf /var/lib/apt/lists/*

# nodeユーザーにsudo権限を付与
RUN echo "node ALL=(ALL) NOPASSWD:ALL" >> /etc/sudoers

# 作業ディレクトリ
WORKDIR /workspace

# nodeユーザーに切り替え
USER node

問題3: dpkgロックファイルエラー

症状： sudoのインストール中に「E: Could not open lock file /var/lib/dpkg/lock-frontend」エラーが発生しました。

原因と対処法： dpkgロックファイルエラーは以下の原因で発生します：

• 同時実行: 複数のパッケージ管理操作が同時実行された • プロセス残存: 以前のapt操作が完全に終了していない
• 権限問題: 不適切な権限でパッケージ操作を実行した

一般的には時間を置いて再実行するか、コンテナを再構築することで解決されます。

問題4: Viteでのrolldownエラー

症状： React開発環境としてViteを使用した際に、以下のエラーが発生しました：

Error: Cannot find native binding. npm has a bug related to optional dependencies
Error: Cannot find module '@rolldown/binding-linux-x64-gnu'

原因： ViteのバージョンとNode.js 18の互換性問題、およびDockerコンテナ環境でのバイナリファイルの問題でした。

解決策： ViteからNext.jsに変更することで解決しました：

npx create-next-app@13.5.0 . --typescript --eslint --no-tailwind --app --src-dir

最終的な推奨構成

推奨設定: Next.jsベース

最終的に安定動作した設定は以下の通りです：

{
  "name": "React Map App",
  "image": "mcr.microsoft.com/devcontainers/javascript-node:18-bullseye",
  "workspaceFolder": "/workspace",
  "forwardPorts": [3000],
  "features": {
    "ghcr.io/devcontainers/features/common-utils:2": {
      "username": "vscode",
      "userUid": "automatic",
      "userGid": "automatic"
    }
  },
  "customizations": {
    "vscode": {
      "extensions": [
        "ms-vscode.vscode-typescript-next",
        "esbenp.prettier-vscode"
      ]
    }
  },
  "postCreateCommand": "npm install",
  "remoteUser": "vscode"
}

プロジェクト作成コマンド

# Next.jsプロジェクト作成
npx create-next-app@13.5.0 . --typescript --eslint --no-tailwind --app --src-dir

# 地図アプリ用ライブラリのインストール
npm install leaflet react-leaflet axios uuid
npm install -D @types/leaflet @types/uuid

DevContainerでのコンテナ操作

基本コマンド

複数コンテナ環境で特定のコンテナに接続する場合：

  1. コマンドパレット起動: Ctrl+Shift+P (Windows/Linux) または Cmd+Shift+P (Mac)
  2. 主要コマンド: • Dev Containers: Attach to Running Container... – 既存のコンテナに接続 • Dev Containers: Open Folder in Container... – フォルダを指定してコンテナで開く • Dev Containers: Rebuild and Reopen in Container – コンテナを再構築して接続 • Dev Containers: Reopen in Container – docker-compose環境用

トラブルシューティング時の対応

  1. 設定ファイル確認: devcontainer.jsonの構文エラーや設定ミスを確認
  2. コンテナ再構築: Dev Containers: Rebuild Containerを実行
  3. ログ確認: VS Codeの出力パネルでDevContainerのログを確認
  4. 権限問題: rootユーザーでの実行またはsudo権限の設定

注意点とベストプラクティス

1. イメージ選択

公式のDevContainer用イメージ（mcr.microsoft.com/devcontainers/）を使用することを推奨します。素のDockerイメージよりも設定済みの環境を使用する方が安定しています。

2. 権限管理

本番環境でない開発用途では、適切なsudo権限設定で開発効率を優先します。セキュリティが重要な環境では、最小権限の原則を適用してください。

3. Node.jsバージョン

プロジェクトで使用するライブラリの要件を事前に確認しましょう。最新のツールは新しいNode.jsバージョンを要求する場合があります。

4. 依存関係管理

パッケージインストール時のエラーは、キャッシュクリアと再インストールで解決することが多いです。Docker環境では、バイナリファイルの互換性問題が発生しやすい点に注意が必要です。

まとめ

DevContainer環境でのReact開発環境構築では、Node.js環境の整備と権限設定が主要な課題となります。公式のDevContainerイメージを使用し、適切な権限設定を行うことで、安定した開発環境を構築できます。

トラブルが発生した際は、段階的にアプローチし、エラーメッセージを詳しく分析することが重要です。特にDocker環境特有の権限問題やバイナリ互換性問題については、代替手段を含めた複数の解決策を準備しておくことが効果的です。

本ガイドで紹介した手順と解決策により、効率的なReact開発環境の構築が可能となり、開発生産性の向上が期待できます。