FastAPIとNext.jsフルスタック連携ガイド

FastAPI と Next.js フルスタック連携ガイド：プロジェクト構成からデプロイまでをステップバイステップで解説

FastAPI と Next.js の連携は、フロントエンドとバックエンドの統合性を高めるための強力なアプローチです。しかし、CORS エラーの対応や複数プロジェクトのデプロイなど、多くのエンジニアが抱える課題があります。本記事では、FastAPI と Next.js フルスタック連携ガイドとして、最新技術スタックを含む実践的な手順をステップバイステップで解説します。

FastAPI と Next.js のプロジェクト構成設計

FastAPI と Next.js を統合する際のプロジェクト構成は、アプリケーションのスケーラビリティや保守性に直結します。モノリシック型とマイクロサービス型の選択を含め、適切なアーキテクチャ設計が不可欠です。

モノリシック型とマイクロサービス型の比較

技術選択の柔軟性と将来的な拡張性を考慮することで、プロジェクトライフサイクルに合った設計が可能になります。

ファイル構造のベストプラクティス

プロジェクトのディレクトリ構成は以下のように設計するのが一般的です：

この構成では、ディレクトリ間の依存関係を明確にし、デプロイや CI/CD での管理が容易になります。

CORS 設定とクロスドメイン通信

FastAPI と Next.js の連携には、ブラウザーセキュリティポリシーによる CORS（Cross-Origin Resource Sharing）制限を回避する必要があります。適切な設定により、開発環境での問題やデプロイ時のエラーを防ぎます。

FastAPI / Next.js における統合的な CORS 対応方法

• FastAPI 側: CORSMiddleware を用いてリクエスト元の制限を柔軟に設定
• Next.js 側: プロキシ設定や環境変数でホスティングサービスと同期

FastAPI での CORSMiddleware の実装手順

1. FastAPI アプリケーションにミドルウェアを追加
   python
from fastapi.middleware.cors import CORSMiddleware

app.add_middleware(
CORSMiddleware,
allow_origins=["http://localhost:3000"], # Next.js の開発サーバーのURL
allow_methods=[""],
allow_headers=[""],
)


1. 環境変数による柔軟な設定
   デプロイ時には allow_origins を Vercel や他のホスティングサービスに合わせて更新します。

Next.js でのプロキシ設定と CORS 避免手順

1. next.config.js でプロキシの設定
   javascript
module.exports = {
async rewrites() {
return [
{
source: '/api/:path*',
destination: 'http://localhost:8000/api/:path*', // FastAPI の URL
},
];
},
};

2. 開発環境での CORS 問題回避
   プロキシ経由で API を呼び出すことで、ブラウザのセキュリティ制限を自動的に回避できます。

TypeScript での API クライアント作成

FastAPI は OpenAPI スペックを自動生成し、そのインターフェースを活用することで型安全なフロントエンド構築が可能です。SWR や Axios を組み合わせた設計が効率的です。

OpenAPI 仕様からの型定義自動生成手順

• Swagger Codegen の使用

• コマンドで TypeScript 型定義ファイルを生成できます：
  bash
npx @openapitools/openapi-generator-cli generate -i http://localhost:8000/openapi.json -g typescript-fetch -o ./services/api-types/

• 型定義の統合
  生成された .ts ファイルを services/ 内に配置し、API クライアントで利用します。

Axios と SWR の統合設計

API クライアントの例：

このようにすることで、データフェッチの効率と再利用性を高められます。

Vercel 上での FastAPI と Next.js の統合デプロイ手順

Next.js は Vercel 上で即座にデプロイ可能ですが、FastAPI バックエンドも一緒に配置するには環境変数や CI/CD のカスタマイズが必要です。

環境変数管理と Secrets 設定

1. Vercel での環境変数設定
2. Vercel ウェブダッシュボードから NEXT_PUBLIC_API_URL や DATABASE_URL を設定します（NEXT_PUBLIC_ で公開可能な値）。
3. FastAPI の Secret 設定ファイル
4. バックエンド側では .env ファイルに環境変数を管理し、Vercel 上でのデプロイ時に自動読み込みされます。

CI/CD パイプラインのカスタマイズ手順

1. vercel.json の設定

2. builds 内に FastAPI 用の構築コマンドを追加：
   json
{
"builds": [
{ "src": "frontend/", "use": "@vercel/next" },
{ "src": "backend/main.py", "use": "@vercel/python" }
]
}

3. Python バージョン指定と依存関係管理

4. pyproject.toml で使用する Python 版を明示し、依存関係の管理を確実にします。

Docker によるローカル環境構築

Docker を利用することで、開発・テスト環境の一貫性を保ちます。以下は基本的な Dockerfile と docker-compose.yml の例です。

多段階ビルドで構成された Dockerfile

Dockerfile は、アプリケーションの依存関係や実行環境を一貫して管理するためのファイルです。

ローカル環境構築用 docker-compose.yml の詳細設定

docker-compose.yml を用いることで、Next.js と FastAPI のコンテナを連携させたローカル環境を構築できます。

プロジェクト初期設定と今後の拡張性

プロジェクト立ち上げ時は、エラーハンドリングやモジュール分割の設計が将来的な保守性に影響します。

エラーハンドリングの共通設計

• FastAPI 側：HTTPException を用いて一貫したエラー応答を実装する
  python
from fastapi import HTTPException

@app.get("/data")
def get_data():
if some_condition:
raise HTTPException(status_code=404, detail="Data not found")


• Next.js 側：SWR の error プロパティでエラーハンドリングを統一
  typescript
const { data, error } = useSWR('/api/data', fetcher);
if (error) return <div>エラーが発生しました</div>;

モジュール分割のベストプラクティス

• FastAPI の routes/ 内で API をモジュールごとに分ける
• Next.js の components/ と services/ を分離し、再利用性を高める

結論：FastAPI × Next.js フルスタック構築の要点

1. プロジェクト構成：マイクロサービス型がスケーラビリティに適している
2. CORS 対策：FastAPI の CORSMiddleware と Next.js のプロキシ設定を併用する
3. OpenAPI スペック活用：自動生成された TypeScript 型で API クライアントを構築すると効率的
4. Vercel 上のデプロイ：vercel.json をカスタマイズし、FastAPI と Next.js の同時デプロイを実現
5. Docker 利用：ローカル環境の一貫性と開発効率を高める

記事に記載されたサンプルコードを元に、あなたのプロジェクトの初期設定を始めてみましょう。