はじめに
この記事は DevNav Handbook の1本目です。
DevNav Handbook は、Spring Boot × React の開発手順を再実装しながら、実装時に詰まりやすいポイント、エラー対応、復習ポイントを整理していくシリーズです。
今回は、Spring Boot と React(Vite) を使って、最小構成でフロントエンドとバックエンドの疎通確認を行います。
ゴールは、React から Spring Boot の /api/hello を呼び出し、画面に Hello DevNav を表示することです。
最初からDB、JPA、Securityまで入れると、環境構築の段階で原因の切り分けが難しくなります。
そのため、この記事ではまず以下だけを目指します。
React(Vite) → Spring Boot → Hello DevNav
この記事のゴール
この記事では、以下を確認します。
1. Vite + React + TypeScript の起動
2. Spring Boot の起動
3. GET /api/hello の作成
4. React から Spring Boot API を fetch で呼び出す
5. 必要に応じてCORS設定を追加する
完成イメージは以下です。
http://localhost:5173
DevNav Replay
Hello DevNav
今回の検証環境
今回の検証環境は以下です。
Java: 17
Build Tool: Maven
Spring Boot: 4.0.6
Frontend: React + Vite + TypeScript
Backend Package: com.example.devnav
Backend Port: 8080
Frontend Port: 5173
この記事では Spring Boot 4系の構成に合わせて、spring-boot-starter-webmvc を使用しています。
Spring Boot 3系の場合は、spring-boot-starter-web を使うケースが一般的です。
最初に入れる依存関係
最初の疎通確認では、依存関係を増やしすぎない方が安全です。
今回使う依存関係は以下です。
Spring Web / Spring Web MVC
Validation
Spring Boot DevTools
Lombok（任意）
最初の段階では、以下はまだ入れません。
Spring Security
Spring Data JPA
PostgreSQL Driver
理由は、DBや認証をまだ使わない段階でこれらを入れると、/api/hello の確認前に別のエラーで詰まりやすいためです。
要注意：最初から全部入れない
ここはかなり重要です。
要注意ポイント
最初から Security / JPA / PostgreSQL を入れると、
Hello API の確認前に別の問題で詰まりやすい。
特に以下は、初学者でも経験者でも詰まりやすいです。
JPAを入れたらDB接続設定が必要になる
Securityを入れたら /login に飛ばされる
Reactから呼ぶとCORSで止まる
/ を開いてWhitelabel Errorを見て焦る
最初は、DBも認証も入れずに、まず通信だけを確認します。
ディレクトリ構成
今回は以下のような構成にします。
devnav-replay-2026
├── backend
│ └── devnav
│ ├── pom.xml
│ └── src
├── frontend
│ ├── package.json
│ └── src
└── docs
作業ディレクトリを作成する
cd ~/Desktop
mkdir devnav-replay-2026
cd devnav-replay-2026
mkdir frontend backend docs
git init
React + Vite + TypeScript を作成する
cd ~/Desktop/devnav-replay-2026/frontend
npm create vite@latest . -- --template react-ts
npm install
npm run dev
起動確認URLです。
http://localhost:5173
Viteの初期画面が表示されればOKです。
Spring Bootプロジェクトを作成する
Spring InitializrでSpring Bootプロジェクトを作成します。
設定例です。
Project: Maven
Language: Java
Spring Boot: 4.0.6
Group: com.example
Artifact: devnav
Name: devnav
Package name: com.example.devnav
Java: 17
Dependencies は以下です。
Spring Web / Spring Web MVC
Validation
Spring Boot DevTools
Lombok（任意）
ダウンロードしたzipを解凍して、以下に配置します。
devnav-replay-2026/backend/devnav
最小構成の pom.xml
今回の最小構成では、dependencies は以下のようになります。
<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-validation</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-webmvc</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-devtools</artifactId>
<scope>runtime</scope>
<optional>true</optional>
</dependency>
<dependency>
<groupId>org.projectlombok</groupId>
<artifactId>lombok</artifactId>
<optional>true</optional>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-webmvc-test</artifactId>
<scope>test</scope>
</dependency>
</dependencies>
Spring Boot 3系の場合は、以下を使うケースが一般的です。
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
HelloControllerを作成する
以下の場所にControllerを作成します。
src/main/java/com/example/devnav/controller/HelloController.java
コードは以下です。
package com.example.devnav.controller;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
/**
* Reactとの疎通確認用Controller。
*/
@RestController
@RequestMapping("/api")
public class HelloController {
/**
* DevNav再現プロジェクトの疎通確認メッセージを返す。
*
* @return 確認用メッセージ
*/
@GetMapping("/hello")
public String hello() {
return "Hello DevNav";
}
}
Spring Bootを起動する
IntelliJ IDEAから実行しても、ターミナルから実行してもOKです。
ターミナルから実行する場合は以下です。
cd ~/Desktop/devnav-replay-2026/backend/devnav
./mvnw spring-boot:run
起動できたら、ブラウザで以下を開きます。
http://localhost:8080/api/hello
以下が表示されれば、バックエンド単体の疎通確認は成功です。
Hello DevNav
要注意：/ を開いてWhitelabel Errorが出る場合
以下を開くと、Whitelabel Errorが表示されることがあります。
http://localhost:8080/
これは今回、/ 用のControllerやHTMLを作っていないためです。
今回作成したAPIは以下です。
GET /api/hello
そのため、確認するURLは以下です。
http://localhost:8080/api/hello
/api/hello で Hello DevNav が表示されていれば問題ありません。
ReactからSpring Boot APIを呼び出す
次に、React側からSpring BootのAPIを呼び出します。
frontend/src/App.tsx を以下のように変更します。
import { useEffect, useState } from "react";
/**
* DevNav Replayのトップ画面コンポーネント。
*/
function App() {
const [message, setMessage] = useState<string>("読み込み中...");
/**
* Spring BootのHello APIからメッセージを取得する。
*/
useEffect(() => {
const fetchHello = async () => {
try {
const response = await fetch("http://localhost:8080/api/hello");
if (!response.ok) {
throw new Error("API通信に失敗しました");
}
const text = await response.text();
setMessage(text);
} catch (error) {
console.error(error);
setMessage("API接続エラー");
}
};
fetchHello();
}, []);
return (
<main style={{ padding: "40px", fontFamily: "sans-serif" }}>
<h1>DevNav Replay</h1>
<p>{message}</p>
</main>
);
}
export default App;
フロントエンドを起動します。
cd ~/Desktop/devnav-replay-2026/frontend
npm run dev
以下を開きます。
http://localhost:5173
画面に以下が表示されれば成功です。
Hello DevNav
要復習：CORS設定
ここは要復習ポイントです。
要復習・要注意ポイント
Reactは localhost:5173
Spring Bootは localhost:8080
ポートが違うため、ブラウザ上では別オリジンとして扱われる。
そのため、ReactからSpring Boot APIを呼ぶとCORSで止まる場合がある。
ReactからAPIを呼べない場合は、Spring Boot側にCORS設定を追加します。
以下の場所に作成します。
src/main/java/com/example/devnav/config/WebConfig.java
コードは以下です。
package com.example.devnav.config;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.CorsRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
/**
* React開発サーバーからSpring Boot APIへアクセスするためのCORS設定。
*/
@Configuration
public class WebConfig implements WebMvcConfigurer {
/**
* Viteの開発サーバーから /api 配下へのアクセスを許可する。
*
* @param registry CORS設定を登録するためのオブジェクト
*/
@Override
public void addCorsMappings(CorsRegistry registry) {
registry.addMapping("/api/**")
.allowedOrigins("http://localhost:5173")
.allowedMethods("GET", "POST", "PUT", "DELETE", "PATCH", "OPTIONS")
.allowedHeaders("*");
}
}
追加後、Spring Bootを再起動します。
CORS設定の読み方
今回のCORS設定は、ざっくり以下の意味です。
registry.addMapping("/api/**")
/api/ 配下のAPIに対してCORS設定を適用します。
.allowedOrigins("http://localhost:5173")
Reactの開発サーバーである localhost:5173 からのアクセスを許可します。
.allowedMethods("GET", "POST", "PUT", "DELETE", "PATCH", "OPTIONS")
許可するHTTPメソッドを指定します。
.allowedHeaders("*")
リクエストヘッダーを許可します。
今回の最小構成では、Reactから GET /api/hello を呼び出すために使っています。
よくあるエラーと解決策
JPAを入れるとDataSourceエラーになる
Spring Data JPAを追加した状態でDB接続設定を書いていないと、起動時に以下のようなエラーが出ます。
Failed to configure a DataSource: 'url' attribute is not specified
Failed to determine a suitable driver class
これは、JPAを追加したことでSpring BootがDB接続を必要と判断するためです。
最初の疎通確認では、JPAは入れない方が安全です。
DBを使う段階になってから、以下を追加します。
Spring Data JPA
PostgreSQL Driver
Securityを入れると /login に飛ばされる
Spring Securityを追加すると、デフォルト設定によりログイン画面へリダイレクトされます。
症状です。
http://localhost:8080/login
ログには以下のような表示が出ます。
Using generated security password: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
最初の /api/hello の疎通確認では、Securityはまだ入れない方がシンプルです。
認証・認可を実装する段階で追加します。
Port 8080 was already in use
すでに別のアプリが8080番ポートを使っている場合、以下のようなエラーになります。
Web server failed to start. Port 8080 was already in use.
Macの場合は、以下で8080番ポートを使っているプロセスを停止できます。
lsof -ti :8080 | xargs kill -9
その後、Spring Bootを再起動します。
React側が「読み込み中...」のまま止まる
React側が「読み込み中...」のまま変わらない場合は、以下を確認します。
1. Spring Bootが起動しているか
2. http://localhost:8080/api/hello を直接開いて Hello DevNav が出るか
3. React側のfetch先URLが正しいか
4. CORS設定を入れているか
まずは、ブラウザで以下を直接確認します。
http://localhost:8080/api/hello
次に、React側のfetch先を確認します。
fetch("http://localhost:8080/api/hello")
それでも表示されない場合は、CORS設定を確認します。
3分で確認するチェックリスト
次回からは、以下の順番で確認します。
1. Spring Initializrでは最初にJPA / Security / PostgreSQLを入れない
2. Spring Bootで /api/hello を作る
3. http://localhost:8080/api/hello を直接開く
4. Vite + React + TypeScript を作る
5. Reactから http://localhost:8080/api/hello をfetchする
6. 表示されない場合はCORS設定を追加する
7. http://localhost:5173 に Hello DevNav が表示されれば完了
今回の復習ポイント
今回、特に復習すべきポイントは以下です。
要復習
CORS設定
Spring Securityを入れたときの /login リダイレクト
Spring Data JPAを入れたときのDataSourceエラー
8080ポート競合
/api/hello と / の違い
Reactのfetch処理
特にCORS設定は、ReactとSpring Bootを別ポートで動かす構成では何度も出てきます。
ここは、流れだけでなく「なぜ必要か」まで復習しておくと、次回以降のエラー対応がかなり楽になります。
まとめ
Spring Boot × React(Vite) の最小環境構築では、最初からDBや認証を入れすぎない方が原因を切り分けやすいです。
まずは以下だけを確認します。
React → Spring Boot → Hello DevNav
ここまで確認できてから、PostgreSQL、JPA、Securityを順番に追加していくと、どこで問題が起きたのか判断しやすくなります。
DevNav Handbookでは、今後もこのように、実装手順・詰まりポイント・復習ポイントをセットで整理していきます。