API

@k8ordo/routerが書き出す関数とコンポーネント、型の一覧です。使う場面の近いものを隣に並べ、型は最後にまとめています。

このページの内容

defineRoutes

import元 @k8ordo/router

ルート表を作ります。キーがパスのパターンで、値はページのコンポーネントか、ページをまとめるオブジェクトです。

コードをコピー

defineRoutes<R extends RoutesRecord>(record: R): Routes<R>

引数

recordRoutesRecord: ルート表そのもの。キーは/で始まるパターンです。

戻り値

Routes<R> — 渡した表と、パスを照合するmatchを持つオブジェクト。

注意

表は呼んだ時点で検査され、書き方の誤りはTypeErrorになります。
照合は書いた順に行い、最初に合ったパターンを選びます。

routes.ts

コードをコピー

export const routes = defineRoutes({
  '/': Home,
  '/products': {
    layout: ProductsLayout,
    children: { '/': ProductList, '/:id': ProductPage },
  },
  '/*': NotFound,
});

Router

import元 @k8ordo/router

ルート表をブラウザのナビゲーションにつなぎ、いまのパスに合ったページを描きます。ブラウザの中で描くアプリの根に、1度だけ置きます。

コードをコピー

<Router routes={Routes} />

引数

routesRoutes: defineRoutesが返したルート表。

注意

ルート表が答えるパスへのナビゲーションだけを引き受け、それ以外はブラウザに任せます。
表に無いパスで開かれたときは、何も描きません。
マウントした時点でブラウザのURLを読むので、サーバーでは描けません。

Outlet

import元 @k8ordo/router

レイアウトの中で、そのレイアウトが包むページを描く位置を決めます。

コードをコピー

<Outlet />

注意

<Router>の外で描くと例外を投げます。フレームワークの下では、レイアウトはchildrenを描きます。

href

import元 @k8ordo/router

パターンとparamから、リンク先のURLを作ります。

コードをコピー

href<P extends RegisteredNavigablePattern>(
  pattern: P,
  params?: RegisteredParams<P>,
): string

引数

patternP: リンク先のパターン。Registerに登録していれば、表にあるリンク先にできるパターンに限られます。
paramsRegisteredParams: パターンのparamの値。paramの無いパターンでは渡しません。

戻り値

string — <a>のhref属性に渡すURL。サブパスの下で配信しているときは、その分も前に付きます。

注意

