【Laravel × Next.js】Scramble + Orvalで型安全なAPI開発を試してみた
はじめに
Laravel REST APIとTypeScript製フロントエンドを連携する際、こんな悩みがありました。
- APIのレスポンス型を手動で定義するのが面倒
- バックエンドの変更がフロントエンドに伝わらず、ランタイムエラーになる
- API呼び出しのコードが冗長で、毎回似たような実装を書いている
前回の記事でScramble(Laravel用OpenAPI自動生成)を検証したところ、型安全なフロントエンド開発との相性が良さそうだったので、今回はOrval(OpenAPIからTypeScript/React Query生成)と組み合わせて、実際に型安全なAPI開発フローを構築できるか試してみました。
今回検証したこと
Laravel API → Scramble → OpenAPI JSON → Orval → TypeScript型 + React Queryフック → Next.js
バックエンドで型を定義するだけで、フロントエンドの型定義とAPI呼び出しコードが自動生成される開発体験を目指します。
検証環境
- PHP 8.4 / Laravel 12
- Node.js 22 / Next.js 15
- Scramble(最新版)
- Orval 8.2.0
- TanStack Query(React Query)5.x
検証に使用したコードは以下のリポジトリで公開しています。
ScrambleとOrvalについて
Scramble
ScrambleはLaravel専用のOpenAPI(Swagger)ドキュメント自動生成ライブラリです。PHPコードの静的解析により、アノテーション不要でOpenAPIを生成してくれます。FormRequestやAPI Resourceから型を自動推論してくれるのが特徴です。
Orval
OrvalはOpenAPI仕様からTypeScriptコードを自動生成するツールです。React Query / SWR / Vue Query などのフック生成に対応しており、今回はReact Query用のコードを生成してみます。
組み合わせると何が嬉しいか
| 期待するメリット | 内容 |
|---|---|
| 型の一元管理 | LaravelのFormRequest/Resourceで型を定義すれば、フロントエンドの型は自動生成されるはず |
| 変更の自動追従 | APIの変更はOrval再実行で即座にフロントエンドに反映されるはず |
| 開発効率の向上 | React Queryフックが自動生成されるため、API呼び出しコードを書く必要がないはず |
実際にどこまでうまくいくか、検証していきます。
環境構築
ディレクトリ構成
最終的なディレクトリ構成は以下のようになりました。
scramble-orval-demo/
├── docker-compose.yml
├── docker/
│ └── php/
│ └── Dockerfile
├── src/ # Laravel(バックエンド)
└── frontend/ # Next.js(フロントエンド)
Laravel環境構築(Docker Compose)
PHPの依存関係管理が面倒なので、Docker Composeで環境を構築しました。
Dockerfile
docker/php/Dockerfile:
FROM php:8.4-cli
RUN apt-get update && apt-get install -y \
git \
unzip \
libzip-dev \
&& docker-php-ext-install zip pdo pdo_mysql \
&& apt-get clean && rm -rf /var/lib/apt/lists/*
COPY --from=composer:latest /usr/bin/composer /usr/bin/composer
WORKDIR /var/www/html
EXPOSE 8000
CMD ["php", "artisan", "serve", "--host=0.0.0.0", "--port=8000"]
docker-compose.yml
services:
app:
build:
context: ./docker/php
dockerfile: Dockerfile
volumes:
- ./src:/var/www/html
ports:
- "8000:8000"
environment:
- DB_CONNECTION=sqlite
- DB_DATABASE=/var/www/html/database/database.sqlite
検証用なのでDBはSQLiteを使いました。
Laravelプロジェクト作成とScrambleインストール
# プロジェクト作成
docker run --rm -v $(pwd)/src:/app composer create-project laravel/laravel .
# SQLite用の空ファイル作成
touch src/database/database.sqlite
# Scrambleインストール
docker run --rm -v $(pwd)/src:/app -w /app composer require dedoc/scramble
起動してScrambleのドキュメント画面が表示されることを確認しました。
docker compose up -d
docker compose exec app php artisan migrate
http://localhost:8000/docs/api にアクセスすると、Scrambleの画面が表示されました。
Task CRUD APIの作成
検証用のシンプルなTask APIを作成しました。
ファイル生成
docker compose exec app php artisan make:model Task -mcrR
docker compose exec app php artisan install:api
Laravel 11以降では routes/api.php がデフォルトで存在しないため、install:api コマンドが必要でした。これを知らずにしばらくハマりました。
Migration
src/database/migrations/xxxx_create_tasks_table.php:
public function up(): void
{
Schema::create('tasks', function (Blueprint $table) {
$table->id();
$table->string('title');
$table->text('description')->nullable();
$table->enum('status', ['pending', 'in_progress', 'completed'])->default('pending');
$table->date('due_date')->nullable();
$table->timestamps();
});
}
Model
src/app/Models/Task.php:
<?php
namespace App\Models;
use Illuminate\Database\Eloquent\Factories\HasFactory;
use Illuminate\Database\Eloquent\Model;
class Task extends Model
{
use HasFactory;
protected $fillable = [
'title',
'description',
'status',
'due_date',
];
protected $casts = [
'due_date' => 'date',
];
}
FormRequest
src/app/Http/Requests/StoreTaskRequest.php:
<?php
namespace App\Http\Requests;
use Illuminate\Foundation\Http\FormRequest;
class StoreTaskRequest extends FormRequest
{
public function authorize(): bool
{
return true;
}
public function rules(): array
{
return [
'title' => ['required', 'string', 'max:255'],
'description' => ['nullable', 'string'],
'status' => ['nullable', 'in:pending,in_progress,completed'],
'due_date' => ['nullable', 'date'],
];
}
}
src/app/Http/Requests/UpdateTaskRequest.php:
<?php
namespace App\Http\Requests;
use Illuminate\Foundation\Http\FormRequest;
class UpdateTaskRequest extends FormRequest
{
public function authorize(): bool
{
return true;
}
public function rules(): array
{
return [
'title' => ['sometimes', 'required', 'string', 'max:255'],
'description' => ['nullable', 'string'],
'status' => ['nullable', 'in:pending,in_progress,completed'],
'due_date' => ['nullable', 'date'],
];
}
}
API Resource
src/app/Http/Resources/TaskResource.php:
<?php
namespace App\Http\Resources;
use Illuminate\Http\Request;
use Illuminate\Http\Resources\Json\JsonResource;
class TaskResource extends JsonResource
{
public function toArray(Request $request): array
{
return [
'id' => $this->id,
'title' => $this->title,
'description' => $this->description,
'status' => $this->status,
'due_date' => $this->due_date?->format('Y-m-d'),
'created_at' => $this->created_at->toISOString(),
'updated_at' => $this->updated_at->toISOString(),
];
}
}
Controller
src/app/Http/Controllers/TaskController.php:
<?php
namespace App\Http\Controllers;
use App\Http\Requests\StoreTaskRequest;
use App\Http\Requests\UpdateTaskRequest;
use App\Http\Resources\TaskResource;
use App\Models\Task;
use Illuminate\Http\Resources\Json\AnonymousResourceCollection;
class TaskController extends Controller
{
/**
* タスク一覧を取得
*/
public function index(): AnonymousResourceCollection
{
$tasks = Task::orderBy('created_at', 'desc')->get();
return TaskResource::collection($tasks);
}
/**
* タスクを作成
*/
public function store(StoreTaskRequest $request): TaskResource
{
$task = Task::create($request->validated());
return new TaskResource($task);
}
/**
* タスク詳細を取得
*/
public function show(Task $task): TaskResource
{
return new TaskResource($task);
}
/**
* タスクを更新
*/
public function update(UpdateTaskRequest $request, Task $task): TaskResource
{
$task->update($request->validated());
return new TaskResource($task);
}
/**
* タスクを削除
*/
public function destroy(Task $task): \Illuminate\Http\JsonResponse
{
$task->delete();
return response()->json(null, 204);
}
}
ルート定義
src/routes/api.php:
<?php
use App\Http\Controllers\TaskController;
use Illuminate\Support\Facades\Route;
Route::apiResource('tasks', TaskController::class);
マイグレーションを実行して、ルートが登録されていることを確認しました。
docker compose exec app php artisan migrate
docker compose exec app php artisan route:list
# api/tasks のルートが表示されればOK
OpenAPI JSONの確認
http://localhost:8000/docs/api.json にアクセスすると、Scrambleが生成したOpenAPI JSONを確認できました。
{
"openapi": "3.1.0",
"components": {
"schemas": {
"TaskResource": {
"type": "object",
"properties": {
"id": { "type": "integer" },
"title": { "type": "string" },
"description": { "type": ["string", "null"] },
"status": { "type": "string" },
"due_date": { "type": "string" },
"created_at": { "type": "string" },
"updated_at": { "type": "string" }
},
"required": ["id", "title", "description", "status", "due_date", "created_at", "updated_at"]
},
"StoreTaskRequest": {
"type": "object",
"properties": {
"title": { "type": "string", "maxLength": 255 },
"description": { "type": ["string", "null"] },
"status": { "type": ["string", "null"], "enum": ["pending", "in_progress", "completed"] },
"due_date": { "type": ["string", "null"], "format": "date-time" }
},
"required": ["title"]
}
}
}
}
確認できたポイント:
- FormRequestの
rules()からリクエストの型が推論されている - API Resourceの
toArray()からレスポンスの型が推論されている -
statusのバリデーションin:pending,in_progress,completedがenumとして認識されている -
nullableなフィールドはtype: ["string", "null"]として表現されている
アノテーションなしでここまで推論してくれるのは、前回の検証で確認した通りですが、改めて便利だと感じました。
Next.js + Orval環境構築
Next.jsプロジェクト作成
npx create-next-app@latest frontend
最新版ではデフォルト設定(TypeScript, ESLint, Tailwind CSS, App Router)をまとめて選択できるようになっていました。
パッケージインストール
cd frontend
npm install orval --save-dev
npm install @tanstack/react-query
npm install axios
Orval設定ファイル作成
frontend/orval.config.ts:
import { defineConfig } from 'orval';
export default defineConfig({
api: {
input: {
target: 'http://localhost:8000/docs/api.json',
},
output: {
mode: 'tags-split',
target: './lib/api/generated',
schemas: './lib/api/generated/schemas',
client: 'react-query',
httpClient: 'axios',
prettier: true,
override: {
mutator: {
path: './lib/api/axios.ts',
name: 'customInstance',
},
},
},
},
});
設定の意味:
| オプション | 説明 |
|---|---|
input.target |
OpenAPI JSONのURL。Scrambleのエンドポイントを指定 |
mode: 'tags-split' |
OpenAPIのタグごとにファイルを分割 |
client: 'react-query' |
TanStack Query用のフックを生成 |
httpClient: 'axios' |
HTTPクライアントとしてAxiosを使用 |
override.mutator |
カスタムAxiosインスタンスを指定(baseURL設定に必要) |
カスタムAxiosインスタンス作成
frontend/lib/api/axios.ts:
import Axios, { AxiosRequestConfig } from 'axios';
const axios = Axios.create({
baseURL: 'http://localhost:8000/api',
headers: {
'Content-Type': 'application/json',
},
});
export const customInstance = async <T>(
config: AxiosRequestConfig
): Promise<T> => {
const response = await axios(config);
return response.data;
};
最初 export default で定義したところ、生成されたコードで return default<TasksIndex200>(...) のようになってしまい構文エラーになりました。export const customInstance のように名前付きエクスポートにする必要がありました。
コード生成実行
npx orval
🍻 orval v8.2.0 - A swagger client generator for typescript
🎉 api - Your OpenAPI spec has been converted into ready to use orval!
生成成功です。
生成されたコードの確認
ディレクトリ構成
frontend/lib/api/generated/
├── schemas/
│ ├── index.ts
│ ├── taskResource.ts
│ ├── storeTaskRequest.ts
│ ├── storeTaskRequestStatus.ts
│ └── ...
└── task/
└── task.ts
タグごとにディレクトリが分かれ、スキーマは schemas/ にまとめられていました。
型定義(schemas)
frontend/lib/api/generated/schemas/taskResource.ts:
export interface TaskResource {
id: number;
title: string;
/** @nullable */
description: string | null;
status: string;
due_date: string;
created_at: string;
updated_at: string;
}
frontend/lib/api/generated/schemas/storeTaskRequest.ts:
import type { StoreTaskRequestStatus } from './storeTaskRequestStatus';
export interface StoreTaskRequest {
/** @maxLength 255 */
title: string;
/** @nullable */
description?: string | null;
/** @nullable */
status?: StoreTaskRequestStatus;
/** @nullable */
due_date?: string | null;
}
frontend/lib/api/generated/schemas/storeTaskRequestStatus.ts:
export type StoreTaskRequestStatus = typeof StoreTaskRequestStatus[keyof typeof StoreTaskRequestStatus] | null;
export const StoreTaskRequestStatus = {
pending: 'pending',
in_progress: 'in_progress',
completed: 'completed',
} as const;
確認できたポイント:
-
description: string | null- nullableなフィールドはunion型で表現されている -
title: string- requiredなフィールドはoptionalになっていない -
StoreTaskRequestStatus- enumはas constオブジェクトとして生成されている(TypeScriptのベストプラクティス)
期待通りの型が生成されていました。
React Queryフック
frontend/lib/api/generated/task/task.ts には以下のフックが生成されていました。
| フック | 用途 | 種別 |
|---|---|---|
useTasksIndex |
タスク一覧取得 | useQuery |
useTasksStore |
タスク作成 | useMutation |
useTasksShow |
タスク詳細取得 | useQuery |
useTasksUpdate |
タスク更新 | useMutation |
useTasksDestroy |
タスク削除 | useMutation |
GETは useQuery、POST/PUT/DELETEは useMutation として生成されていて、React Queryのベストプラクティスに沿っています。
実際のAPI呼び出し
生成されたフックを使って、実際にタスクを表示・作成してみました。
React Query Provider設定
frontend/app/providers.tsx:
'use client';
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
import { useState } from 'react';
export default function Providers({ children }: { children: React.ReactNode }) {
const [queryClient] = useState(() => new QueryClient());
return (
<QueryClientProvider client={queryClient}>
{children}
</QueryClientProvider>
);
}
frontend/app/layout.tsx にProviderを追加:
import Providers from "./providers";
export default function RootLayout({
children,
}: Readonly<{
children: React.ReactNode;
}>) {
return (
<html lang="en">
<body>
<Providers>{children}</Providers>
</body>
</html>
);
}
タスク一覧ページ
frontend/app/page.tsx:
'use client';
import { useTasksIndex, useTasksStore } from '@/lib/api/generated/task/task';
import { useState } from 'react';
export default function Home() {
const [title, setTitle] = useState('');
// タスク一覧取得
const { data: tasks, isLoading, error, refetch } = useTasksIndex();
// タスク作成
const createTask = useTasksStore({
mutation: {
onSuccess: () => {
setTitle('');
refetch();
},
},
});
const handleSubmit = (e: React.FormEvent) => {
e.preventDefault();
if (!title.trim()) return;
createTask.mutate({ data: { title } });
};
if (isLoading) return <div className="p-8">Loading...</div>;
if (error) return <div className="p-8 text-red-500">Error: {String(error)}</div>;
return (
<main className="p-8 max-w-2xl mx-auto">
<h1 className="text-2xl font-bold mb-6">Task List</h1>
<form onSubmit={handleSubmit} className="mb-6 flex gap-2">
<input
type="text"
value={title}
onChange={(e) => setTitle(e.target.value)}
placeholder="New task title"
className="flex-1 border rounded px-3 py-2 bg-white text-black"
/>
<button
type="submit"
disabled={createTask.isPending}
className="bg-blue-500 text-white px-4 py-2 rounded disabled:opacity-50"
>
{createTask.isPending ? 'Adding...' : 'Add Task'}
</button>
</form>
<ul className="space-y-2">
{tasks?.data?.map((task) => (
<li
key={task.id}
className="border rounded p-3 flex justify-between items-center"
>
<span>{task.title}</span>
<span className="text-sm text-gray-500">{task.status}</span>
</li>
))}
{tasks?.data?.length === 0 && (
<li className="text-gray-500">No tasks yet</li>
)}
</ul>
</main>
);
}
確認できたポイント:
-
useTasksIndex()を呼ぶだけでタスク一覧が取得できる -
createTask.mutate({ data: { title } })の引数は型チェックされる -
tasks?.data?.map((task) => ...)のtaskはTaskResource型として認識される
タスクの作成・一覧表示が問題なく動作しました。
型安全の検証
ここからが今回の検証の本題です。バックエンドの型を変更したときに、フロントエンド側でどう検知されるか確認しました。
シナリオ: TaskResourceに新しいフィールドを追加
Laravel側で priority フィールドを追加して、フロントエンドへの影響を見てみます。
Laravel側の変更
Migration:
docker compose exec app php artisan make:migration add_priority_to_tasks_table
public function up(): void
{
Schema::table('tasks', function (Blueprint $table) {
$table->enum('priority', ['low', 'medium', 'high'])->default('medium')->after('status');
});
}
Model、TaskResource、StoreTaskRequestにも priority を追加しました。
Orval再実行
npx orval
型定義の変更を確認
frontend/lib/api/generated/schemas/taskResource.ts:
export interface TaskResource {
id: number;
title: string;
/** @nullable */
description: string | null;
status: string;
priority: string; // ← 自動的に追加された
due_date: string;
created_at: string;
updated_at: string;
}
バックエンドで追加した priority フィールドが、フロントエンドの型定義に反映されていました。
フロントエンドで新しいフィールドを使用
{tasks?.data?.map((task) => (
<li key={task.id}>
<span>{task.title}</span>
<span>{task.priority}</span> {/* IDEの補完で候補に出る */}
</li>
))}
VSCodeの補完で task.priority が候補に出ることを確認しました。
存在しないプロパティへのアクセスは型エラー
試しにタイポしてみました。
<span>{task.priorityyyy}</span>
即座にTypeScriptエラーが表示されました。
Property 'priorityyyy' does not exist on type 'TaskResource'.
これが型安全の威力です。ランタイムエラーになる前に、開発時点(コンパイル時)でエラーを検知できます。
型チェックコマンド
CIで型の整合性をチェックする場合は以下のコマンドが使えます。
npx tsc --noEmit
バックエンドの変更によってフロントエンドの型が壊れた場合、このコマンドで検知できます。
開発フローの自動化
package.json にスクリプト追加
{
"scripts": {
"dev": "next dev",
"build": "next build",
"generate:api": "orval"
}
}
ローカルファイルを使う場合の設定例:
// orval.config.ts
export default defineConfig({
api: {
input: {
target: './openapi.json', // ローカルファイルを指定
},
// ...
},
});
# OpenAPI JSONをローカルに書き出す
curl http://localhost:8000/docs/api.json > openapi.json
CI/CD での活用
GitHub Actionsなどで以下のようなワークフローを組むと、PRマージ前に型の整合性をチェックできます。
- name: Generate API types
run: npm run generate:api
- name: Type check
run: npx tsc --noEmit
検証結果まとめ
確認できたこと
| 項目 | 結果 |
|---|---|
| ScrambleによるOpenAPI自動生成 | ✅ FormRequest、API Resourceから型が正しく推論された |
| OrvalによるTypeScript型生成 | ✅ nullable、enum含め正しい型が生成された |
| React Queryフック生成 | ✅ GET→useQuery、POST/PUT/DELETE→useMutationで生成された |
| バックエンド変更の追従 | ✅ Orval再実行で型定義に反映された |
| 型エラーの検知 | ✅ 存在しないプロパティへのアクセスはコンパイル時にエラー |
メリット
| メリット | 説明 |
|---|---|
| 型の一元管理 | LaravelのFormRequest/Resourceで型を定義するだけ。フロントエンドの型は自動生成される |
| 開発効率の向上 | API呼び出しコード、型定義を手書きする必要がない |
| 型安全の保証 | 存在しないプロパティへのアクセスはコンパイル時にエラー |
| 変更の自動追従 | バックエンドの変更はOrval再実行で即座に反映 |
| IDEサポート | 補完、リファクタリング、ジャンプが効く |
注意点・ハマったポイント
| 注意点 | 内容 |
|---|---|
| Node.js バージョン | Orval 8.x は Node.js 22以上が必要。20系だと実行時エラー |
| Laravel 11以降のAPI ルート |
routes/api.php がデフォルトで存在しない。php artisan install:api が必要 |
| カスタムAxiosの書き方 |
export default だと生成コードが壊れる。名前付きエクスポートが必要 |
| CORSの設定 | 開発環境ではデフォルトで動作。本番環境では適切に設定(後述) |
| OpenAPI生成の精度 | 複雑なレスポンスは正確に推論されない場合がある(後述) |
CORS設定について
Laravel 11以降では、HandleCors ミドルウェアがデフォルトで有効になっており、デフォルト設定で allowed_origins => ['*'](全オリジン許可) になっています。そのため、開発環境では追加設定なしでフロントエンド(localhost:3000)からバックエンド(localhost:8000)へのリクエストが動作します。
本番環境でオリジンを制限したい場合は、以下のコマンドで設定ファイルを公開してカスタマイズできます:
php artisan config:publish cors
config/cors.php が作成されるので、allowed_origins を適切に設定してください:
'allowed_origins' => ['https://your-frontend-domain.com'],
Scrambleの推論がうまくいかない場合
Scrambleは非常に強力ですが、複雑なクロージャや動的な条件分岐がある場合、型推論が any や unknown になることがあります。その場合は、インラインPHPDocで明示的に型を指定することで補完できます。
/**
* @mixin Post // クラスレベルでモデルを指定
*/
class PostDetailResource extends JsonResource
{
public function toArray(Request $request): array
{
return [
/** @var int 投稿ID */
'id' => $this->id,
/** @var string 記事タイトル */
'title' => $this->title,
/**
* @var array<int, array{id: int, name: string}> タグ一覧
*/
'tags' => $this->tags->map(fn ($tag) => [
'id' => $tag->id,
'name' => $tag->name,
]),
/** @var int|null コメント数 */
'comments_count' => $this->when($this->comments_count !== null, $this->comments_count),
];
}
}
この開発フローが向いているケース
- Laravel + TypeScript製フロントエンドの組み合わせ
- APIの型定義を手動管理したくない
- チーム開発で型の整合性を保証したい
- React Query(TanStack Query)を使用している
おわりに
Scramble + Orvalの組み合わせで、期待通りの型安全なAPI開発フローを構築できました。
バックエンドで型を定義すれば、フロントエンドの型定義とAPI呼び出しコードが自動生成される。この開発体験は一度味わうと手放せなくなりそうです。
特にチーム開発では、APIの変更がフロントエンドの型エラーとして検知できるのは大きなメリットだと感じました。
Discussion