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 コンポーネントを描画します。
サーバーレンダリングビュー
this.view() は JSX コンポーネントをプレーンなサーバーレンダリング HTML レスポンスとして返します。ブログ記事、ドキュメント、マーケティングページのような公開・読み取り中心のページ向けの、this.inertia() のハイドレーションしない対になる存在です。クライアントフレームワークなし、ハイドレーションなし、Inertia のページペイロードスクリプトもドキュメントに含まれません。guren.dev 自身のブログ記事がこの仕組みで配信されています。
セキュリティ
認証ガイド
Guren には Laravel 由来の認証スタックが同梱され、セッションミドルウェアと ORM の上に構築されています。TypeScript/Bun に馴染む形でガードとユーザープロバイダーを提供します。
OAuthガイド
Guren は「GitHub / Google / Discordでサインイン」のようなログインのための OAuth 2.0 認可コードフローを提供します。リダイレクト、CSRF対策済みのstate管理、トークン交換、プロフィール取得を処理し、あなたは自分のログインコントローラーとセッションに組み込むだけです。
認可
認可は、認証済みユーザーが実行できる操作を制御する仕組みです。Guren は Laravel に着想を得たポリシーベースの認可システムを提供しています。
APIトークンガイド
Guren はAPIリクエストを認証するためのセキュアなAPIトークンシステムを提供します。トークンは保存前にハッシュ化され、abilities（スコープ）をサポートし、有効期限を設定できます。
パスワードリセットガイド
Guren はトークン生成、検証、有効期限を備えたセキュアなパスワードリセットシステムを提供します。トークンは保存されず署名されます。ストアに渡るのは不透明なトークン ID だけです。
メール確認ガイド
Guren はトークン生成、検証、有効期限を備えたセキュアなメール確認システムを提供します。トークンは保存されず署名されます。ストアに渡るのは不透明なトークン ID だけです。
暗号化とハッシュ
Guren はデータの暗号化とパスワードの安全なハッシュ化のためのユーティリティを提供しています。
応用機能
イベントガイド
Guren はアプリケーション内のコンポーネントを疎結合にするための、シンプルかつ強力なイベントシステムを提供します。イベントを使用することで、アプリケーション内で発生した出来事を他の部分がリッスンして反応できるようになります。
キューガイド
Guren は、時間のかかるタスクをバックグラウンドで処理するための堅牢なキューシステムを提供します。これは、メール送信、アップロード処理、外部API呼び出しなどの操作を行いながら、高速なレスポンスタイムを維持するために不可欠です。
キャッシュガイド
Guren は複数のストレージバックエンドをサポートする統一されたキャッシュAPIを提供します。キャッシュは、コストの高い計算やデータベースクエリを保存して高速に取得することで、アプリケーションのパフォーマンス向上に役立ちます。
メールガイド
Guren はメール送信のための Fluent API を提供し、複数のトランスポートバックエンドをサポートしています。メールシステムはキューシステムと統合して非同期送信を実現し、HTMLテンプレート、添付ファイルなどをサポートします。
通知ガイド
Guren はメール、データベース、Slackなど複数のチャンネルで通知を送信するための統一されたAPIを提供します。通知はクラスベースで、再利用可能でテストが容易です。
ブロードキャスティングガイド
Guren は接続されたクライアントへのリアルタイムイベント配信のためのブロードキャスティングシステムを提供します。ライブ通知、チャットアプリケーション、リアルタイムダッシュボードなどの機能を構築するのに便利です。
ストレージガイド
Guren は複数のストレージバックエンドをサポートする統一されたファイルストレージAPIを提供します。ストレージシステムにより、ローカルファイルシステム、Amazon S3、その他のクラウドストレージプロバイダーを一貫したインターフェースで簡単に扱えます。
アタッチメントガイド
アタッチメントは、アップロードされたファイルをモデルに結び付けます。「Post は cover 画像を1つと images を複数持つ」という宣言をモデルに書くと、ファイルはストレージディスクに保存され、1つの attachments テーブルで追跡され、画像バリデーションとサムネイル用のバリアント生成が組み込みで付いてきます。宣言はモデル上にあるため、コレクション名、one/many の種別、バリアント名はすべてコンパイル時に検査されます。
タスクスケジューリングガイド
Guren はアプリケーション内でスケジュールタスクを定義するための Fluent API を提供します。複数のcronエントリを管理する代わりに、コード内でタスクスケジュール全体を定義できます。
コンソールコマンド
コンソールコマンドを使うと、バックフィル・単発のメンテナンス・レポート生成といった処理を、HTTP ハンドラと同じモデル・サービス・コンテナを使ってターミナルから実行できます。
レート制限ガイド
Guren はアプリケーションを乱用から保護するための柔軟なレート制限システムを提供します。複数のストレージバックエンド、カスタムキージェネレーター、固定ウィンドウとスライディングウィンドウの両方のアルゴリズムをサポートしています。
ロギングガイド
Guren はRFC 5424に準拠したログレベル、複数のチャンネル、コンテキスト付きロギングをサポートする柔軟なロギングシステムを提供します。
ヘルスチェック
Guren はアプリケーションの依存関係やサービスを監視するための包括的なヘルスチェックシステムを提供します。ロードバランサー、オーケストレーター、監視ツール向けに/healthエンドポイントを公開するためにヘルスチェックを使用します。
国際化(i18n)ガイド
Gurenは国際化を一気通貫でサポートします: ファイルベースの翻訳カタログ、リクエスト単位のロケール検出、コントローラーとReactページの翻訳ヘルパー、15言語超の複数形化ルール、型付き翻訳キー、そしてカタログの整合性チェッカーです。
APIリソース
APIリソースは、モデルとAPIレスポンス間の変換レイヤーを提供します。データがJSONにシリアライズされる方法を細かく制御できます。
Markdownレンダリング
@guren/plugin-markdownは、堅牢なデフォルト設定でmarkdownをHTMLにレンダリングします。GitHub Flavored Markdown、dangerouslySetInnerHTMLに安全なサニタイズ済み出力、GitHubスタイルのアラート、見出しアンカー、そしてオプションのshikiコードハイライトを備えています。guren.dev自身のdocsとブログが使っているパイプラインです。
テストとデプロイ
テストガイド
よく書かれた一つのテストは、ユーザーより先にバグを見つけてくれます。Guren はテストを書くことがブラウザで手動確認するより速く感じられるほど便利にできています。
デプロイガイド
create-guren-app で生成したアプリを本番に出す手順をまとめます。PostgreSQL が利用できる前提です。
サーバーレスデプロイ（AWS Lambda）
Guren は AWS Lambda の Node.js ランタイム上で動作します。公式プラグイン @guren/plugin-lambda がバンドルを担当し、CDK コンストラクトが HTTP・キュー・スケジュールタスク・CLI コマンド・静的アセットまでフルスタックをプロビジョニングします。
Cloudflare Workers へのデプロイ
Guren は @guren/plugin-cloudflare を通じて Cloudflare Workers 上で動作し、データベースには D1 を使います。このガイドでは、まっさらなアカウントからデプロイ完了までを一通り扱います。
本番運用ランブック
GA（正式リリース）前に必要な運用基準を定義します。
AIネイティブ開発
スペックアンカード開発
AIエージェントは、人間が手作業でドキュメントを正しく保てる速度を超えて
エージェントインターフェース
AI エージェントは MCP を通じてアプリケーションを呼び出します。Guren では、エージェント向けにもう1つアプリケーションを書く必要はありません。エージェントツールは、ルートがすでに持っているコントラクトから導出されます。ルートの params・query・body スキーマがツールの入力スキーマになり、output スキーマがツールの出力スキーマになり、ミドルウェアチェーンが検査するポリシーがツールの認可になります。
永続エージェント
永続エージェント(durable agent)は、アプリケーション自身がホストする長命でステートフルなプロセスです。そしてアプリケーションへは、ルートがすでに宣言しているエージェントツールを通してしか到達しません。
リファレンス
認証アプリを作る
このガイドでは、ユーザー登録・ログイン・保護されたルートを備えたアプリケーションを構築します。空のディレクトリから認証フロー完成まで、10分以内で完了できます。
API を構築して公開する
このガイドでは、Guren で JSON API を構築して公開するまでの手順を説明します。API 専用プロジェクトの作成、データベーススキーマの定義、バリデーション付きコントローラーの作成、エンドポイントのテストまでをカバーします。
本番環境にデプロイする
このガイドでは、Guren アプリケーションをローカル開発環境から本番環境に移行するための手順を説明します。Bun を使った Docker ベースのデプロイを中心に解説します。
セットアップのトラブルシューティング
このガイドでは、Guren での開発中によく遭遇する問題とその解決方法を紹介します。何か問題が起きたときは、個別のパッケージドキュメントを読む前にまずここを確認してください。
CLI リファレンス
Guren には 2 つの CLI が付属します。
プラグイン作成ガイド
このガイドでは、Gurenプラグインの作成、テスト、公開の手順を解説します。
サポートマトリクス
| ランタイム | バージョン | ステータス |
Guren アップグレードガイド
マイナーバージョン間のアップグレード時に使用する手順です。
リリース / 互換性ポリシー
このドキュメントは、本番運用に向けた最低限のリリース契約を定義します。
用語集
Guren のドキュメントで頻出する言葉を、初学者向けに短くまとめます。ここにない用語は各ガイドの文脈で補足しています。
チュートリアル
基礎
第 1 章: ゼロから出荷できるアプリへ
この章では Guren アプリを雛形生成し、雛形が何を用意してくれたのかを読み、テストを先に置いた上で変更をひとつ手で加え、変更をひとつコーディングエージェントに委ねてハーネスがその仕事を検査する様子を見届け、最後にどこでも動かせるコンテナイメージを手にします。以降のすべての章も同じ形で終わります。ゲートが緑で、コミット済みで、出荷できる状態です。
第 2 章: リクエストをひとつ、手で
第 1 章で手にしたアプリには、あなたが書いていないページがひとつありました。この章では次のページを空のファイルから、以降のコースが使う順序で書きます。失敗するテスト、ルート、コントローラー、ページの順です。その後、2 つ目のページをテストで仕様化してエージェントに委ね、ハーネスが編集中のファイルに合った rule を読み込む様子を見届けます。
第 3 章: posts テーブル
ブログには投稿が要り、投稿には置き場所が要ります。この章では最初のテーブルを定義し、そのマイグレーションを生成して適用し、テーブルを読むモデルを書き、投稿を表示する 2 つのページを作ります。その後、作成フォームをテストで仕様化してエージェントに委ね、scaffold スキルがエージェントを手打ちではなくジェネレーターへ向かわせる様子を見ます。
第 4 章: バリデーションとリソース
第 3 章ではスキーマをコントローラーの中に置き、ページには生のフィールドの写しを送っていました。この章では両方にきちんとした置き場所を与えます。ルート、コントローラー、フォームが共有する、人が書くようなメッセージ付きのバリデーターファイル。そして、投稿がブラウザからどう見えるかを決めるリソースクラスです。その後、編集、削除、ページネーションをテストで仕様化してエージェントに委ね、受け入れる前に code-review subagent を第二の読者として使います。
ユーザー
第 5 章: ユーザーとパスワード
ここまではすべて匿名でした。この章でブログにユーザーを与えます。パスワードハッシュを持つテーブル、ハッシュの仕方を知っているモデル、セッションとそれに付いてくる CSRF 保護、そして手で組む登録・ログイン・ログアウトです。その後、プロフィールページをテストで仕様化してエージェントに委ね、モデルに触れる前にエージェントが guren context User から何を得るのかを見ます。
第 6 章: ルートを保護する
ブログにユーザーはできましたが、まだ誰もユーザーを確認していません。ゲストは相変わらず投稿を書き、編集し、削除できますし、guren audit は第 3 章からずっとそう言い続けています。この章では投稿の変更をログインの壁の内側に置き、すでにある行を失わないマイグレーションですべての投稿に著者を与え、それからエージェントにマイグレーションをひとつ任せて db-manage スキルがそれを安全に保つ様子を見ます。最後に、いまなら読めるようになった bunx guren add auth の出力を見ます。
第 7 章: 認可、そしてゲートに見えないもの
第 6 章は壁を作りました。投稿を変えるにはサインインが要ります。扉は作っていません。サインイン済みのユーザーなら誰でも、誰の投稿でも編集・削除できます。その違いが認証(あなたは誰か)と認可(あなたは許されているか)で、この章では後者をポリシーで手で組みます。そして、この章だけが意図的にやることがあります。認可に一言も触れずにエージェントに機能を委ね、それが抜けたときにあなたの安全装置のどれが気づくかを見せます。
データ
第 9 章: リレーションシップ
第 6 章は authorsOf を残しました。著者の id を集めて IN クエリを 1 本走らせるヘルパーです。これは動きますし、リレーションシップが内部でやっていることそのものです。この章ではそれを本物に置き換えます。モデルに一度だけ宣言し、with() で読み込む belongsTo と hasMany です。それからコメントを追加します。ほかの 2 つを指す最初のテーブルです。そして、あなたがまだ作っていない唯一の形をエージェントに渡します。中間テーブルを通した多対多、タグです。
第 10 章: ファイル
ブログには画像が要ります。この章では Guren の attachments レイヤーを導入し、公開ディレクトリの外に保存されて署名付き URL 経由で配信されるカバー画像をすべての投稿に与え、それからギャラリーをエージェントに委ねます。その途中で guren check は正しくあるべき事柄をひとそろい新しく手にし、「プライベート」を「公開」に変えてしまうあの間違いをそれが捕まえるところを、あなたは目にします。
第 11 章: イベントとメール
ここまでの処理はすべてリクエストの中で完結していました。検証し、行を 1 つ書き、リダイレクトする。この章の主題は、そうであってはならない仕事です。Bob が Ada の投稿にコメントすると Ada にメールが届きますが、Bob のブラウザは、ページを目にする前にメールサーバーの応答を待たされてはいけません。