@k8ordo/router

はじめる

商品の一覧と商品ごとのページを持つ、ViteとReactのアプリを例にします。ルート表を書いてブラウザに表示し、ページ同士をリンクでつなぎます。

このページの内容

インストール

bash
npm install @k8ordo/router

次の環境で動きます。

  • React 19.3以上
  • TypeScriptで書くなら、TypeScript 7以上

エージェント向けのガイドはnode_modules/@k8ordo/router/docs/GUIDE.mdに入っています。AGENTS.mdなどからこのパスを参照させてください。

ナビゲーションにはブラウザのNavigation APIを、パスの照合にはURLPatternを使います。polyfillもフォールバックもありません。

ルート表の定義

src/routes.ts
import { defineRoutes } from '@k8ordo/router';

import { Home } from './pages/home';
import { NotFound } from './pages/not-found';
import { ProductList } from './pages/product-list';
import { ProductPage } from './pages/product-page';

export const routes = defineRoutes({
  '/': Home,
  '/products': ProductList,
  '/products/:id': ProductPage,
`:id`はパスの1区間を受け取るparam
  '/*': NotFound,
上のどのパターンにも合わないパスを受ける
});

アプリで開けるパスと、そのパスで表示するページをdefineRoutesに書きます。キーがパスのパターンで、値がページのコンポーネントです。ページはpropsを受け取らないReactコンポーネントです。

/products/42を開くとProductPageが表示され、idは'42'です。パターンは上から順に照合するので、/*は最後に置きます。

ページを移ってもレイアウトは作り直されず、<Outlet />の中だけが切り替わります。レイアウトやルートグループの書き方はルート表を見てください。

ルーターの設置

src/main.tsx
import { Router } from '@k8ordo/router';
import { StrictMode } from 'react';
import { createRoot } from 'react-dom/client';

import { routes } from './routes';

const root = document.querySelector('#root');
if (root === null) throw new Error('#root is missing');

createRoot(root).render(
  <StrictMode>
    <Router routes={routes} />
  </StrictMode>,
);

createRootで描画する最上位に<Router>を置き、ルート表を渡します。<Router>はブラウザで開いているパスを表と照合し、合ったページを表示します。

情報

メモ

<Router>はブラウザの中で表示するアプリで使います。サーバーで描画する場合やビルド時に生成する場合は、@k8ordo/frameworkを使います。

src/pages/product-list.tsx
import { href } from '@k8ordo/router';

const products = [
  { id: '1', name: 'Desk lamp' },
  { id: '2', name: 'Notebook' },
];

export function ProductList() {
  return (
    <ul>
      {products.map((product) => (
        <li key={product.id}>
          <a href={href('/products/:id', { id: product.id })}>
`id`を渡し忘れると型エラーになる
            {product.name}
          </a>
        </li>
      ))}
    </ul>
  );
}

リンク先はhrefにパターンとparamを渡して作ります。paramの型はパターンの文字列から推論されます。

リンクはただの<a>です。押されたときにブラウザが知らせるナビゲーションを<Router>が受け取るので、ページ全体は読み込み直されません。

paramの読み取り

src/pages/product-page.tsx
import { href, useParams } from '@k8ordo/router';

export function ProductPage() {
  const { id } = useParams('/products/:id');
自分のパターンを渡してparamを読む

  return (
    <article>
      <h1>Product {id}</h1>
      <a href={href('/products')}>Back to the list</a>
    </article>
  );
}

ページの側では、useParamsに自分のパターンを渡してparamを読みます。どちらのファイルもルート表をimportしません。

表に無いパターンも型エラーにするには、ルート表をRegisterに登録します。書き方はパスの型検査を見てください。

k8ordo

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