クイックスタート

関連ソースファイル

このページの内容は以下のソースファイルに基づいて生成されています：

• README.md
• src/hono.ts
• src/index.ts
• src/types.ts
• src/context.ts
• src/http-exception.ts
• src/hono.test.ts
• src/router.ts
• src/hono-base.ts
• src/types.test.ts

Honoは日本語で「炎」を意味する、軽量で高速なWebフレームワークである。Web標準に基づいて構築されており、Cloudflare Workers、Deno、Bun、Node.jsなど、あらゆるJavaScriptランタイムで動作する。

プロジェクトの作成

Honoプロジェクトを作成する最も迅速な方法は、公式が提供するスキャフォールディングコマンドを使用することである。このコマンドを実行すると、対話形式でランタイム（Cloudflare Workers、Deno、Bun、Node.jsなど）を選択でき、自動的にプロジェクトテンプレートが生成される。

bash
1npm create hono@latest

このコマンドは README.md:35-39 で「Quick Start」として紹介されている公式の推奨方法である。実行後、プロジェクト名と使用するランタイムの選択を求められる。

Honoの基本概念として、以下の最小限のコード例が示されている通り、Honoクラスをインポートしてインスタンス化し、ルートを定義するだけでWebアプリケーションを構築できる。

ts
1import { Hono } from 'hono'
2const app = new Hono()
3
4app.get('/', (c) => c.text('Hono!'))
5
6export default app

このコード例は README.md:22-33 に記載されており、Honoのシンプルさを示している。

基本的なアプリケーション構造

Honoアプリケーションのエントリーポイントは、src/index.tsで定義されている。このファイルは src/index.ts:1-52 に示す通り、Honoクラスをメインエクスポートとして公開し、型定義を再エポートする。

ts
1import { Hono } from './hono'
2
3export type {
4  Env,
5  ErrorHandler,
6  Handler,
7  MiddlewareHandler,
8  // ... その他の型
9} from './types'
10
11export { Hono }

Honoクラス自体は src/hono.ts:1-34 で定義されており、HonoBaseクラスを継承している。コンストラクタでは、オプションとしてrouterを受け取り、指定がない場合はSmartRouter（内部でRegExpRouterとTrieRouterを使用）をデフォルトルーターとして設定する。

ts
1export class Hono<
2  E extends Env = BlankEnv,
3  S extends Schema = BlankSchema,
4  BasePath extends string = '/',
5> extends HonoBase<E, S, BasePath> {
6  constructor(options: HonoOptions&lt;E&gt; = {}) {
7    super(options)
8    this.router =
9      options.router ??
10      new SmartRouter({
11        routers: [new RegExpRouter(), new TrieRouter()],
12      })
13  }
14}

この設計により、開発者は必要に応じてカスタムルーターを注入できる柔軟性を持つ。

Contextの基本操作

Honoのリクエスト処理において中心的な役割を果たすのがContextクラスである。このクラスは src/context.ts:293-369 で定義されており、リクエストオブジェクト、レスポンスオブジェクト、環境変数へのアクセスを提供する。

Contextの主要プロパティ

Contextクラスのコンストラクタは以下のように定義されている：

ts
1constructor(req: Request, options?: ContextOptions<E>) {
2  this.#rawRequest = req
3  if (options) {
4    this.#executionCtx = options.executionCtx
5    this.env = options.env
6    this.#notFoundHandler = options.notFoundHandler
7    this.#path = options.path
8    this.#matchResult = options.matchResult
9  }
10}

レスポンスの操作

レスポンスオブジェクトの取得と設定は src/context.ts:399-434 で実装されている。resゲッターは、まだレスポンスが作成されていない場合、空のResponseインスタンスを生成して返す。

ts
1get res(): Response {
2  return (this.#res ||= createResponseInstance(null, {
3    headers: (this.#preparedHeaders ??= new Headers()),
4  }))
5}
6
7set res(_res: Response | undefined) {
8  // ヘッダーのマージ処理など
9  this.#res = _res
10  this.finalized = true
11}

