ファイルの規約

sobria は、次のファイルとディレクトリを名前で認識します。Vite プラグインの設定は sobria/vite の API に記述しています。

src/
  routes/          # ページ、レイアウト、API のルート
  elements/        # 要素
  server.ts        # サーバーのエントリー（任意）
.sobria/           # sobria prepare が生成するファイル

要素を TSX のソースのまま配布するライブラリは、package.json に sobria のフィールドを記述し、prefix に接頭辞を、elements に要素のディレクトリを指定します（外部からの利用）。

src/routes/ のファイル

ほかの名前のファイルはルートになりません。ページが使用する部品は、ページと同じディレクトリに配置できます。

page

default export したサーバーコンポーネントを、GET のリクエストで描画します。props は params と url です（PageProps）。prerender を export すると、ビルドの時点で HTML のファイルに書き出します。

layout

ページ、not-found、error は、src/routes/layout.tsx を最も外側にして、そのファイルのディレクトリまでのすべての layout.tsx で包まれます。props は params、url、children です（LayoutProps）。

route

HTTP のメソッド名の関数を export します。

関数の戻り値は、次のようにレスポンスにします。

sobria/server の defineHandler（Hono の defineHandler）で包んだ関数の戻り値には、上の表と異なる Hono の規則を適用します。この規則では、文字列は HTML に、null も 204 になります。

middleware

defineMiddleware で作成したミドルウェアを default export します。

ディレクトリの layout、not-found、error は、そのディレクトリまでのすべての middleware.ts を通過したリクエストでだけ描画します。

not-found と error

• ページで投げた notFound() とエラーには、ページのディレクトリか祖先のディレクトリのうち、最も近いものを使用します
• ミドルウェアが投げた notFound() には、そのミドルウェアのディレクトリの親から祖先に向かって探索し、最も近いものを使用します。src/routes/middleware.ts が投げたときは、Not Found のテキストを 404 で返します
• route.ts が投げた notFound() には、route.ts のディレクトリか祖先のディレクトリのうち、最も近いものを使用します
• フォームの送信先のサーバー関数が失敗したときは、送信したページのディレクトリか祖先のディレクトリのうち、最も近い error を使用します。送信したページの URL に一致するページが無いときは、その URL に使用する not-found のディレクトリか祖先のディレクトリのうち、最も近い error を使用します
• 存在しない URL には、URL の先頭から区切りが一致するディレクトリの not-found のうち、URL の区切りの数で数えて最も深いものを使用します
• どちらも、そのディレクトリまでのすべての layout.tsx で包みます
• not-found が無ければ、Not Found のテキストを返します
• error が無ければ、本番は Internal Server Error のテキストを返し、開発中は Vite のエラーのオーバーレイを表示する HTML を返します

使い方はルーティングに記述しています。

ディレクトリの名前

ディレクトリの名前が、URL の 1 つの区切りになります。

• パラメータの名前には、ASCII の英数字と _ を使用します
• 同じ位置で複数のルートが一致するときは、静的な区切り、動的な区切り、キャッチオールの順に優先します
• グループに配置した layout.tsx と middleware.ts は、そのグループのルートだけに適用します

エラーになる配置

次の配置は、ルートを走査した時点でエラーになります。

• [ か ( で始まり、上の表のどの形でもない名前のディレクトリ
• 同じ URL を扱う 2 つの page か route。グループを経由した場合と、同じディレクトリに page と route を配置した場合を含みます
• 同じ URL を扱い、グループを含めたディレクトリの深さが同じ 2 つの not-found
• キャッチオールのディレクトリの配下のディレクトリにある page、route、not-found
• 同じディレクトリにある、拡張子を除いた名前が同じ 2 つのルートのファイル（page.tsx と page.mdx など）

src/elements/

拡張子が .tsx か .jsx のファイルが default export した関数が、要素になります。ディレクトリは、Vite プラグインの設定 elementsDir で変更できます。

タグ名

タグ名は、接頭辞と、src/elements/ からのファイルのパスから決まります。接頭辞は Vite プラグインの設定 prefix で指定します。

• パスの区切りは - で連結します。camelCase、PascalCase、snake_case の名前は kebab-case にします
• index のファイルのタグ名は、ディレクトリの名前になります
• src/elements/ の直下の index のファイルはビルドのエラーになります
• ファイル名とディレクトリ名に英数字、-、_ 以外の文字を含むと、ビルドのエラーになります
• 2 つのファイルが同じタグ名になると、ビルドのエラーになります。例えば、forms/date-picker.tsx と forms-date-picker.tsx はどちらも sobria-forms-date-picker になります

要素のファイルの export

src/ のそのほかのファイル

src/routes/ と src/elements/ の外のファイルには、サーバー関数、データの取得、共通のコンポーネントを配置します。

• サーバー関数は、src/ の中の、拡張子が .ts、.tsx、.js、.jsx のファイルで定義できます
• 要素は、src/routes/ の中のファイルを import できません。要素から呼び出すサーバー関数は、src/routes/ の外に配置します

src/server.ts

src/server.ts は、サーバーのエントリーです。fetch を持つ値（Hono のアプリなど）を default export します。

src/server.ts が無ければ、sobria/app をサーバーのエントリーにします。sobria/app は、src/routes/ のファイルとサーバー関数から sobria が構築した Hono のアプリを default export します。

開発サーバー、vite build の出力、vite preview は、どれも同じエントリーにリクエストを渡します。書き方は Hono との連携とデプロイに記述しています。

.sobria/

.sobria/ には、型の検査に使用するファイルを生成します。

• 生成するのは、開発サーバーとビルドの開始時と、sobria prepare を実行したときです。開発中は、src/routes/ か要素のディレクトリの中でファイルかディレクトリを追加か削除したときと、tsconfig.base.json を追加か削除したときにも生成します
• 内容が変わったファイルだけを書き込みます
• 生成する tsconfig は、アプリの tsconfig.base.json があれば、それを extends します
• アプリの tsconfig.json には、3 つの tsconfig を references に列挙します
• .sobria/ は git で管理しません

登録した拡張子

Vite プラグインの設定 extensions に、ほかのプラグインが TSX に変換するファイルの拡張子（.mdx など）を登録できます。変換するプラグインは、plugins の配列で sobria より前に配置します。

// vite.config.ts
export default defineConfig({
  plugins: [mdx(), sobria({ extensions: [".mdx"] })],
});

次の拡張子は、sobria() を呼び出した時点でエラーになります。

• .ts、.tsx、.js、.jsx、.mts、.cts、.mjs、.cjs、.json、.css
• . の後に英数字以外の文字を含む拡張子（.page.md など）
• 2 回登録した拡張子