はじめる
このガイドは 2 部構成です。Part A では、Docker もデータベースサーバーも使わず、SQLite で新規 Guren アプリを 5 分程度で動かします。Part B ではフルセットアップを扱います: Postgres / MySQL、環境変数、機能ジェネレーター、本番ビルドなどです。まず Part A から始めて、必要になったら Part B に戻ってきてください。
はじめる
このガイドは 2 部構成です。Part A では、Docker もデータベースサーバーも使わず、SQLite で新規 Guren アプリを 5 分程度で動かします。Part B ではフルセットアップを扱います: Postgres / MySQL、環境変数、機能ジェネレーター、本番ビルドなどです。まず Part A から始めて、必要になったら Part B に戻ってきてください。
手順は macOS と Linux を対象としていますが、Windows でも WSL2 を使えば同じように動きます。
Note
見慣れない用語があれば 用語集 を参照してください。
Part A: クイックスタート（SQLite — Docker 不要）
前提条件
- Bun 1.1 以降 — これだけです。
curl -fsSL https://bun.sh/install | bash
1. プロジェクトを雛形生成する
bunx create-guren-app my-app
cd my-app
スキャフォールダーは 2 つの質問をします。始めるだけならデフォルトのままで問題ありません。
- レンダリングモード: SSR（デフォルト）または SPA。SSR ではサーバーレンダリングされた HTML と Vite アセットの自動検出が使えます。
- データベース: SQLite（デフォルト、設定不要）、PostgreSQL、または MySQL。
その後、依存関係をインストールし、生成済みの APP_KEY 入りの .env ファイルを作成してくれます。プロンプトをスキップしたい場合はフラグを渡します: --mode ssr、--db sqlite、認証の雛形を最初から含めるなら --auth です。
2. 開発サーバーを起動する
bun run dev
型付きのルート／ページマニフェストを再生成（codegen）してからサーバーを起動します。http://localhost:3333 を開いてください。
3. 何が表示されるか
ターミナルには Guren のバージョンと URL を添えた深紅の ASCII バナーが、ブラウザにはウェルカムページが表示されます。SQLite のデータベースファイルは必要になった時点で ./data/guren.db に作成されます。新規アプリにはまだテーブル定義がないため、初回起動前にマイグレーションを実行する必要はありません。
Tip
バックエンドの変更は Bun 経由でホットリロードされ、開発サーバーはフロントエンドアセット用に Vite を自動起動します。Vite を自分で起動したい場合は GUREN_DEV_VITE=0 を、スクリプト実行時にバナーを消したい場合は GUREN_DEV_BANNER=0 を設定してください。
最初の機能を追加する
アプリが動いたら、次は何かを作ってみましょう。おすすめの次のステップは ミニブログを作るチュートリアル です。今作ったアプリに、投稿の CRUD、認証、リレーションシップを使ったコメント機能を追加していく 3 部構成のコースです。
Part B: フルセットアップ
以下はすべて初回セッションでは省略可能ですが、アプリが成長するにつれて必要になるものです。
PostgreSQL または MySQL を使う
雛形生成時に --db postgres（または --db mysql）を渡すか、プロンプトで選択します。スキャフォールダーが対応するデータベースの docker-compose.yml を書き出し、DATABASE_URL をそこに向けてくれます。Docker Desktop（Compose v2） がインストールされていれば、次のコマンドでデータベースを起動できます。
docker compose up -d
デフォルトの接続文字列:
- PostgreSQL:
postgres://guren:guren@localhost:54322/guren - MySQL:
mysql://guren:guren@localhost:33306/guren
使い終わったら docker compose down でコンテナを停止します。
Tip
すでにローカルやクラウドで Postgres が動いていますか？ その場合は Docker を使わず、DATABASE_URL をそのインスタンスに向けるだけで構いません — このガイドの残りはそのまま通用します。SQLite で作ったアプリも、あとから config/database.ts を更新すれば切り替えられます。詳しくは データベースガイド を参照してください。
環境変数
スキャフォールダーは .env.example から .env を作成し、新しい APP_KEY を書き込みます。主な設定:
APP_URL: Inertia に伝えるベース URL（デフォルトhttp://localhost:3333）。DATABASE_URL: 接続文字列 — SQLite ではファイルパス、Postgres / MySQL では URL。PORT: 開発サーバーの HTTP ポート（デフォルト3333）。SESSION_DRIVER、CACHE_STORE、QUEUE_CONNECTION: デフォルトはインメモリ／同期実行。マルチプロセスでデプロイする場合はredisに切り替えます。
Caution
.env はバージョン管理に含めないでください。もしコミットに認証情報が漏れてしまった場合は、データベースユーザーをローテーションし、ファイル内で参照している API キーをすべて再生成してください。
認証とリソースを追加する
Guren には機能一式を雛形生成するジェネレーターが同梱されています。
bunx guren add auth
bunx guren add resource posts --fields "title:string,body:text,published:boolean"
add auth はユーザー登録、ログイン、ログアウト、セッションミドルウェアをセットアップします。add resource は指定したフィールドに基づいて、モデル、マイグレーション、コントローラー、バリデーター、リソース、Inertia ページを生成します。ほかのジェネレーター（キュー、メール、イベント、ストレージなど）は bunx guren add --help で確認できます。
型付きマニフェストを生成する
bun run codegen
codegen は、エンドツーエンドの型安全を支える型付きルートヘルパーとページマニフェストを書き出します。bun run dev と bun run build が自動で実行するため、手動で実行する必要があるのは、サーバー停止中にルートやページを追加・リネームした場合だけです。
マイグレーションとシードデータの投入
リソースを追加した（＝マイグレーションが生成された）ら、スキーマを適用してサンプルデータを投入します。
bun run db:migrate && bun run db:seed
これは SQLite、Postgres、MySQL のいずれでも同じように動きます。マイグレーションは db/schema.ts の Drizzle スキーマから生成されます。
型チェックとテスト
bun run typecheck
型エラーは出たそばから修正しましょう — 問題を早期に捕まえるほうが、動いているアプリをデバッグするよりずっと簡単です。テストを追加したら（テストガイド 参照）、bun test で実行します。
本番ビルド
リリースの準備ができたら:
bun run build
bun run preview
build はハッシュ付きのクライアントアセット（SSR モードではサーバーアセットも）を public/assets/ 以下に出力し、ランタイムが読み込むマニフェストも生成します。preview は本番サーバーをローカルで起動するので、ビルドの動作確認ができます。ホスティングの選択肢は デプロイガイド を参照してください。
次のステップ
- ミニブログを作るチュートリアル — 初めての方におすすめのハンズオンコース。投稿の CRUD、認証、そしてコメントとリレーションシップを扱います。
- ファーストステップ — 1 つのリクエストがフレームワークをどう流れるかを辿る 10 分のツアー。
その後は、次の順番でガイドを読み進めてください。
道中では CLI リファレンス を手元に置いておくと便利です。問題を見つけたりアイデアがあれば、ぜひ Issue や PR を送ってください — コントリビューションを歓迎します。