@k8ordo/state

はじめる

商品一覧の絞り込みをURLに置く例で、@k8ordo/stateの使い方をたどります。状態を1つ定義して、コンポーネントで読み書きするところまで進みます。

このページの内容

インストール

bash
npm install @k8ordo/state zod

次の環境で動きます。

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

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

ブラウザでは、URLの書き換えにNavigation APIを使います。polyfillもフォールバックもありません。

情報

メモ

このページの例はzodで書いていますが、zod/miniでも動きます。選び方は置き場所の「zod/mini」の節を見てください。

状態の定義

src/state.ts
import { definePageState } from '@k8ordo/state';
import * as z from 'zod';

export const listState = definePageState('product-list', {
この状態の名前。アプリの中で重ならないものを付ける
  url: z.object({
    inStock: z.stringbool().default(false),
    page: z.coerce.number().int().min(1).default(1),
  }),
});

リンクを共有したときに同じ一覧が開くように、絞り込みはURLに置きます。URLに置く状態は、definePageStateのurlにスキーマで書きます。

URLのパラメータは欠けることがあるので、どのフィールドにも.default()を付けます。パラメータの値は文字列です。数値はz.coerce.number()で、真偽値はz.stringbool()で受けます。

定義は'use client'の無いモジュールに書き、Server ComponentとClient Componentの両方からimportします。'use client'のファイルからexportすると、Server Componentにはclient referenceが渡り、hrefを呼べません。

フックでの読み書き

src/components/filters.tsx
'use client';

import { useAppState } from '@k8ordo/state';

import { listState } from '../state';

export function Filters() {
  const [{ inStock, page }, update] = useAppState(listState);

  return (
    <div>
      <label>
        <input
          checked={inStock}
          onChange={(event) => {
            update({ inStock: event.target.checked, page: 1 });
今の履歴エントリを書き換える
          }}
          type="checkbox"
        />
        In stock only
      </label>
      <button
        onClick={() => {
          update({ page: page + 1 }, { history: 'push' });
新しい履歴エントリを追加する
        }}
        type="button"
      >
        Next page
      </button>
    </div>
  );
}

Client ComponentでuseAppStateに定義を渡すと、現在の値とupdateが返ります。updateは値を変える関数です。

update()に渡した値は次の描画に反映され、URLへの書き込みはそのあとに行われます。書き込みのまとめ方や待ち方は更新を見てください。

update()は既定では今の履歴エントリを書き換えます。ページ送りには{ history: 'push' }を付けているので、ブラウザの戻るボタンで前のページに戻れます。

Playground

絞り込みのデモ

このページのURLを実際に書き換えるdefinePageStateです。

  • デスクライト在庫あり
  • 木の椅子売り切れ
1 / 3
クエリ
クエリなし(すべて既定値)

試してみる

  1. 「在庫があるものだけ」にチェックを入れると、クエリが?inStock=trueになり、在庫のある商品だけが並びます。
  2. 「次のページ」を押すと、クエリにpage=2が足されます。そのあとブラウザの戻るボタンを押すと、1ページ目に戻ります。
  3. チェックを外すと、クエリからinStockが消えます。falseは既定値なので、URLには書かれません。
k8ordo

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