@k8ordo/server

設定とファイル

framework()のオプションと、src/routes/に置けるファイル、@k8ordo/serverの各入口からimportできるものの一覧です。それぞれの使い方は、ガイドの各ページで説明しています。

このページの内容

4つの入口

@k8ordo/serverは、コードが動く場所ごとに入口を分けています。デプロイしたアプリが読み込むのはruntimeとserveだけで、どちらもViteを読み込みません。

  • @k8ordo/server：vite.config.tsで使うプラグインのframework()です。Viteを読み込みます。
  • @k8ordo/server/runtime：ハンドラの中で動くコードがimportするものです。Node.jsにしか無いものを使わないので、ハンドラと一緒にどのランタイムでも動きます。
  • @k8ordo/server/serve：ビルドをNode.jsで動かすserve()です。
  • @k8ordo/server/vercel：Vercel向けの出力を書くプラグインのvercel()です。

framework

import元 @k8ordo/server

アプリをサーバーで動かすViteのプラグインです。ReactのプラグインとRSCのパイプラインを含んだ配列を返すので、pluginsにそのまま渡します。

ts
framework(options?: ServerOptions): PluginOption[]

引数

options.routesDirstring
ルートのディレクトリです。プロジェクトのルートからの相対パスで、既定はsrc/routesです。変えても、生成されるファイルは.k8ordo/に書かれます。

戻り値

PluginOption[] — Viteのプラグインの配列。

vite.config.ts
import { framework } from '@k8ordo/server';
import { defineConfig } from 'vite';

export default defineConfig({ plugins: [framework()] });

ルートのファイル

src/routes/のディレクトリに置けるファイルと、それぞれがexportするもの、受け取るものです。これ以外の名前のファイルは、_で始まるディレクトリに置きます。

page.tsx

  • default export：そのディレクトリのURLに答えるページのコンポーネントです。paramsとpathnameを受け取ります。
  • このモードでは、requestも受け取ります。リクエストのヘッダーとCookieが入っています。
  • paramsSchema：パラメータを検証するスキーマです。Standard Schemaを実装したものを渡します。省略できます。
  • search：読むurlスキーマです。宣言したページは、そのスロットをsearchとして受け取ります。

layout.tsx

  • default export：その下で描かれるものをchildrenで受け取って包むコンポーネントです。paramsとpathnameも受け取りますが、paramsは文字列として型が付きます。
  • このモードでは、requestも受け取ります。リクエストのヘッダーとCookieが入っています。
  • paramsSchema：その下のすべてのページで、ページ自身のスキーマより先に走ります。

not-found.tsx

  • default export：その下で、どのルートにも当たらなかったURLに答えるコンポーネントです。paramsとpathnameを受け取り、paramsの値は検証されていない文字列です。
  • このモードでは、requestも受け取ります。リクエストのヘッダーとCookieが入っています。
  • このモードでは404のステータスで答えます。ディレクトリごとに置けます。

error.tsx

  • 'use client'のファイルにします。
  • default export：errorとresetを受け取るコンポーネントです。その下で例外が投げられたとき、代わりに描かれます。paramsは受け取りません。

loading.tsx

  • default export：propsを受け取らないコンポーネントです。その下のページを待つ間、<Suspense>のfallbackとして描かれます。

redirect.ts

  • default export：行き先の文字列か、{ to, permanent }です。toはルート表のパターンで書き、パラメータは当たった値で埋まります。
  • このモードでは、GETとHEADに307で答え、permanentなら308で答えます。

route.ts

  • GETやPOSTなどのメソッド名のexport：{ request, params }を受け取り、Responseを返す関数です。
  • paramsSchema：ページと同じく、パラメータを検証します。
  • このモードでは7つのメソッドのどれもexportできます。HEADが無ければ、GETの答えから本文を外して返します。

guard.ts

  • default export：{ request, params }を受け取る関数です。Responseを返すとそこで打ち切り、何も返さなければ通します。その下のURLに答える前に走ります。

