モードの選び方

次のどれかに当てはまるなら、mode: 'server'を選びます。

• フォームの送信をServer Actionで受け取る
• guard.tsで、ページを描画する前にリクエストを止める
• リクエストのヘッダーやCookieを読む、またはcookies()で書く
• ページがsearchをexportして、クエリを受け取る
• 前もって並べられない値のページを、サーバーで描く（利用者が作る記事のIDなど）
• route.tsでGET以外のメソッドに応答する

どれにも当てはまらないなら、mode: 'static'を選びます。ページをビルドの時点で描画しておくので、サーバーなしで静的ホスティングに置けます。記事が増えるなど中身が変わったときは、ビルドし直します。ドキュメントやブログのように、訪問者によって中身が変わらないサイトに向いています。

staticモードでも、前もって並べられない値に答えることはできます。page.tsxの横にfallback.tsxを置くと、ビルドしていない値の本文をブラウザで描きます。最初のHTMLに本文が要らないページなら、staticモードのままで足ります。書き方はパラメータを見てください。

迷ったらmode: 'static'から始めます。あとでリクエストが要るものを書くと、ビルドか型チェックがエラーにします。

• ビルドの出力：staticモードではdist/client/のファイルで、serverモードではリクエストハンドラです。
• パラメータのあるルート：staticモードでは値をpathsで並べます。並べなかった値には、fallback.tsxを置けばブラウザで描くシェルが答えます。serverモードではリクエストと一緒に受け取るので、値が増えてもビルドし直しません。
• どのルートにも当たらないURL：staticモードではホスティングが404.htmlを返し、serverモードではアプリが404のステータスで返します。
• redirect.ts：staticモードでは行き先へ送るページとして書き出し、serverモードでは307か308を返します。
• route.ts：staticモードではGETの応答をファイルに書き、serverモードではexportしたメソッドすべてに応答します。
• Content-Security-Policy：staticモードではcspオプションで<meta>に書きます。serverモードではguard.tsでヘッダーに書きます。
• ページのrequest：staticモードでは型に無く、読むと型エラーになります。型チェックを通さずに読んでも、ビルドがエラーになります。serverモードではヘッダーとCookieを読めます。

import { framework } from '@k8ordo/framework/vite';
import { defineConfig } from 'vite';

export default defineConfig({
  plugins: [framework({ mode: 'server' })],
});

src/routes/のファイルと@k8ordo/frameworkからのimportは、どちらのモードでもそのまま使えます。fallback.tsxもserverモードでは使われないだけなので、消す必要はありません。

pathsとsite、cspは、staticモードだけのオプションです。mode: 'server'と一緒に書くと型エラーになり、設定を読み込んだ時点でもエラーになります。serverモードへ移るときは外します。serverモードのビルドの動かし方はデプロイを見てください。

staticモードへ移るときは、パラメータのあるルートの値をpathsで並べるか、fallback.tsxを置きます。下の拒まれる書き方と、ページのrequestを読むコードも消します。

static build cannot answer a request — a file is written once for every visitor, and these import @k8ordo/framework/server:
  src/lib/session.ts
this application wants mode: 'server'

staticモードのビルドは、リクエストに応答する次のコードをエラーにします。見つけたファイルは、種類ごとにまとめて挙げます。guard.tsとsearch、route.tsのメソッドは、コンパイルの前に調べます。@k8ordo/framework/serverのimportと'use server'は、コンパイルの後に調べます。前の段階のエラーを直すと、次のビルドで後の段階のエラーが出ることがあります。

• @k8ordo/framework/serverから値をimportするモジュール
• 'use server'のモジュール
• guard.ts
• searchをexportするページ
• GET以外のメソッドをexportするroute.ts

どのエラーもthis application wants mode: 'server'の行で終わります。vite devも、そのモジュールをコンパイルした時点で同じエラーにします。import typeはビルドの前に消えるので、エラーになりません。RedirectTargetのような型は、staticモードでも@k8ordo/framework/serverから読めます。import { type RedirectTarget }と書くとエラーになります。verbatimModuleSyntaxの設定では、モジュールを読み込むimportとして残るためです。

ビルドが調べるのはアプリのモジュールだけです。node_modulesの依存が@k8ordo/framework/serverをimportしていても名前は挙がらず、cookies()などを呼んだ時点でエラーになります。export *で別のモジュールをexportするroute.tsとページも、exportの名前を読めないのでエラーになります。