値はencodeURIComponentで符号化されます。
/*を含むパターンや値の無いparam、URLでの書き方が無い値は、実行時にTypeErrorになります。

コードをコピー

href('/products'); // '/products'
href('/products/:id', { id: 42 }); // '/products/42'

navigateTo

import元 @k8ordo/router

パターンとparamからURLを作り、そのページへ移ります。

コードをコピー

navigateTo<P extends RegisteredNavigablePattern>(
  pattern: P,
  params?: RegisteredParams<P>,
  options?: NavigateToOptions,
): NavigationResult

引数

patternP: リンク先のパターン。Registerに登録していれば、表にあるリンク先にできるパターンに限られます。
paramsRegisteredParams: パターンのparamの値。paramの無いパターンでは渡しません。
optionsNavigateToOptions: ナビゲーションのオプション。paramの無いパターンでは2つ目の引数になります。

戻り値

NavigationResult — ブラウザのnavigation.navigate()が返す{ committed, finished }。finishedは、新しいページが画面に出たときに解決します。

注意

既定では、履歴に新しいエントリを積みます。
別のナビゲーションに追い越されると、finishedはAbortErrorでrejectします。

コードをコピー

await navigateTo('/products/:id', { id: '42' }).finished;
navigateTo('/products', { history: 'replace' });

bindParams

import元 @k8ordo/router

いくつかのparamを関数から補う、hrefとnavigateToを作ります。ロケールのように、すべてのリンクに共通のparamに使います。

コードをコピー

bindParams<const Bound extends BoundParams>(
  source: () => Bound,
): BoundLinks<Bound>

引数

source() => Bound: 束ねるparamを返す関数。hrefやnavigateToが呼ばれるたびに呼ばれます。

戻り値

BoundLinks<Bound> — sourceの値を補うhrefとnavigateTo。

注意

束ねたparamは省けますが、渡せば上書きできます。
パターンにparamがあれば、オプションはいつも3つ目の引数です。すべてを束ねたときは、2つ目にundefinedを渡します。

usePathname

import元 @k8ordo/router

ブラウザがいま開いているパスを返します。

コードをコピー

usePathname(): string

戻り値

string — いまのパス。サブパスと末尾のスラッシュを外した形です。

注意

パスが変わったときだけ再描画され、クエリ文字列が変わっても再描画されません。
URLが書き換わった時点で変わり、新しいページが画面に出るのは待ちません。
サーバーでの描画とハイドレーションでは、<Router>かフレームワークが描くページの中でなければ例外を投げます。

useMatch

import元 @k8ordo/router

いまのパスがパターンに合うかを調べます。

コードをコピー

useMatch<P extends MatchablePattern>(
  pattern: P,
  options?: MatchOptions,
): ParamsOf<P> | null

引数

patternP: 表のパターンか、その後ろに/*を付けたもの。/*は「そのパターンより下のどこか」を表します。
optionsMatchOptions: inclusiveをtrueにすると、/*のパターンがそのパターン自身のページにも合います。

戻り値

ParamsOf | null — 合えばそのparams、合わなければnull。

注意

usePathnameの上に作られていて、パスが変わったときだけ再描画されます。
ルート表を使わないので、フレームワークの下でも使えます。

matchPath

import元 @k8ordo/router

useMatchと同じ判定を、渡したパスに対して行います。

コードをコピー

matchPath<P extends MatchablePattern>(
  pattern: P,
  pathname: string,
  options?: MatchOptions,
): ParamsOf<P> | null

引数

patternP: 表のパターンか、その後ろに/*を付けたもの。/*は「そのパターンより下のどこか」を表します。
pathnamestring: 調べるパス。比べる前に末尾のスラッシュを落とします。
optionsMatchOptions: inclusiveをtrueにすると、/*のパターンがそのパターン自身のページにも合います。

戻り値

ParamsOf | null — 合えばそのparams、合わなければnull。

コードをコピー

matchPath('/products/:id', '/products/42'); // { id: '42' }
matchPath('/products/*', '/products'); // null
matchPath('/products/*', '/products', { inclusive: true }); // {}

usePendingPathname

import元 @k8ordo/router

読み込み中のページのパスを返します。

コードをコピー

usePendingPathname(): string | null

戻り値

string | null — 読み込み中のページのパス。何も読み込んでいなければnull。

注意

ナビゲーションが始まった時点で値が入り、新しいページが画面に出たとき、中断されたとき、読み込みに失敗したときにnullに戻ります。
クエリ文字列だけを変える状態の更新では、値が入りません。
サーバーでの描画ではnullです。

useParams

import元 @k8ordo/router

ページのparamを、パターンから決まる型で読みます。

コードをコピー

useParams<P extends RegisteredPattern>(pattern: P): ParamsOf<P>

引数

patternP: このコンポーネントが描かれるページのパターン。

戻り値

ParamsOf — パターンから型の決まったparams。値はいつも文字列です。

注意

別のパターンのページの中で描かれると、例外を投げます。
<Router>の下でだけ使えます。フレームワークの下では使えません。

useRoute

import元 @k8ordo/router

いま選ばれているパターンとparamsを、型の無い形で返します。

コードをコピー

useRoute(): {
  pattern: string;
  params: Readonly<Record<string, string>>;
}

戻り値

Pick<Match, 'pattern' | 'params'> — 選ばれたパターンと、そのparams。

注意

<Router>の外や、合ったページが無いところでは例外を投げます。

normalizePathname

import元 @k8ordo/router

ルーターと同じ規則でパスを整えます。末尾のスラッシュを落とし、/だけは残します。

コードをコピー

normalizePathname(pathname: string): string

引数

pathnamestring: 整えるパス。

注意

落とすのは末尾のスラッシュだけです。途中のスラッシュの重なりや、パーセントエンコードには触れません。

コードをコピー

normalizePathname('/products/'); // '/products'
normalizePathname('/'); // '/'

withBase

import元 @k8ordo/router

表のパスの前に、アプリを配信しているサブパスを付けます。

コードをコピー

withBase(pathname: string, base?: string): string

引数

pathnamestring: 表の書き方のパス。
basestring: サブパス。省くとimport.meta.env.BASE_URLを読みます。Viteを通らないコードでは渡します。

戻り値

string — サブパスの付いたパス。

注意

./のような相対のサブパスでは、何も付け外ししません。

withoutBase

import元 @k8ordo/router

URLのパスから、アプリを配信しているサブパスを外します。

コードをコピー

withoutBase(pathname: string, base?: string): string | null

引数

pathnamestring: URLのパス。
basestring: サブパス。省くとimport.meta.env.BASE_URLを読みます。Viteを通らないコードでは渡します。

戻り値

string | null — サブパスを外したパス。サブパスの外のパスにはnull。

注意

./のような相対のサブパスでは、何も付け外ししません。

コードをコピー

withBase('/products', '/docs/'); // '/docs/products'
withoutBase('/docs/products', '/docs/'); // '/products'
withoutBase('/elsewhere', '/docs/'); // null

notFound

import元 @k8ordo/router

フレームワークのページから、そのパスにページが無いことを伝えます。

コードをコピー

notFound(): never

注意

例外を投げるので、後ろの行は走りません。
@k8ordo/staticと@k8ordo/serverでは、いちばん近いnot-found.tsxが404で答えます。
<Router>の下では、ほかの例外と同じ扱いです。

isNotFound

import元 @k8ordo/router

投げられた値が、notFound()の投げたものかを調べます。

コードをコピー

isNotFound(value: unknown): boolean

引数

valueunknown: 調べる値。

注意

クラスではなくSymbol.forの印で見分けるので、このパッケージが2つ読み込まれていても判定できます。

PathnameProvider

import元 @k8ordo/router

サーバーでの描画とハイドレーションの間に、usePathnameが返すパスを渡します。

コードをコピー

<PathnameProvider pathname={string}>{children}</PathnameProvider>

引数

pathnamestring: この描画のパス。

注意

<Router>とフレームワークのランタイムが自分で置きます。アプリが書くのは、useInterceptedNavigationで自分の仕組みを作るときだけです。

import元 @k8ordo/router

新しいページが画面に出たことを、ルート表のerrorに伝えるコンテキストです。

コードをコピー

<NavigationGeneration value={number}>
  {children}
</NavigationGeneration>

引数

valuenumber: useInterceptedNavigationが返すgeneration。

注意

<Router>とフレームワークのランタイムが自分で置きます。

import元 @k8ordo/router

<Router>のナビゲーションの部分を、単独で使うためのフックです。引き受けたナビゲーションを読み込んで反映し、新しいページが画面に出てから終えます。

コードをコピー

useInterceptedNavigation<T>(
  handler: NavigationHandler<T>,
): { readonly generation: number }

引数

handlerNavigationHandler<T>: 引き受けるかどうか、何を読み込むか、どう反映するかを決める関数の組。

戻り値

{ readonly generation: number } — 新しいページが画面に出るたびに変わるgeneration。

注意

applyで入れた値は、同じコンポーネントの中でuseDeferredValueを通して描きます。
handlerはイベントの時点で読むので、描画のたびに作り直してもかまいません。

Routes

import元 @k8ordo/router

defineRoutesが返すルート表の型です。

コードをコピー

type Routes<R extends RoutesRecord = RoutesRecord> = {
  kind: 'routes';
  record: R;
  match: (
    pathname: string,
    accept?: (match: Match) => boolean,
  ) => Match | null;
};

フィールド

kind'routes': いつもroutes。
recordR: defineRoutesに渡した表。
match(pathname, accept?) => Match | null: パスを照合し、合ったMatchかnullを返します。acceptがfalseを返すと、その結果を見送って次のパターンへ進みます。

RoutesRecord

import元 @k8ordo/router

ルート表そのものの型です。キーは/で始まるパターン、値はRouteNodeです。

コードをコピー

type RoutesRecord = Record<`/${string}`, RouteNode>;

RouteNode

import元 @k8ordo/router

ルート表の値の型です。ページのコンポーネントか、childrenを持つオブジェクトです。

コードをコピー

type RouteNode =
  | RouteComponent
  | {
      layout?: RouteComponent;
      error?: ErrorComponent;
      loading?: ComponentType;
      children: RoutesRecord;
    };

フィールド

layoutRouteComponent: 下のページを包むレイアウト。
errorErrorComponent: 下のページが例外を投げたときに、ページの代わりに描くコンポーネント。
loadingComponentType: 下のページがサスペンドしている間に出すコンポーネント。propsは受け取りません。
childrenRoutesRecord: 下のページの表。キーは親のパターンに続けて読みます。

RouteComponent

import元 @k8ordo/router

ページとレイアウトの型です。どんなpropsを宣言したコンポーネントでも入ります。

コードをコピー

type RouteComponent = ComponentType<never>;

注意

<Router>はpropsを渡さず、フレームワークはparamsなどを渡します。同じ表をどちらでも描けるように、ComponentType<never>にしています。

Match

import元 @k8ordo/router

matchが返す、照合の結果の型です。

コードをコピー

type Match = {
  pattern: string;
  params: Readonly<Record<string, string>>;
  stack: readonly RouteComponent[];
};

フィールド

patternstring: 選ばれたパターン。表に書いたとおりの綴りです。
paramsReadonly<Record<string, string>>: デコードしたparamの値。
stackreadonly RouteComponent[]: 描くコンポーネントの並び。外側のレイアウトから順に、ページが最後です。

ErrorProps

import元 @k8ordo/router

ルート表のerrorのコンポーネントが受け取るpropsの型です。

コードをコピー

type ErrorProps = {
  readonly error: unknown;
  readonly reset: () => void;
};

フィールド

errorunknown: 投げられた値。
reset() => void: その場で下のページをもう一度描きます。

ErrorComponent

import元 @k8ordo/router

ルート表のerrorに書くコンポーネントの型です。

コードをコピー

type ErrorComponent = ComponentType<ErrorProps>;

NavigateToOptions

import元 @k8ordo/router

navigateToのオプションの型です。

コードをコピー

type NavigateToOptions = {
  history?: 'push' | 'replace';
};

フィールド

history'push' | 'replace': 'push'なら新しいエントリを積み、'replace'ならいまのエントリを置き換えます。既定は'push'です。

MatchOptions

import元 @k8ordo/router

useMatchとmatchPathのオプションの型です。

コードをコピー

type MatchOptions = {
  readonly inclusive?: boolean;
};

フィールド

inclusiveboolean: /*のパターンを、そのパターン自身のページにも合わせます。/*で終わらないパターンには影響しません。

MatchablePattern

import元 @k8ordo/router

useMatchとmatchPathが受け取るパターンの型です。表のパターンか、リンク先にできるパターンの後ろに/*を付けたものです。

コードをコピー

type MatchablePattern =
  | RegisteredPattern
  | `${RegisteredNavigablePattern}/*`;

BoundParams

import元 @k8ordo/router

bindParamsに渡す関数が返す値の型です。URLでの書き方が1通りに決まる値を、paramの名前ごとに持ちます。

コードをコピー

type BoundParams = Readonly<Record<string, ParamValue>>;

BoundLinks

import元 @k8ordo/router

bindParamsが返すオブジェクトの型です。

コードをコピー

type BoundLinks<Bound extends BoundParams> = {
  readonly href: (pattern, params?) => string;
  readonly navigateTo: (
    pattern,
    params?,
    options?: NavigateToOptions,
  ) => NavigationResult;
};

フィールド

href(pattern, params?) => string: 束ねたparamを補うhref。
navigateTo(pattern, params?, options?) => NavigationResult: 束ねたparamを補うnavigateTo。

import元 @k8ordo/router

useInterceptedNavigationに渡す関数の組の型です。

コードをコピー

type NavigationHandler<T> = {
  claim: (url: URL) => boolean;
  load: (url: URL, signal: AbortSignal) => T | Promise<T>;
  apply: (value: T) => void;
  refresh?: (url: URL) => boolean;
};

フィールド

claim(url: URL) => boolean: このナビゲーションを引き受けるかどうか。イベントの間に同期的に答えます。
load(url: URL, signal: AbortSignal) => T | Promise<T>: そのURLで描くものを作ります。追い越されるとsignalが中断されます。
apply(value: T) => void: 作ったものを、transitionの外でふつうの更新として反映します。
refresh(url: URL) => boolean: パスが変わらないナビゲーションでも、読み込み直すかどうか。省くと読み込み直しません。

Register

import元 @k8ordo/router

ルート表を型に登録するためのインターフェースです。declare moduleでroutesを足すと、パターンが表と照らし合わされます。

コードをコピー

declare module '@k8ordo/router' {
  interface Register {
    routes: typeof routes;
  }
}

注意

登録はアプリの中で1度だけ行います。
@k8ordo/staticと@k8ordo/serverでは.k8ordo/register.gen.tsに生成され、paramsとsearch、@k8ordo/serverではrequestも加わります。

RegisteredPattern

import元 @k8ordo/router

登録した表のすべてのページのパターンです。/*のパターンも含みます。登録の前は、/で始まる任意の文字列です。

コードをコピー

type RegisteredPattern = Register extends {
  routes: Routes<infer R>;
}
  ? PatternOf<R>
  : `/${string}`;

RegisteredNavigablePattern

import元 @k8ordo/router

登録した表のうち、リンク先にできるパターンです。/*を含むものを除きます。登録の前は、/で始まる任意の文字列です。

コードをコピー

type RegisteredNavigablePattern = Register extends {
  routes: Routes<infer R>;
}
  ? NavigablePatternOf<R>
  : `/${string}`;

RegisteredParams

import元 @k8ordo/router

パターンPへのリンクが受け取るparamsの型です。スキーマが型を決めたparamはその型で、ほかはParamValueか文字列です。

コードをコピー

type RegisteredParams<P extends string>

RegisteredPageParams

import元 @k8ordo/router

パターンPのページが受け取るparamsの型です。スキーマを走らせたところはその出力で、ほかは文字列です。

コードをコピー

type RegisteredPageParams<P extends string>

PageProps

import元 @k8ordo/router

フレームワークのページが受け取るpropsの型です。型引数には、ページのディレクトリが表すパターンを渡します。

コードをコピー

type PageProps<P extends RegisteredPattern> = {
  readonly params: RegisteredPageParams<P>;
  readonly pathname: string;
} & RequestProps &
  SearchProps<P>;

フィールド

paramsRegisteredPageParams: スキーマが作った型のparams。
pathnamestring: この描画のパス。
requestRequest: リクエスト。@k8ordo/serverでだけ加わります。
searchunknown: searchをexportしたページが読み取った値。そのページにだけ加わります。

LayoutProps

import元 @k8ordo/router

フレームワークのレイアウトが受け取るpropsの型です。型引数には、ページのあるパターンだけを渡せます。

コードをコピー

type LayoutProps<P extends RegisteredPattern> = {
  readonly params: ParamsOf<P>;
  readonly pathname: string;
  readonly children: ReactNode;
} & RequestProps;

フィールド

paramsParamsOf: params。スキーマを書いていても、型は文字列です。
pathnamestring: この描画のパス。
childrenReactNode: レイアウトが包むページ。
requestRequest: リクエスト。@k8ordo/serverでだけ加わります。

RouteContext

import元 @k8ordo/router

フレームワークのroute.tsがexportする関数の引数の型です。

コードをコピー

type RouteContext<P extends RegisteredPattern> = {
  readonly request: Request;
  readonly params: RegisteredPageParams<P>;
};

フィールド

requestRequest: 受け取ったリクエスト。
paramsRegisteredPageParams: ページと同じく、スキーマが作った型のparams。

PatternOf

import元 @k8ordo/router

表Rのすべてのページのパターンです。書いたとおりの綴りで、/*のパターンも含みます。

コードをコピー

type PatternOf<R extends RoutesRecord>

NavigablePatternOf

import元 @k8ordo/router

表Rのうち、リンク先にできるパターンです。/*を含むものを除きます。

コードをコピー

type NavigablePatternOf<R extends RoutesRecord>

NavigablePath

import元 @k8ordo/router

パスPathが、表のリンク先にできるパターンのどれかに区間ごとに合えばPath、合わなければneverです。

コードをコピー

type NavigablePath<D, Path extends string>

注意

:paramの位置には、空でない1区間ならどれでも入ります。
末尾にスラッシュのあるパスはneverです。

コードをコピー

type A = NavigablePath<typeof routes, '/products/42'>;
// '/products/42'
type B = NavigablePath<typeof routes, '/products/42/reviews'>;
// never

ParamsOf

import元 @k8ordo/router

パターンの文字列から作るparamsの型です。値はどれもstringです。

コードをコピー

type ParamsOf<Pattern extends string>

コードをコピー

type Params = ParamsOf<'/:locale/products/:id'>;
// { locale: string; id: string }

PathFor

import元 @k8ordo/router

パターンに合うパスの型です。:paramの位置は任意の文字列になります。

コードをコピー

type PathFor<Pattern extends string>

コードをコピー

type Path = PathFor<'/:locale/products/:id'>;
// `/${string}/products/${string}`

ParamValue

import元 @k8ordo/router

URLでの書き方が1通りに決まる値の型です。リンクのparamに渡せます。

コードをコピー

type ParamValue = string | number | bigint | boolean;

StandardSchemaLike

import元 @k8ordo/router

Standard Schemaの形の型です。zodやzod/miniなど、Standard Schemaを実装したライブラリのスキーマが当てはまります。

コードをコピー

type StandardSchemaLike<Output = unknown> = {
  readonly '~standard': {
    readonly types?: { readonly output: Output } | undefined;
  };
};

SchemaOutput

import元 @k8ordo/router

スキーマが作る値の型です。

コードをコピー

type SchemaOutput<Schema> =
  Schema extends StandardSchemaLike<infer Output> ? Output : never;

ParamsSchemaFor

import元 @k8ordo/router

パターンPのparamsSchemaとして書けるスキーマの型です。出力のキーは、パターンのparamの一部です。

コードをコピー

type ParamsSchemaFor<Pattern extends string> = StandardSchemaLike<
  Partial<Record<keyof ParamsOf<Pattern> & string, unknown>>
>;

ParsedParams

import元 @k8ordo/router

パターンのparamsに、スキーマの並び（外側のレイアウトから順に、ページが最後）の出力を重ねた型です。スキーマが扱わないparamは文字列のままです。

コードをコピー

type ParsedParams<
  Pattern extends string,
  Schemas extends readonly unknown[],
>

ParsedParamsMap

import元 @k8ordo/router

パターンごとのスキーマの並びを、パターンごとのParsedParamsにした型です。生成されるRegisterのparamsに使います。

コードをコピー

type ParsedParamsMap<
  Schemas extends Record<string, readonly unknown[]>,
>

注意

スキーマにかかわる型は、主に生成されるコードが使います。アプリが自分で書くのは、PagePropsとLayoutPropsで足ります。