Next.jsでもHonoを使ってOpenAPIの支援を受けられるようにする #honoconf

Hono Conference 2025にて発表しました。

https://honoconf.dev/2025

https://fortee.jp/honoconf-2025/proposal/671010c7-520f-4d71-9be4-8464b1efe393

Transcript

1. Next.jsでもHonoを使っ てOpenAPIの支援を受け られるようにする id:ymse / @azukibar_D 2025/10/18 Hono Conference 2025 1
2. お品書き - 話の前提となるアプリケーション構成 - Next.jsのルーティングとリクエストハンドラ - HonoとNext.jsを統合する - Hono OpenAPI 2
3. 自己紹介 - あずきバー @azukibar_D - 株式会社はてな - Webアプリケーションエンジニア - 普段はTypeScriptを書いています 3
4. 類似テーマのみなさま - 「Next.jsでもHonoを使ってOpenAPIの支援 を受けられるようにする」 - 会場に類似テーマの発表がいくつかある - Aditya Mathur氏 - @hono/mcpの話をされていた - Hono OpenAPIの作者 4
7. 類似テーマの2名 - フロントエンド主体で進めるHono×zod-openapiのスキー マ駆動開発 - スキーマをもとにモックを作成 - スキーマ駆動開発における開発プロセス - スキーマ駆動で、Zod OpenAPI Honoによる、API開発す るために、Hono Takibiというライブラリを作っている - OpenAPIのスキーマからhono/zod-openapiを作るHono Takibiの話 - 話すテーマとは逆のアプローチ 7
8. 8 前提
9. お品書き - 話の前提となるアプリケーション構成 - Next.jsのルーティングとリクエストハンドラ - HonoとNext.jsを統合する - Hono OpenAPI 9
10. toitta - インタビュー動画加工 - 書き起こし - 切片化 - 任意の設問に対し、 インタビューをもとに 回答を生成 10
11. おおまかな構成 11
12. おおまかな構成 12 ここの話をします
13. ユーザーから見えるのは Next.jsアプリのみ - Next.jsアプリがユーザーから見えるUIを提供 - App Router - 表示するデータの取得 - Server Functionsでのデータ更新 - ドメイン固有の処理はNext.jsアプリ内に定義 - DBへ保存するJSONカラムのスキーマ 13
14. すべてをNext.jsアプリで処理しない - Next.jsで実行すると都合が悪い処理もある - 生成AIへのコンテンツ生成リクエスト - 動画の読み込みや変換処理 - CPU/メモリを多く使うので水平スケーリングしやすく - インタビュー動画の書き起こし - GPUを使いたい 14
15. コンテンツ生成部分の特徴 - Pythonで実装されている - DBに繋がっていない - Python-Prismaは2025年4月にアーカイブされている - Next.jsアプリを経由してデータ取得 - Next.jsがデータ取得用のAPIを提供する必要がある 15
16. 実装あるある - 新機能の追加に向けAPIを実装 - APIを使う側と提供する側で分かれて実装 - 結合したら400 Bad Request - 入出力値スキーマの変更追従漏れ - あとから値が不足していることに気がつく 16
17. APIの仕様を書いて共有 - 仕様を合意してから作る - 「/api/ _/interview に ?id=foo を付けてGETをすると データが取れます」 - 「保存するときのBodyはこれでいきます」 - @valibot/json-schema で吐いたJSON Schemaを貼る - 最初のほうはなんとかなる 17
18. 崩壊 - 実装を進めると過不足に気がつく - 取得するリソースを絞りたい - バルクで取得したい - 直す - （ここでドキュメント・実装の追従が漏れる） - 突然壊れる - さっきまで使えていたエンドポイントが400を返す 18
19. 崩壊を防ぐには - 崩壊を防ぐための知見はすでにある - OpenAPIやgRPCなどの仕組みが一例 - 今回はOpenAPIの力を借りる話をします 19
20. 20 Next.jsのルーティング と リクエストハンドラ
21. お品書き - 話の前提となるアプリケーション構成 - Next.jsのルーティングとリクエストハンドラ - Next.jsのルーティングをおさらい - Route Handlerで実装するHTTP API - HonoとNext.jsを統合する - Hono OpenAPI 21
22. お品書き - 話の前提となるアプリケーション構成 - Next.jsのルーティングとリクエストハンドラ - Next.jsのルーティングをおさらい - Route Handlerで実装するHTTP API - HonoとNext.jsを統合する - Hono OpenAPI 22
23. Next.jsのルーティング - Next.jsはファイルベースでルーティング - ディレクトリ構成とURL構成が一致する - /app/foo/page.tsxでコンポーネントをエクスポートす ると /fooへのリクエストで表示される - 規約に沿ったディレクトリ名で特別扱いをする - URLの一部を動的に処理 23
24. Dynamic Route Segments - パスにidなどが含まれるURLを処理する仕組み - 例）GET /api/foo/:slug/list - ハンドラ内でURLの値を取得できる - 例) slug - []で囲うと動的になる - 例）api/foo/[slug]/list/route.ts で/api/foo/1/list な どの処理ができる 24
25. 多階層の処理 - []で囲ったときは1階層 - 例）api/foo/[slug]/list/route.ts で/api/foo/1/list な どの処理ができる - /api/barと/api/bar/bazを同一ハンドラで処 理したいときもある - Catch-all Segmentsの登場 25
26. 2つのCatch-all - Catch-all - /api/foo/[...slug]/route.tsで以下にマッチ - /api/foo/1, /api/foo/1/2/3 - Optional Catch-all - /api/foo/[[...slug]]/route.tsで以下にマッチ - /api/foo/1, /api/foo/1/2/3, /api/foo - あとで出てきます 26
27. 2つのCatch-all - Catch-all - /api/foo/[...slug]/route.tsで以下にマッチ - /api/foo/1, /api/foo/1/2/3 - Optional Catch-all - /api/foo/[[...slug]]/route.tsで以下にマッチ - /api/foo/1, /api/foo/1/2/3, /api/foo ←にマッチするのが Optional Catch-all - あとで出てきます 27
28. Route Groups - Next.jsはファイルベースルーティング - URLとディレクトリ構造が一致 - とはいえURLとは別にグループを作りたくなる - 関心や機能で分ける - ディレクトリ名を()で囲むとURLには表れない グループができる - 例 /api/(admin)/ と /api/(guest)/ 28
29. Next.jsルーティングまとめ - 基本はファイルベース - []で囲うとハンドラで値が取れる - 例） /api/foo/[slug]/list - [...slug]のように3点始まりだとCatch-all - [[...slug]]のように[[]]で囲うとOptional Catch-all - ()で囲うとパスに表れないグループができる - Route Groups 29
30. お品書き - 話の前提となるアプリケーション構成 - Next.jsのルーティングとリクエストハンドラ - Next.jsのルーティングをおさらい - Route Handlerで実装するHTTP API - HonoとNext.jsを統合する - Hono OpenAPI 30
31. 31 Next.jsでAPIを提供する - /api/foo/route.tsに以下のコードを置く - Route Handlerと呼ばれている - /api/fooへのGETで200 OKが返る export async function GET(request: Request) { return new NextResponse("ok", {status: 200}); }
32. 入出力のバリデーション - Next.js組み込みの入出力値検査はない - 入力はawait req.json()で取得し自前でバリ デーションする - バリデーションはスキーマライブラリを使うの が良い 32
33. Zod, Valibotなどのスキーマライブラ リ - スキーマを定義し検査するライブラリ - Zod, Valibot, ArkType, … - TypeScriptだと値に型がついてお得 import * as v from 'valibot'; const inputSchema = v.object({ id: v.string() }) v.parse(inputSchema, await req.json()) 33
34. 34 HonoとNext.js
35. お品書き - 話の前提となるアプリケーション構成 - Next.jsのルーティングとリクエストハンドラ - HonoとNext.jsを統合する - Hono OpenAPI 35
36. 36 Next.js統合 - HonoはNext.jsと統合できる - ドキュメントにもある - https://hono.dev/docs/getting-started/nextjs - hono/vercelを使うといい感じにハンドルされ る
37. Honoのルータどこに置く - Next.jsはファイルベースルーティング - Honoはあるファイルがルータとして処理を分 配してほしい - Honoとはルーティングの考えかたが違う - Routerを置くHonoとRoutingをフレームワークがやる Next.js 37
38. Honoのハンドラどこに置く - （復習）[[...foo]]/route.tsで全てのリクエス トを扱える - Optional Catch-all Segments - Route Groupsで関心を分けたい - Next.jsで処理されるハンドラとHonoで処理されるハン ドラ 38
39. 実装例 // app/api/(hono)/[[...slug]]/route.tsに以下のファイルを配置 import { Hono } from 'hono' import { handle } from 'hono/vercel' const app = new Hono().basePath('/api') app.get('/hello', (c) => { return c.json({ message: 'Hello Next.js!' }) }) export const GET = handle(app) export const POST = handle(app) // https://hono.dev/docs/getting-started/nextjs より引用し一部改変 39
40. 実装例 // app/api/(hono)/[[...slug]]/route.tsに以下のファイルを配置 import { Hono } from 'hono' import { handle } from 'hono/vercel' const app = new Hono().basePath('/api') app.get('/hello', (c) => { return c.json({ message: 'Hello Next.js!' }) }) export const GET = handle(app) export const POST = handle(app) // https://hono.dev/docs/getting-started/nextjs より引用し一部改変 40 アダプタとして hono/vercelをimport
41. 実装例 // app/api/(hono)/[[...slug]]/route.tsに以下のファイルを配置 import { Hono } from 'hono' import { handle } from 'hono/vercel' const app = new Hono().basePath('/api') app.get('/hello', (c) => { return c.json({ message: 'Hello Next.js!' }) }) export const GET = handle(app) export const POST = handle(app) // https://hono.dev/docs/getting-started/nextjs より引用し一部改変 41 アダプタとして hono/vercelをimport Next.jsは特定名でexport された関数がリクエストを ハンドルする hono/vercelのhandleで 囲って関数を実装
42. 既存の実装と同居 - 過渡期はRoute Handlerで実装されたハンドラ とHonoで実装されたハンドラが同居 - 意味的にも違うのでRoute Groupsで分ける - Honoで実装されたハンドラは(hono)ディレク トリ以下に置く 42
43. めでたしめでたし - Next.jsのAPIをHonoで実装することに成功 - ElysiaJSでも同じ手法が紹介されている - https://elysiajs.com/integrations/nextjs.html - 新規に実装するだけだったらこれで良いが…… - 我々にはすでに実装した既存のリソースがある 43
44. 既存のリソースとどう同居する？ - Next.jsの仕組みで実装したミドルウェア - ロギング - 認証 - トレース - Route Handlerで実装した既存エンドポイント 44
45. 既存のリソースとどう同居する？ - Next.jsの仕組みで実装したミドルウェア - ロギング - 認証 - トレース - Route Handlerで実装した既存エンドポイント 45
46. 既存のミドルウェア - 今回の手法はあくまでNext.jsのルーティング をHonoに委譲するだけ - ミドルウェアの処理がされてからHonoに渡っ てくる - Next.jsミドルウェア, Next.jsルータ, Honoのルータの順 で処理 - なので考慮不要。そのままで良いはず 46
47. 既存のリソースとどう同居する？ - Next.jsの仕組みで実装したミドルウェア - ロギング - 認証 - トレース - Route Handlerで実装した既存エンドポイント 47
48. Optional Catch-all segments の処理順 . └── api ├── (hono) │ └── [[...slugs]] │ └── route.ts (1) └── foo └── route.ts (2) 48 /api/fooへの処理 (2)のRoute Handlerが 処理する (1)のroute.tsに書いた /api/fooのハンドラは 実行されない
49. Optional Catch-all segments の処理順 . └── api ├── (hono) │ └── [[...slugs]] │ └── route.ts (1) └── foo └── route.ts (2) 49 左のような構造のコー ドを想定 (1)のroute.tsに書いた /api/fooのハンドラは 実行されない Optional Catch-all segmentsの 処理優先順位が低い
50. Optional Catch-all segments - Optional Catch-all segmentsの処理優先順位 が低い - つまりRoute Handlerの実装をそのままに Honoの実装を増やせる - 段階的な移行が可能 50
51. 既存のリソースとどう同居する？ まとめ - Next.jsの仕組みで実装したミドルウェア - -> 手を加えず、そのままで良い - Route Handlerで実装した既存エンドポイント - -> Hono側の実装が後に評価されるのでそのままで良い 51
52. Next.js x Honoまとめ - Route Handlerで作ったハンドラそのままに Honoのハンドラを横付け - 段階的にHonoの強力なエコシステムを獲得 52
53. 53 Hono OpenAPI
54. お品書き - 話の前提となるアプリケーション構成 - Next.jsのルーティングとリクエストハンドラ - HonoとNext.jsを統合する - Hono OpenAPI 54
55. Hono OpenAPI - Honoのミドルウェアとしてふるまう - 入力値のバリデーションやドキュメント生成を 行なう - 先日v1が出た - 🎉standard schema対応 55
56. スキーマ出力 - Hono OpenAPIはopenapi.jsonを出力できる - https://honohub.dev/docs/openapi/persisting - generateSpecsにHonoのappを渡すと出力される - 出力スクリプトをCIで都度実行、差分があった ら落ちるように - 常に正しいopenapi.jsonがリポジトリにある状態 56
57. OpenAPIの恩恵 - API呼び出し側はopenapi.jsonを元に実装可能 - 例えばopenapi-generator-cliでコード生成 - Swaggerを用いれば人間が読みやすいドキュメ ントも入手できる 57
58. 課題解決 - API仕様の変更追従漏れ課題があった - 仕様を自動生成することで解決 - 人間が都度変更する必要がなくなる - CIなどで仕様変更と同時に壊れたことを検知できる 58
59. 59 Next.jsと Hono+Hono OpenAPI
60. 60 ここまでの話をまとめる - HonoとNext.jsを連携できる - HonoとHono OpenAPIを繋げるとHonoを OpenAPI対応できる
61. 61 ここまでの話をまとめる - HonoとNext.jsを連携できる - HonoとHono OpenAPIを繋げるとHonoを OpenAPI対応できる Next.jsでもHonoを使って OpenAPIの支援を受けられるようになる
62. 62 ここまでの話をまとめる - HonoとNext.jsを連携できる - Honoとhono-openapiを繋げるとHonoを OpenAPI対応できる Next.jsでもHonoを使って OpenAPIの支援を受けられるようになる
63. 63 まとめ
64. 64 まとめ - Next.jsで提供するHTTP APIをHonoによって 提供 - Hono OpenAPIでOpenAPIの力を手にいれる - Next.jsでもコードファーストでAPI仕様を生成 する - Honoを導入することで豊富なエコシステムを 獲得