Guren を一目で
Laravel のような書き心地の、フルスタック TypeScript フレームワーク — Bun で動きます。
ドキュメント
Guren を、
最初から最後まで。
ルーティング、モデル、認証、キューまで全サブシステムのガイドと、動くアプリを作るチュートリアル。どのページも実行できるコードから始まります。
ガイド
はじめに
Why Guren
Guren の立ち位置を正直に整理します — Hono・Next.js・AdonisJS・Laravel との比較と、Guren がこの設計になっている理由です。
はじめる
このガイドは 2 部構成です。Part A では、Docker もデータベースサーバーも使わず、SQLite で新規 Guren アプリを 5 分程度で動かします。Part B ではフルセットアップを扱います: Postgres / MySQL、環境変数、機能ジェネレーター、本番ビルドなどです。まず Part A から始めて、必要になったら Part B に戻ってきてください。
ファーストステップ: 1 つのリクエストを辿る 10 分ツアー
このツアーでは、単一のリクエスト — GET /posts — が Guren アプリのすべてのレイヤーを通る様子を追いかけます: ルート、コントローラー、バリデーション、モデル、リソース、Inertia ページ、そしてテストです。頭の中に地図を作るために読んでください。各ストップには、より深く学べるガイドへのリンクがあります。
アーキテクチャ
Guren は Laravel の設計思想を TypeScript 上で再構成し、Bun・Hono・Inertia.js・React・Drizzle ORM を束ねたフルスタック MVC フレームワークです。ここではルーティングからレスポンス生成までの流れと主要コンポーネントを説明します。
基本
ルーティングガイド
Guren は Hono の HTTP サーバー上に Laravel 風のルーティング DSL を提供します。推奨構成では routes/web.ts が registrar 関数を export し、アプリ起動時に app-local な Router へルートを登録します。
コントローラーガイド
コントローラーは、受信した HTTP リクエストを処理し、モデルを通じてデータを取得し、Inertia や JSON ペイロードでレスポンスを返す役割を担います。すべてのコントローラーは app/Http/Controllers/ に配置し、フレームワークの Controller 基底クラスを継承します。このガイドでは、コントローラーと routes/web.ts で定義されるルートとの接続方法も説明します。
ミドルウェアガイド
Guren のルートとアプリケーションは Hono のミドルウェアモデルを共有しつつ、よく使うケースで Laravel 風の書き心地を提供します。Application インスタンスにグローバル登録する方法と、ルート DSL で個別に付与する方法があります。
CSRF 保護
CSRF（Cross-Site Request Forgery）保護は、悪意のあるウェブサイトが認証済みユーザーの代わりにフォームを送信することを防ぎます。Guren はセッションとシームレスに統合する組み込みの CSRF ミドルウェアを提供しています。
バリデーション
Guren のバリデーションは schema-first が基本です。Zod 互換スキーマをコントローラー、ルートコントラクト、ミドルウェアで使い回し、必要な場合だけ legacy な FormRequest 互換レイヤーを使います。
エラーハンドリング
Guren はグローバルエラーハンドラーからコントローラーレベルの例外キャッチまで、複数層のエラーハンドリングを提供しています。Hono の堅牢なエラーハンドリングプリミティブをベースに、ユーザーへのエラー表示をカスタマイズできます。
データベースガイド
Guren は Drizzle ORM と PostgreSQL を組み合わせて使います。このガイドでは、スキーマ定義、マイグレーション、シーダー、アプリケーションコードからの日常的な利用方法を説明します。
フロントエンドガイド
Guren は Inertia.js と React を組み合わせ、単一ページアプリの体験を提供します。コントローラーは Inertia レスポンスを返し、フロントエンドは resources/js/pages/ 配下の React コンポーネントを描画します。
セキュリティ
認証ガイド
Guren には Laravel 由来の認証スタックが同梱され、セッションミドルウェアと ORM の上に構築されています。TypeScript/Bun に馴染む形でガードとユーザープロバイダーを提供します。
OAuthガイド
Guren は「GitHub / Google / Discordでサインイン」のようなログインのための OAuth 2.0 認可コードフローを提供します。リダイレクト、CSRF対策済みのstate管理、トークン交換、プロフィール取得を処理し、あなたは自分のログインコントローラーとセッションに組み込むだけです。
認可
認可は、認証済みユーザーが実行できる操作を制御する仕組みです。Guren は Laravel に着想を得たポリシーベースの認可システムを提供しています。
APIトークンガイド
Guren はAPIリクエストを認証するためのセキュアなAPIトークンシステムを提供します。トークンは保存前にハッシュ化され、abilities（スコープ）をサポートし、有効期限を設定できます。
パスワードリセットガイド
Guren はトークン生成、検証、有効期限を備えたセキュアなパスワードリセットシステムを提供します。トークンはセキュリティのため、保存前にハッシュ化されます。
メール確認ガイド
Guren はトークン生成、検証、有効期限を備えたセキュアなメール確認システムを提供します。トークンはセキュリティのため、保存前にハッシュ化されます。
暗号化とハッシュ
Guren はデータの暗号化とパスワードの安全なハッシュ化のためのユーティリティを提供しています。
応用機能
イベントガイド
Guren はアプリケーション内のコンポーネントを疎結合にするための、シンプルかつ強力なイベントシステムを提供します。イベントを使用することで、アプリケーション内で発生した出来事を他の部分がリッスンして反応できるようになります。
キューガイド
Guren は、時間のかかるタスクをバックグラウンドで処理するための堅牢なキューシステムを提供します。これは、メール送信、アップロード処理、外部API呼び出しなどの操作を行いながら、高速なレスポンスタイムを維持するために不可欠です。
キャッシュガイド
Guren は複数のストレージバックエンドをサポートする統一されたキャッシュAPIを提供します。キャッシュは、コストの高い計算やデータベースクエリを保存して高速に取得することで、アプリケーションのパフォーマンス向上に役立ちます。
メールガイド
Guren はメール送信のための Fluent API を提供し、複数のトランスポートバックエンドをサポートしています。メールシステムはキューシステムと統合して非同期送信を実現し、HTMLテンプレート、添付ファイルなどをサポートします。
通知ガイド
Guren はメール、データベース、Slackなど複数のチャンネルで通知を送信するための統一されたAPIを提供します。通知はクラスベースで、再利用可能でテストが容易です。
ブロードキャスティングガイド
Guren は接続されたクライアントへのリアルタイムイベント配信のためのブロードキャスティングシステムを提供します。ライブ通知、チャットアプリケーション、リアルタイムダッシュボードなどの機能を構築するのに便利です。
ストレージガイド
Guren は複数のストレージバックエンドをサポートする統一されたファイルストレージAPIを提供します。ストレージシステムにより、ローカルファイルシステム、Amazon S3、その他のクラウドストレージプロバイダーを一貫したインターフェースで簡単に扱えます。
タスクスケジューリングガイド
Guren はアプリケーション内でスケジュールタスクを定義するための Fluent API を提供します。複数のcronエントリを管理する代わりに、コード内でタスクスケジュール全体を定義できます。
レート制限ガイド
Guren はアプリケーションを乱用から保護するための柔軟なレート制限システムを提供します。複数のストレージバックエンド、カスタムキージェネレーター、固定ウィンドウとスライディングウィンドウの両方のアルゴリズムをサポートしています。
ロギングガイド
Guren はRFC 5424に準拠したログレベル、複数のチャンネル、コンテキスト付きロギングをサポートする柔軟なロギングシステムを提供します。
ヘルスチェック
Guren はアプリケーションの依存関係やサービスを監視するための包括的なヘルスチェックシステムを提供します。ロードバランサー、オーケストレーター、監視ツール向けに/healthエンドポイントを公開するためにヘルスチェックを使用します。
国際化（i18n）ガイド
Guren は翻訳管理、複数言語の複数形サポート、ファイルベースとメモリベースの両方のローダーを備えた包括的な国際化システムを提供します。
APIリソース
APIリソースは、モデルとAPIレスポンス間の変換レイヤーを提供します。データがJSONにシリアライズされる方法を細かく制御できます。
テストとデプロイ
テストガイド
よく書かれた一つのテストは、ユーザーより先にバグを見つけてくれます。Guren はテストを書くことがブラウザで手動確認するより速く感じられるほど便利にできています。
デプロイガイド
create-guren-app で生成したアプリを本番に出す手順をまとめます。PostgreSQL が利用できる前提です。
サーバーレスデプロイ（AWS Lambda）
@guren/core/lambda アダプターで Guren を AWS Lambda 上で動かせます。このガイドでは HTTP、キュー、スケジュールタスク、CLI コマンド、インフラ構成のすべてをカバーします。
本番運用ランブック
GA（正式リリース）前に必要な運用基準を定義します。
リファレンス
認証アプリを作る
このガイドでは、ユーザー登録・ログイン・保護されたルートを備えたアプリケーションを構築します。空のディレクトリから認証フロー完成まで、10分以内で完了できます。
API を構築して公開する
このガイドでは、Guren で JSON API を構築して公開するまでの手順を説明します。API 専用プロジェクトの作成、データベーススキーマの定義、バリデーション付きコントローラーの作成、エンドポイントのテストまでをカバーします。
本番環境にデプロイする
このガイドでは、Guren アプリケーションをローカル開発環境から本番環境に移行するための手順を説明します。Bun を使った Docker ベースのデプロイを中心に解説します。
セットアップのトラブルシューティング
このガイドでは、Guren での開発中によく遭遇する問題とその解決方法を紹介します。何か問題が起きたときは、個別のパッケージドキュメントを読む前にまずここを確認してください。
CLI リファレンス
Guren には 2 つの CLI が付属します。
プラグイン作成ガイド
このガイドでは、Gurenプラグインの作成、テスト、公開の手順を解説します。
サポートマトリクス
| ランタイム | バージョン | ステータス |
Guren アップグレードガイド
マイナーバージョン間のアップグレード時に使用する手順です。
リリース / 互換性ポリシー
このドキュメントは、本番運用に向けた最低限のリリース契約を定義します。
用語集
Guren のドキュメントで頻出する言葉を、初学者向けに短くまとめます。ここにない用語は各ガイドの文脈で補足しています。
チュートリアル
ミニブログを作る
チュートリアル: ミニブログを作る
このチュートリアルシリーズでは、空のディレクトリから、小さいながらも本物のブログアプリケーションを作り上げます。スキーマ、モデル、バリデーター、コントローラー、ルート、React ページ — と 1 レイヤーずつ積み上げていくので、完走する頃には Guren アプリの各パーツがどう噛み合うのかを理解できているはずです。
Part 1: ブログ投稿アプリを作る
このパートではブログの心臓部 — 投稿の作成・一覧・閲覧 — を作ります。テーブル、モデル、バリデーター、コントローラー、ルート、ページと、すべてのファイルを自分の手で書くので、リクエストが Guren アプリケーションの中をどう流れるかを正確に把握できます。
Part 2: 認証を追加する
Part 1 で作ったブログは、誰でも投稿を公開できてしまいます。このパートでは、コマンド 1 つでユーザーアカウントを追加し、投稿作成をログイン必須にして、すべての投稿に著者を紐づけます。
Part 3: リレーションシップ: コメント
Part 2 を終えて、ブログには投稿と著者が揃いました。最終パートでは読者に声を持たせます: 投稿とユーザーの両方に属する comments テーブルを追加し、モデルのリレーションシップを配線して、投稿ページにコメントフォームを作ります。