Contents
Next.js と Mastra の統合方法｜開発効率を高める具体的な手順とベストプラクティス
Next.jsアプリケーションにMastraを導入することで、API管理やデータフェッチングの手間を軽減し、開発効率を向上させることができます。本記事では、Next.js 14以降のバージョンを対象に、認証フローの統合やSSG/SSRでの同期処理など、実務で必要な技術スタックの組み合わせ方を解説します。
Next.jsプロジェクトへのMastra導入の準備
Next.jsとMastraを組み合わせる際には、技術スタックの確認が不可欠です。特にNext.js 14以降ではApp Routerが採用される標準構造であり、Server ComponentsはApp Router内での利用が前提となっています。また、TypeScriptの利用は開発効率向上のために強く推奨されます。
必要な技術スタックと対応確認
以下に導入に必要な技術スタックとその補足情報を整理しました。
| 項目 | 値 | 補足 |
|---|---|---|
| Next.jsバージョン | 14以降（App Router採用） | Server ComponentsはApp Router内でのみ有効 |
| Node.jsバージョン | v16以上推奨、v18+で最適 | ライブラリの互換性を保つためにv16も動作可能 |
| TypeScript利用 | 推奨 | 型定義ファイルの導入で開発効率が向上 |
注意: Mastraの公式ドキュメントでは、API管理に特化した設定が紹介されています。導入前には公式リファレンスを確認してください。
Mastraライブラリの導入手順
MastraをNext.jsプロジェクトに統合するには、パッケージのインストールとグローバル設定ファイルを作成します。ここではnpmやyarnを使ったインストール手順と、next.config.jsへの記述変更ポイントを解説します。
パッケージインストールと導入手順
Next.jsプロジェクトにMastraを統合するには、以下のコマンドでパッケージをインストールしてください。
-
npmの場合
bash
npm install @mastra/core -
yarnの場合
bash
yarn add @mastra/core
補足: 最新版のライブラリを使用する際は、
@latestを指定するなどしてバージョン管理を行うとよいです。
グローバル設定ファイルの作成
Mastraを全プロジェクトで利用可能にするには、グローバルな設定ファイルを作成します。next.config.jsに以下のように記述してください。
|
1 2 3 4 5 6 7 8 |
const nextConfig = { // ...他の設定 experimental: { appDir: true, serverComponentsExternalPackages: ['@mastra/core'], }, }; |
ポイント:
serverComponentsExternalPackagesにMastraを指定することで、Server Componentsでの利用が可能になります。
APIルートとの認証フロー統合
Next.jsアプリケーションでAPIルートを使用する際には、認証フローの統合が不可欠です。JWTやOAuth2.0に対応したMiddlewareやAPI Routeでのトークン検証を実装します。
Middlewareによる認証チェックの実装
Next.jsのMiddleware機能で、APIルートにアクセスする際の認証を統合できます。以下はJWT認証の一例です。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 |
// middleware.ts import { NextResponse } from 'next/server'; import jwt from 'jsonwebtoken'; export async function middleware(request) { const token = request.cookies.get('auth_token')?.value; if (!token) { return new NextResponse('Unauthorized', { status: 401 }); } try { await jwt.verify(token, process.env.JWT_SECRET); } catch (err) { return new NextResponse('Invalid token', { status: 403 }); } } |
Mastra APIと連携した認証フローの実装例
Mastra APIとの認証フローでは、以下のようにAPI Keyを用いたリクエストヘッダを追加します。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
// api/auth/[...].ts export async function POST(req: Request) { const { email, password } = await req.json(); const response = await fetch('https://api.mastra.io/v1/auth/login', { method: 'POST', headers: { 'Content-Type': 'application/json', 'Authorization': `Bearer ${process.env.MASTRA_API_KEY}`, }, body: JSON.stringify({ email, password }), }); const data = await response.json(); return NextResponse.json(data); } |
SSG/SSR環境でのマスターデータ同期
Next.jsでSSG（Static Site Generation）やSSR（Server-Side Rendering）を使用する際、Mastra APIからマスターデータを取得する方法が重要です。ISR（Incremental Static Regeneration）の活用も検討してください。
getStaticPropsでのデータ取得フロー
getStaticPropsでデータをフェッチし、Mastra APIと連携させます。以下は基本的な処理フローです。
- Mastra APIからマスターデータをフェッチ
- データが最新か確認（バージョン番号やタイムスタンプを使用）
- 必要に応じてISRで静的ページの再生成
|
1 2 3 4 5 6 7 8 |
export async function getStaticProps() { const data = await fetchMastraData(); // Mastra APIを呼び出す関数 return { props: { data }, revalidate: 60, // ISRによるキャッシュ有効期限（秒） }; } |
ISRの活用とMastra API連携例
ISRにより、特定のURLにアクセスされた際に静的ページを再生成します。以下はMastra APIとの同期方法です。
|
1 2 3 4 5 6 7 8 9 |
// app/page.tsx export async function generateStaticParams() { const res = await fetch('https://api.mastra.io/v1/master-data'); const data = await res.json(); return data.map((item) => ({ id: item.id, })); } |
ポイント:
generateStaticParamsでMastra APIから動的にパラメータを取得し、ISRの実行タイミングを制御します。
エラーハンドリングとキャッシュ戦略
Next.jsアプリケーションでは、エラーハンドリングとキャッシュ戦略の適切な設計が重要です。401/5xx系エラーの処理やSWR、React Queryとの併用も検討してください。
グローバルエラーコンポーネントの実装
Next.jsでは、not-found.tsxやカスタムエラーコンポーネントを作成することで、一貫したエラーメッセージを提示できます。以下は401エラーの一例です。
|
1 2 3 4 5 6 7 8 9 10 |
// app/error.tsx export default function ErrorPage({ error }) { return ( <div> <h1>エラーが発生しました</h1> <p>{error.message}</p> </div> ); } |
クライアントサイドキャッシュ設定
SWRやReact Queryなど、クライアントサイドのキャッシュライブラリと組み合わせることで、API呼び出しを最適化できます。Mastra APIとの連携例です。
|
1 2 3 4 5 6 7 8 9 10 11 12 |
import useSWR from 'swr'; const fetcher = (url) => fetch(url, { headers: { Authorization: `Bearer ${process.env.MASTRA_API_KEY}` }, }).then((res) => res.json()); export default function DataComponent() { const { data, error } = useSWR('/api/mastra-data', fetcher); return <div>{data?.name}</div>; } |
パフォーマンス最適化のベストプラクティス
Next.js 14以降ではServer Componentsが導入され、Mastraとの連携によってさらに効率的な処理が可能になります。Lazy LoadingやAPIリクエストの並列制御なども検討してください。
Lazy Loadingの適用範囲と実装
不要なコンポーネントはLazy Loadingで読み込みを遅延させることで、初期ロード時間を短縮できます。以下がServer Componentsでの例です。
|
1 2 3 4 5 6 7 8 9 10 11 12 |
const LazyComponent = React.lazy(() => import('../components/LazyComponent')); export default async function Page() { return ( <div> <Suspense fallback={<div>Loading...</div>}> <LazyComponent /> </Suspense> </div> ); } |
APIリクエストの並列処理制御
複数のAPI呼び出しが発生する際には、Promise.all()などで並列化を行い、パフォーマンスを向上させましょう。以下はMastra APIとの連携例です。
|
1 2 3 4 5 |
const [data1, data2] = await Promise.all([ fetch('https://api.mastra.io/v1/data1'), fetch('https://api.mastra.io/v1/data2'), ]); |
まとめ
本記事では、Next.jsアプリケーションにMastraを統合する具体的な手順とベストプラクティスを解説しました。要点を以下にまとめます。
- 導入準備: Next.js 14以降 + TypeScriptの利用が推奨
- 導入手順:
npm installでパッケージインストール、next.config.jsでの設定変更 - 認証フロー: MiddlewareとAPI Routeでのトークン検証を組み合わせる
- データ同期: SSG/SSR環境におけるMastra APIとの連携とISRの活用
- エラーハンドリング: グローバルエラーコンポーネントとキャッシュ戦略の実装
- パフォーマンス最適化: Lazy Loadingや並列処理の適用
公式ドキュメントと本記事を参考に、Next.jsプロジェクトへのMastra導入を検討してください。