【ASP.NET Core Web API + React + TypeScript(vite)】書籍管理システム設計 ① 環境構築手順書

Last updated at 2026-07-28Posted at 2026-07-28

本記事は 書籍管理システム設計（全4回）シリーズの ① です。

📚 シリーズ全記事（全4回）

【ASP.NET Core Web API + React + TypeScript(vite)】書籍管理システム設計 ① 環境構築手順書（この記事）
【ASP.NET Core Web API + React + TypeScript(vite)】書籍管理システム設計 ② 要件定義書
【ASP.NET Core Web API + React + TypeScript(vite)】書籍管理システム設計 ③ 基本設計書（外部設計）
【ASP.NET Core Web API + React + TypeScript(vite)】書籍管理システム設計 ④ 詳細設計書（内部設計）

項目	内容
文書名	環境構築手順書
システム名	書籍管理システム（Book Manager）
版数	1.0
作成日	2026-07-24
関連文書	01_要件定義書.md / 02_基本設計書.md / 03_詳細設計書.md

改訂履歴

版	日付	改訂内容	作成者
1.0	2026-07-24	初版作成（検証済み環境・手順に基づく）	—

1. はじめに

1.1 目的

本書は、書籍管理システムの開発／動作環境を構築し、アプリケーションを起動・動作確認するまでの手順を示す。

1.2 対象読者

本システムを新しい端末でセットアップする担当者
開発・保守担当者

1.3 構成概要

[ブラウザ] → Vite Dev Server(:5173) →(/api プロキシ)→ ASP.NET Core API(:5000) → SQLite(books.db)

2. 前提環境

2.1 動作確認済み環境

項目	バージョン
OS	Linux（WSL2, kernel 6.6.x-microsoft-standard-WSL2）
.NET SDK	10.0.302
EF Core Tools（dotnet-ef）	10.0.10
Node.js	v24.16.0
npm	11.13.0
React / React-DOM	19.2.8
TypeScript	6.0.3
Vite	8.1.5
@vitejs/plugin-react	6.0.4

2.2 必要ソフトウェア一覧

ソフトウェア	用途	必須
.NET SDK 10	バックエンドのビルド・実行	○
dotnet-ef（グローバルツール）	マイグレーション・DB更新	○
Node.js 20 以上（推奨 v24 系）	フロントエンドのビルド・実行	○
npm	パッケージ管理	○
Git	ソース取得（任意）	△
モダンブラウザ	動作確認	○

本システムは開発用に HTTP + Vite プロキシ構成のため、HTTPS 開発証明書（dotnet dev-certs）の信頼設定は不要である。

3. 事前準備（プレインストール）

すでに「2.1 動作確認済み環境」を満たしている場合、本章はスキップして「4章」へ進む。
インストール方法は OS により異なるため、以下は代表例。

3.1 .NET SDK 10 のインストール

公式配布（https://dotnet.microsoft.com/download）または各 OS のパッケージ／インストールスクリプトで導入する。
確認：

dotnet --version        # 例: 10.0.302
dotnet --list-sdks

3.2 EF Core ツール（dotnet-ef）のインストール

dotnet tool install --global dotnet-ef
# 既にある場合は更新: dotnet tool update --global dotnet-ef

グローバルツールのパス ~/.dotnet/tools が PATH に含まれていることを確認する。
確認：

dotnet ef --version     # 例: 10.0.10

3.3 Node.js / npm のインストール

nvm や各 OS のパッケージ等で Node.js（20 以上、推奨 v24 系）を導入する。
確認：

node --version          # 例: v24.16.0
npm --version           # 例: 11.13.0

4. ソース配置

本システムは以下のディレクトリ構成を前提とする。

webapi/
├─ api/     バックエンド（ASP.NET Core Web API）
├─ web/     フロントエンド（React + TypeScript / Vite）
└─ docs/    ドキュメント

Git 管理下の場合は clone、配布物の場合は所定の場所へ展開する。
以降の手順は webapi/ をカレントとして記載する。

5. バックエンド構築手順（api/）

5.1 依存パッケージの復元

cd api
dotnet restore

使用パッケージ：Microsoft.EntityFrameworkCore.Sqlite / Microsoft.EntityFrameworkCore.Design / Scalar.AspNetCore
復元時に NU1903（推移的依存の脆弱性告知）警告が出るが、動作には影響しない（→ 8.6 参照）。

5.2 データベースの作成・初期化

dotnet ef database update

マイグレーション Init（テーブル作成）→ SeedBooks（初期データ5件投入）が適用され、api/books.db が生成される。
成功時、末尾に Done. と表示される。

5.3 ビルド確認（任意）

dotnet build
# => Build succeeded.（NU1903 の警告は許容）

5.4 API 起動

dotnet run --launch-profile http

起動 URL：http://localhost:5000
API 確認 UI（Scalar）：http://localhost:5000/scalar
OpenAPI 定義：http://localhost:5000/openapi/v1.json
停止：Ctrl + C

6. フロントエンド構築手順（web/）

6.1 依存パッケージのインストール

cd web
npm install

6.2 開発サーバ起動

npm run dev

