API
@k8ordo/routerがexportする関数とコンポーネント、型の一覧です。
このページの内容
defineRoutes
import元 @k8ordo/router
ルート表を作ります。キーはパスのパターンで、値はページのコンポーネントか、childrenを持つオブジェクトです。
defineRoutes<R extends RoutesRecord>(record: R): Routes<R>引数
recordRoutesRecord- ルート表。キーは
/で始まるパターンです。
戻り値
Routes<R> — 渡した表と、パスを照合するmatchを持つオブジェクト。
注意
- 表は呼んだ時点で検査します。
/で始まらないキーや同じパターンの重複など、書き方の誤りはTypeErrorになります。エラー文はroute pattern "/x" is declared twiceのような形です。 - 照合は書いた順に行い、最初に合ったパターンを選びます。
/*は最後に書きます。
routes.tsexport const routes = defineRoutes({
'/': Home,
'/products': {
layout: ProductsLayout,
children: { '/': ProductList, '/:id': ProductPage },
},
'/*': NotFound,
});Router
import元 @k8ordo/router
ルート表をNavigation APIにつなぎ、今のパスに合ったページを描画します。ブラウザで描画するアプリのいちばん上に、1度だけ置きます。
<Router routes={Routes} />引数
routesRoutesdefineRoutesが返したルート表。
注意
- ルート表に合うパスへのナビゲーションだけを処理します。それ以外はブラウザに任せます。
- 表に合わないパスで開かれたときは、何も描画しません。
- マウントした時点でブラウザのURLを読むので、サーバーでは描画できません。
Outlet
import元 @k8ordo/router
レイアウトの中で、そのレイアウトが包むページを描画する位置を示します。
<Outlet />注意
<Router>の外で描画すると、Outlet must render inside <Router>というエラーになります。@k8ordo/frameworkでは、レイアウトはchildrenを描画します。
href
import元 @k8ordo/router
パターンとparamから、リンク先のURLを作ります。
href<P extends RegisteredNavigablePattern>(
pattern: P,
params?: RegisteredParams<P>,
): string引数
patternP- リンク先のパターン。
Registerに登録していれば、表にあるリンク先にできるパターンだけを受け付けます。 paramsRegisteredParams<P>- パターンのparamの値。paramの無いパターンでは渡しません。
戻り値
string — <a>のhref属性に渡すURL。先頭にViteのbaseを付けます。
注意
- 値は
encodeURIComponentでエンコードします。 - 実行時には、
/*を含むパターンはis a wildcardを含むTypeErrorになります。値の無いparamはneeds a value for、URLで表せない値はhas no URL spellingを含む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<P>- パターンの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つ目の引数です。すべてのparamを
sourceが補うときは、2つ目にundefinedを渡します。
usePathname
import元 @k8ordo/router
ブラウザが今開いているパスを返します。
usePathname(): string戻り値
string — 今のパス。Viteのbaseと末尾のスラッシュを外した形です。
注意
- パスが変わったときだけ再描画します。クエリが変わっても再描画しません。
- URLが書き換わった時点で変わります。新しいページの表示は待ちません。
- サーバーの描画では、
@k8ordo/frameworkのページの中でだけ使えます。ハイドレーションでは、<Router>の中でも使えます。外で呼ぶとusePathname needs <Router> above itで始まるエラーになります。 <BrowserPathname>の下では、サーバーの描画でパスを返さずにブラウザを待ちます。
useMatch
import元 @k8ordo/router
今のパスがパターンに合うかを調べます。
useMatch<P extends MatchablePattern>(
pattern: P,
options?: MatchOptions,
): ParamsOf<P> | null引数
patternP- 表のパターンか、その後ろに
/*を付けたもの。/*はそのパターンより下のパスに合います。 optionsMatchOptionsinclusiveをtrueにすると、/*のパターンがそのパターン自身のページにも合います。
戻り値
ParamsOf<P> | null — 合えばそのparam、合わなければnull。
注意
usePathnameの上に作られていて、パスが変わったときだけ再描画します。- ルート表を使わないので、
@k8ordo/frameworkのページでも使えます。
matchPath
import元 @k8ordo/router
useMatchと同じ判定を、渡したパスに対して行います。
matchPath<P extends MatchablePattern>(
pattern: P,
pathname: string,
options?: MatchOptions,
): ParamsOf<P> | null引数
patternP- 表のパターンか、その後ろに
/*を付けたもの。/*はそのパターンより下のパスに合います。 pathnamestring- 調べるパス。比べる前に末尾のスラッシュを落とします。
optionsMatchOptionsinclusiveをtrueにすると、/*のパターンがそのパターン自身のページにも合います。
戻り値
ParamsOf<P> | null — 合えばそのparam、合わなければ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に戻ります。 - クエリだけを変えるナビゲーションでは、ページを読み込み直さない限り値が入りません。
- サーバーの描画では
nullです。
useParams
import元 @k8ordo/router
ページのparamを、パターンから決まる型で読みます。
useParams<P extends RegisteredPattern>(pattern: P): ParamsOf<P>引数
patternP- このコンポーネントが描画されるページのパターン。
戻り値
ParamsOf<P> — パターンから型の決まったparam。値はすべて文字列です。
注意
- 別のパターンのページの中で描画すると、
useParams("/a") rendered under "/b"の形のエラーになります。 <Router>の下でだけ使えます。@k8ordo/frameworkのページでは使えません。
useRoute
import元 @k8ordo/router
今選ばれているパターンとparamを、型の無い形で返します。
useRoute(): {
pattern: string;
params: Readonly<Record<string, string>>;
}戻り値
Pick<Match, 'pattern' | 'params'> — 選ばれたパターンと、そのparam。
注意
<Router>の外や、合ったページが無いところではuseRoute must render inside a matched <Router>というエラーになります。
normalizePathname
import元 @k8ordo/router
ルーターと同じ規則でパスを整えます。末尾のスラッシュを落とし、/だけは残します。
normalizePathname(pathname: string): string引数
pathnamestring- 整えるパス。
注意
- 落とすのは末尾のスラッシュだけです。途中のスラッシュの重なりやパーセントエンコードには触れません。
normalizePathname('/products/'); // '/products'
normalizePathname('/'); // '/'withBase
import元 @k8ordo/router
baseを含まないパスの先頭に、Viteのbaseを付けます。パスはルート表と同じ書き方です。
withBase(pathname: string, base?: string): string引数
pathnamestringbaseを含まないパス。basestring- Viteの
base。省くとimport.meta.env.BASE_URLを読みます。Viteを通らないコードでは渡します。
戻り値
string — baseの付いたパス。
注意
./のような相対のbaseでは、何も付け外ししません。
withoutBase
import元 @k8ordo/router
URLのパスから、Viteのbaseを外します。
withoutBase(pathname: string, base?: string): string | null引数
pathnamestring- URLのパス。
basestring- Viteの
base。省くとimport.meta.env.BASE_URLを読みます。Viteを通らないコードでは渡します。
戻り値
string | null — baseを外したパス。baseの外のパスにはnull。
注意
./のような相対のbaseでは、何も付け外ししません。
withBase('/products', '/docs/'); // '/docs/products'
withoutBase('/docs/products', '/docs/'); // '/products'
withoutBase('/elsewhere', '/docs/'); // nullnotFound
import元 @k8ordo/router
@k8ordo/frameworkのページから、そのパスにページが無いことを伝えます。
notFound(): never注意
- エラーになるので、後ろの行は実行されません。
@k8ordo/frameworkでは、いちばん近いnot-found.tsxを404で返します。<Router>の下では、ほかのエラーと同じ扱いです。
isNotFound
import元 @k8ordo/router
値がnotFound()のエラーかを調べます。
isNotFound(value: unknown): boolean引数
valueunknown- 調べる値。
注意
instanceofでなくSymbol.forのシンボルで判定します。このパッケージが2つ読み込まれていても正しく判定できます。
PathnameProvider
import元 @k8ordo/router
サーバーの描画とハイドレーションの間、usePathnameが返すパスを渡します。
<PathnameProvider pathname={string}>{children}</PathnameProvider>引数
pathnamestring- この描画のパス。
注意
<Router>と、@k8ordo/frameworkのランタイムが自分で置きます。アプリが書くのは、useInterceptedNavigationで自分のホストを作るときだけです。
BrowserPathname
import元 @k8ordo/router
サーバーの描画に、渡せるパスが無いことを伝えます。この下のusePathnameとuseMatchは、use(browser())でブラウザを待ちます。
<BrowserPathname>{children}</BrowserPathname>注意
- いちばん近い
<Suspense>の中身は、ブラウザで描画されます。 @k8ordo/frameworkのランタイムが、fallback.tsxのまわりに置きます。アプリが書くことはありません。
NavigationGeneration
import元 @k8ordo/router
新しいページが表示されたことを、ルート表のerrorに伝えるコンテキストです。
<NavigationGeneration value={number}>
{children}
</NavigationGeneration>引数
valuenumberuseInterceptedNavigationが返すgeneration。
注意
<Router>と、@k8ordo/frameworkのランタイムが自分で置きます。
useInterceptedNavigation
import元 @k8ordo/router
<Router>のナビゲーションの部分を、単独で使うためのフックです。処理すると決めたナビゲーションを読み込んで反映し、新しいページが表示されてから終えます。
useInterceptedNavigation<T>(
handler: NavigationHandler<T>,
): { readonly generation: number }引数
handlerNavigationHandler<T>- ナビゲーションの処理を決める関数を持つオブジェクト。形は
NavigationHandlerです。
戻り値
{ readonly generation: number } — 新しいページが表示されるたびに変わるgeneration。
注意
applyで入れた値は、同じコンポーネントの中でuseDeferredValueを通して描画してください。handlerはイベントの時点で読むので、描画のたびに作り直してもかまいません。
src/article-host.tsx'use client';
import {
NavigationGeneration,
PathnameProvider,
useInterceptedNavigation,
} from '@k8ordo/router';
import { useDeferredValue, useState } from 'react';
import type { ReactNode } from 'react';
type Props = { initial: ReactNode; pathname: string };
export function ArticleHost({ initial, pathname }: Props) {
const [latest, setLatest] = useState(initial);
const { generation } = useInterceptedNavigation<ReactNode>({
claim: (url) => url.pathname.startsWith('/articles/'),
load: (url, signal) => loadArticle(url, signal),
apply: setLatest,
});
const shown = useDeferredValue(latest);
return (
<PathnameProvider pathname={pathname}>
<NavigationGeneration value={generation}>
{shown}
</NavigationGeneration>
</PathnameProvider>
);
}Routes
import元 @k8ordo/router
defineRoutesが返すルート表の型です。
type Routes<R extends RoutesRecord = RoutesRecord> = {
kind: 'routes';
record: R;
match: (pathname: string) => Match | null;
matchAll: (pathname: string) => IteratorObject<Match, undefined>;
};フィールド
kind'routes'- 常に
'routes'。 recordRdefineRoutesに渡した表。match(pathname) => Match | null- パスを照合し、最初に合った
Matchかnullを返します。 matchAll(pathname) => IteratorObject<Match, undefined>- パスに合うパターンをすべて、表に書いた順に返す反復子です。照合するのは反復が進んだところまでです。
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を渡さず、@k8ordo/frameworkはparamsなどを渡します。どちらの表にも同じコンポーネントを書けます。
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?) => stringsourceのparamを補うhref。navigateTo(pattern, params?, options?) => NavigationResultsourceのparamを補うnavigateTo。
NavigationHandler
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- 作ったものを、トランジションの外でふつうの更新として反映します。
refresh(url: URL) => boolean- パスが変わらないナビゲーションでも読み込み直すかどうか。省くと読み込み直しません。
Register
import元 @k8ordo/router
ルート表を型に登録するためのインターフェースです。declare moduleでroutesを足すと、パターンを表と照らし合わせます。
declare module '@k8ordo/router' {
interface Register {
routes: typeof routes;
}
}注意
- 登録はアプリの中で1度だけ行います。
@k8ordo/frameworkでは.k8ordo/register.gen.tsに生成されます。
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へのリンクが受け取るparamの型です。スキーマが型を決めたparamはその型で、ほかはParamValueか文字列です。
type RegisteredParams<P extends string>RegisteredPageParams
import元 @k8ordo/router
パターンPのページが受け取るparamの型です。スキーマを通したparamはその出力で、ほかは文字列です。
type RegisteredPageParams<P extends string>PageProps
import元 @k8ordo/router
@k8ordo/frameworkのページが受け取るpropsの型です。型引数には、ページのディレクトリが表すパターンを渡します。
type PageProps<P extends RegisteredPattern> = {
readonly params: RegisteredPageParams<P>;
readonly pathname: string;
} & RequestProps &
SearchProps<P>;フィールド
paramsRegisteredPageParams<P>- スキーマが決めた型のparam。
pathnamestring- この描画のパス。
requestRequest- リクエスト。serverモードでだけ加わります。
searchunknownsearchをexportしたページが読んだ値。そのページにだけ加わります。
LayoutProps
import元 @k8ordo/router
@k8ordo/frameworkのレイアウトが受け取るpropsの型です。型引数には、ページのあるパターンだけを渡せます。
type LayoutProps<P extends RegisteredPattern> = {
readonly params: ParamsOf<P>;
readonly pathname: string;
readonly children: ReactNode;
} & RequestProps;フィールド
paramsParamsOf<P>- param。スキーマを書いていても、型は文字列です。
pathnamestring- この描画のパス。
childrenReactNode- レイアウトが包むページ。
requestRequest- リクエスト。serverモードでだけ加わります。
RouteContext
import元 @k8ordo/router
@k8ordo/frameworkのroute.tsがexportする関数の引数の型です。
type RouteContext<P extends RegisteredPattern> = {
readonly request: Request;
readonly params: RegisteredPageParams<P>;
};フィールド
requestRequest- 受け取ったリクエスト。
paramsRegisteredPageParams<P>- ページと同じく、スキーマが決めた型のparam。
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'>;
// neverParamsOf
import元 @k8ordo/router
パターンの文字列から作るparamの型です。値はすべて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;
};
};注意
- スキーマにかかわる型は、主に生成されるコードが使います。アプリが自分で書く型は
PagePropsとLayoutPropsで足ります。
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
パターンのparamに、スキーマの並びの出力を重ねた型です。並びは外側のレイアウトから順に、ページが最後です。スキーマが扱わない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[]>,
>