setアクセサでは、既存のレスポンスヘッダーを新しいレスポンスにマージする処理が行われる。特にset-cookieヘッダーは特別扱いされ、複数のCookieが正しく保持される。

エラーハンドリング

Honoでは、HTTPエラーを表現するためにHTTPExceptionクラスを提供している。このクラスは src/http-exception.ts:1-78 で定義されており、認証失敗などの致命的なエラーが発生した場合に使用する。

HTTPExceptionの使用例

ts
1import { HTTPException } from 'hono/http-exception'
2
3app.post('/auth', async (c, next) => {
4  // 認証処理
5  if (authorized === false) {
6    throw new HTTPException(401, { message: 'Custom error message' })
7  }
8  await next()
9})

HTTPExceptionのコンストラクタは、ステータスコードとオプションオブジェクトを受け取る。オプションには以下を指定できる：

• res: カスタムResponseオブジェクト
• message: エラーメッセージ
• cause: エラーの原因

ミドルウェアでのエラー取得

ミドルウェア内で発生したエラーは、Contextのerrorプロパティから取得できる。このプロパティは src/context.ts:318-333 で定義されている。

ts
1/**
2 * `.error` can get the error object from the middleware if the Handler throws an error.
3 */
4error: Error | undefined

使用例：

ts
1app.use('*', async (c, next) => {
2  await next()
3  if (c.error) {
4    // エラー処理
5  }
6})

環境要件とインストール

対応ランタイム

Honoは以下のJavaScriptランタイムで動作する（README.md:22-33）：

インストール方法

npmを使用する場合：

bash
1npm install hono

yarnを使用する場合：

bash
1yarn add hono

pnpmを使用する場合：

bash
1pnpm add hono

Denoを使用する場合：

ts
1import { Hono } from 'https://deno.land/x/hono/mod.ts'

Bunを使用する場合：

bash
1bun add hono

※具体的なインストールコマンドの記述は、提供されたソースファイル内に見つからなかったため「需要确认」とする。パッケージマネージャーの公式ドキュメントまたはpackage.jsonの確認を推奨する。

動作確認

Cloudflare Workersでの確認

npm create hono@latestでCloudflare Workersテンプレートを選択した場合、以下のコマンドで開発サーバーを起動できる（需要确认 — 具体的なコマンドはテンプレートのpackage.jsonを参照）：

bash
1npm run dev

期待される出力

開発サーバーが正常に起動すると、通常は以下のような出力が表示される（需要确认）：

Ready on http://localhost:8787

ヘルスチェック

ブラウザまたはcurlでルートエンドポイントにアクセスし、Hono!というテキストレスポンスが返ってくれば正常に動作している：

bash
1curl http://localhost:8787/
2# 期待される出力: Hono!

※ポート番号（8787）はCloudflare Workersのwranglerのデフォルト値であるが、提供されたソースファイル内で確認できていないため「需要确认」とする。

トラブルシューティング

よくある問題と解決策

エラーのデバッグ

ミドルウェアでエラーをキャッチし、ログを出力することで問題の特定が容易になる：

ts
1app.use('*', async (c, next) => {
2  try {
3    await next()
4  } catch (err) {
5    console.error('Error:', err)
6    throw err
7  }
8})

HTTPExceptionのレスポンスカスタマイズ

HTTPExceptionがスローされた場合、デフォルトのエラーレスポンスが返される。カスタムレスポンスを返す場合は、アプリケーションレベルでエラーハンドラーを設定する必要がある（需要确认 — 具体的なエラーハンドラーの設定方法はHonoOptionsの型定義またはドキュメントを参照）。

次のステップ

クイックスタートガイドでは、Honoの基本的なセットアップと使用方法を説明した。より高度な機能については、以下のトピックを参照すること：

1. ルーティング - パスパラメータ、クエリパラメータ、ルートグループの使用
2. ミドルウェア - 組み込みミドルウェアとカスタムミドルウェアの作成
3. バリデーション - Zodなどのスキーマバリデーションの統合
4. RPC - クライアントとサーバー間の型安全な通信

公式ドキュメントは hono.dev で公開されている（README.md:49-51）。