起動 URL：http://localhost:5173
/api/* へのリクエストは Vite プロキシにより API（:5000）へ転送される（vite.config.ts）。
停止：Ctrl + C

6.3 本番ビルド（任意）

npm run build     # 型チェック(tsc) + ビルド。成果物は web/dist/

7. 動作確認

7.1 API 単体（curl）

API を起動した状態で、別ターミナルから実行：

# 一覧取得（初期データ5件が返る）
curl http://localhost:5000/api/books

# 登録
curl -X POST http://localhost:5000/api/books \
  -H 'Content-Type: application/json' \
  -d '{"title":"新書","author":"著者A","year":2026,"isBorrowed":false}'

# 更新（id=1 を貸出中に）
curl -X PUT http://localhost:5000/api/books/1 \
  -H 'Content-Type: application/json' \
  -d '{"id":1,"title":"吾輩は猫である","author":"夏目漱石","year":1905,"isBorrowed":true}'

# 削除
curl -X DELETE http://localhost:5000/api/books/1

7.2 画面（ブラウザ）

API（:5000）とフロント（:5173）を両方起動する。
ブラウザで http://localhost:5173 を開く。
初期データ5件が一覧表示されることを確認する。
追加・編集・削除・状態バッジ（貸出／返却）切替が動作することを確認する。

7.3 動作確認チェックリスト

No	確認項目	期待結果
1	`dotnet ef database update`	`books.db` 生成、`Done.` 表示
2	API 起動後 `GET /api/books`	初期データ5件が JSON で返る
3	`http://localhost:5000/scalar`	API リファレンス画面が表示される
4	フロント `http://localhost:5173`	一覧に5件表示
5	画面から追加	一覧に追加行が表示される
6	画面から編集→保存	変更内容が反映される
7	状態バッジ押下	貸出中／在庫ありが切り替わる
8	画面から削除	対象行が消える

8. トラブルシューティング

8.1 フロントで「書籍の取得に失敗しました」と表示される

API（:5000）が起動しているか確認する。
web/vite.config.ts のプロキシ先が http://localhost:5000 になっているか確認する。
API のポートを変えた場合は、プロキシ先も合わせる。

8.2 ポートが使用中（Address already in use）

別プロセスが 5000／5173 を使用している。使用中プロセスを停止するか、ポートを変更する。

# ポート使用状況の確認例
ss -ltnp | grep -E ':5000|:5173'

API のポート変更：dotnet run --launch-profile http --urls http://localhost:5001（併せてプロキシ先も変更）。

8.3 `dotnet ef` が見つからない

グローバルツール未インストール、または PATH 未設定。

dotnet tool install --global dotnet-ef
export PATH="$PATH:$HOME/.dotnet/tools"   # 必要に応じ .bashrc 等へ追記

8.4 データベースを初期状態に戻したい

cd api
# 方法A: DBを削除して再作成（シード再投入）
rm -f books.db && dotnet ef database update

# 方法B: EF コマンドで削除
dotnet ef database drop -f && dotnet ef database update

8.5 マイグレーションが適用されていない／テーブルが無い

cd api && dotnet ef database update

8.6 ビルド時の `NU1903` 警告

推移的依存（Microsoft.OpenApi、SQLitePCLRaw.lib.e_sqlite3）の脆弱性告知であり、ビルド・動作に影響はない。
解消したい場合は該当パッケージを新しい版へ更新する（dotnet add package ...）。

8.7 日本語が文字化けする

端末・エディタの文字コードを UTF-8 に設定する。DB・API・フロントは UTF-8 前提。

8.8 CORS エラーが出る

本構成では Vite プロキシ経由（同一オリジン）のため通常発生しない。
フロントが API を絶対 URL で直接叩いていないか（web/src/api.ts の BASE が相対パス /api/books か）を確認する。

9. 停止・クリーンアップ

対象	操作
API 停止	実行ターミナルで `Ctrl + C`
フロント停止	実行ターミナルで `Ctrl + C`
DB 削除	`rm -f api/books.db`（再作成は 8.4）
フロント成果物削除	`rm -rf web/dist`
ビルド中間物削除	`rm -rf api/bin api/obj`（次回ビルドで再生成）

10. 起動クイックリファレンス

# ── 初回のみ ─────────────────────────
cd api && dotnet restore && dotnet ef database update
cd ../web && npm install

# ── 毎回の起動（ターミナル2枚）─────────
# ターミナル1
cd api && dotnet run --launch-profile http     # http://localhost:5000 (UI: /scalar)
# ターミナル2
cd web && npm run dev                           # http://localhost:5173

You get articles that match your needs
You can efficiently read back useful information
You can use dark theme

What you can do with signing up

【ASP.NET Core Web API + React + TypeScript(vite)】書籍管理システム設計 ① 環境構築手順書

📚 シリーズ全記事（全4回）

改訂履歴

1. はじめに

1.1 目的

1.2 対象読者

1.3 構成概要

2. 前提環境

2.1 動作確認済み環境

2.2 必要ソフトウェア一覧

3. 事前準備（プレインストール）

3.1 .NET SDK 10 のインストール

3.2 EF Core ツール（dotnet-ef）のインストール

3.3 Node.js / npm のインストール

4. ソース配置

5. バックエンド構築手順（api/）

5.1 依存パッケージの復元

5.2 データベースの作成・初期化

5.3 ビルド確認（任意）

5.4 API 起動

6. フロントエンド構築手順（web/）

6.1 依存パッケージのインストール

6.2 開発サーバ起動

6.3 本番ビルド（任意）

7. 動作確認

7.1 API 単体（curl）

7.2 画面（ブラウザ）

7.3 動作確認チェックリスト

8. トラブルシューティング

8.1 フロントで「書籍の取得に失敗しました」と表示される

8.2 ポートが使用中（Address already in use）

8.3 dotnet ef が見つからない

8.4 データベースを初期状態に戻したい

8.5 マイグレーションが適用されていない／テーブルが無い

8.6 ビルド時の NU1903 警告

8.7 日本語が文字化けする

8.8 CORS エラーが出る

9. 停止・クリーンアップ

10. 起動クイックリファレンス

8.3 `dotnet ef` が見つからない

8.6 ビルド時の `NU1903` 警告