@k8ordo/routerから使うもの

ルートのファイルが使う型と関数は、モードのパッケージではなく@k8ordo/routerから来ます。そのためページは、どちらのモードでも同じに書けます。

  • PageProps<pattern>：ページが受け取るpropsの型です。
  • LayoutProps<pattern>：レイアウトが受け取るpropsの型です。
  • ErrorProps：error.tsxが受け取るpropsの型です。
  • RouteContext<pattern>：route.tsの関数が受け取る値の型です。
  • notFound()：ページから投げると、いちばん近いnot-found.tsxが404として答えます。
  • href()：ルート表に対して型の付いたURLを作ります。
  • usePathname()とuseMatch()：ブラウザで今のURLを読むフックです。
  • usePendingPathname()：遷移している途中の行き先を読むフックです。

cookies

import元 @k8ordo/server/runtime

リクエストのCookieを読み書きします。guard.ts、route.ts、Server Actionの中で呼びます。

ts
cookies(): Cookies

フィールド

get(name: string) => string | undefined
名前で値を読みます。無ければundefinedです。
has(name: string) => boolean
その名前のCookieがあるかどうかを返します。
set(name: string, value: string, options?: CookieOptions) => void
値を書きます。3つ目の引数で、CookieOptionsの属性を渡します。
delete(name: string, scope?: { path?: string; domain?: string }) => void
Cookieを消します。書いたときと同じpathとdomainを渡します。

注意

  • 読むと、リクエストが運んできたCookieに、同じリクエストの中で先に書いたものが重なって見えます。
  • 書いたものは、答えが何であっても、その答えのSet-Cookieとしてブラウザに届きます。
  • ページの描画の中で呼ぶと、例外を投げます。ページはrequest.cookiesを読みます。
ts
cookies().get('session');
cookies().set('session', token, { maxAge: 60 * 60 * 24 });
cookies().delete('session');

CookieOptions

import元 @k8ordo/server/runtime

cookies().set()の3つ目の引数で渡す、Cookieの属性です。何も渡さなければ、セッションに合った値になります。

ts
type CookieOptions = {
  path?: string;
  domain?: string;
  maxAge?: number;
  expires?: Date;
  httpOnly?: boolean;
  secure?: boolean;
  sameSite?: 'strict' | 'lax' | 'none';
};

フィールド

pathstring
既定は/です。
domainstring
既定では付けません。
maxAgenumber
有効期間を秒で渡します。0を渡すと、すぐに切れます。
expiresDate
期限をDateで渡します。
httpOnlyboolean
既定はtrueで、ページのスクリプトからは読めません。
secureboolean
既定はtrueで、HTTPSでしか送られません。この機械（localhostなど）に素のHTTPで届いたリクエストでは、既定がfalseになります。
sameSite'strict' | 'lax' | 'none'
既定は'lax'です。'none'はsecureのときだけ使えます。

responseHeaders

import元 @k8ordo/server/runtime

最終的な応答が持つHeadersを返します。ここに書いたヘッダーは、ページでもペイロードでも、guardが返したResponseでも、答えに付きます。

ts
responseHeaders(): Headers

注意

  • 答えがすでに持っているヘッダーは置き換えます。
  • guard.ts、route.ts、Server Actionの外で呼ぶと、例外を投げます。

requestHeaders

import元 @k8ordo/server/runtime

リクエストが運んできたヘッダーを返します。引数しか受け取らないServer Actionの中で、ヘッダーを読むのに使います。

ts
requestHeaders(): Headers

注意

  • guard.ts、route.ts、Server Actionの外で呼ぶと、例外を投げます。

redirect

import元 @k8ordo/server/runtime

Server Actionを終え、訪問者を別のURLへ送ります。

ts
redirect(to: string): never

引数

tostring
行き先のURLです。書いたまま送られるので、href()で作ります。

戻り値

never — 値を返さず、例外を投げます。

注意

  • 例外を投げて終わるので、tryの中では呼びません。
  • JavaScriptが届く前に送られたフォームには303で、クライアントのランタイムからの呼び出しには、行き先へ移るよう伝えるペイロードで答えます。

nonce

import元 @k8ordo/server/runtime

この答えのインラインスクリプトに付けるnonceを返します。リクエストごとに新しい値です。

ts
nonce(): string

注意

  • リクエストに答えている間なら、描画の中でも同じ値を返します。
  • リクエストの外で呼ぶと、例外を投げます。

Guard

import元 @k8ordo/server/runtime

guard.tsがdefault exportする関数の型です。そのディレクトリのパターンを型引数に渡します。

ts
type Guard<P extends string = string> = (context: {
  request: Request;
  params: ParamsOf<P>;
}) => Response | void | Promise<Response | void>;

フィールド

requestRequest
届いたままのRequestです。
paramsParamsOf<P>
そのディレクトリのパターンのパラメータです。guardはスキーマより前に走るので、URLの文字列のままです。

RouteRequest

import元 @k8ordo/server/runtime

ページとレイアウト、not-found.tsxが受け取るrequestの型です。どちらのフィールドも読むだけです。

ts
type RouteRequest = {
  headers: Headers;
  cookies: ReadonlyMap<string, string>;
};

フィールド

headersHeaders
リクエストのヘッダーです。
cookiesReadonlyMap<string, string>
Cookieヘッダーを名前ごとに読み取ったものです。同じ名前が2回あれば、最初のものを使います。

RedirectTarget

import元 @k8ordo/server/runtime

redirect.tsがdefault exportする値の型です。satisfies RedirectTargetと書くと、書いたその場で形を検査できます。

ts
type RedirectTarget =
  | string
  | { to: string; permanent?: boolean };

serve

import元 @k8ordo/server/serve

ビルドをNode.jsのHTTPサーバーで動かします。待ち受けを始めてから、待ち受けている場所と止め方を返します。

ts
serve(options?: ServeOptions): Promise<Server>

引数

options.diststring
ビルドの出力ディレクトリです。既定はdistで、今の作業ディレクトリから解決します。
options.portnumber
待ち受けるポートです。既定は3000で、0を渡すと空いているポートをシステムが選びます。
options.hoststring
待ち受けるホストです。既定のlocalhostには同じマシンからしか届かないので、コンテナの中などでは0.0.0.0を渡します。

戻り値

Promise<Server> — 待ち受けを始めたサーバー。

フィールド

portnumber
実際に待ち受けているポートです。
urlstring
http://<host>:<port>の形のURLです。
close() => Promise<void>
サーバーを止めます。止まると解決するPromiseを返します。

注意

  • GETとHEADのうち、dist/client/の中のファイルを指すものにはそのファイルを返し、それ以外はハンドラに渡します。
  • ハンドラが例外を投げたときは、500と本文internal errorだけを返し、内容はサーバーのログに出します。
serve.js
import { serve } from '@k8ordo/server/serve';

const server = await serve({ port: 3000 });
console.log(server.url);

vercel

import元 @k8ordo/server/vercel

vite buildに、VercelのBuild Output API（v3）の形で.vercel/output/も書かせるプラグインです。framework()の隣に置きます。

ts
vercel(): Plugin

戻り値

Plugin — Viteのプラグイン。

注意

  • ハンドラをすべての依存ごとバンドルします。そのため、ネイティブのバイナリを持つ依存や、自分のファイルをパスで読む依存は動きません。
vite.config.ts
import { framework } from '@k8ordo/server';
import { vercel } from '@k8ordo/server/vercel';
import { defineConfig } from 'vite';

export default defineConfig({ plugins: [framework(), vercel()] });
k8ordo

Baselineに入った機能を、制限なく使うReactのライブラリ群。

© 2026 k8o — MIT License

組版：Noto Sans JP / M PLUS 2

@k8ordo/server