state-in-url 6.4.1 → 7.0.0

package/README.ja.md

@@ -1,6 +1,6 @@
 <!-- i18n:start -->
 [English](./README.md) · [简体中文](./README.zh-CN.md) · 日本語 · [한국어](./README.ko.md) · [Русский](./README.ru.md) · [Español](./README.es.md) · [Português (BR)](./README.pt-BR.md) · [Français](./README.fr.md) · [Tiếng Việt](./README.vi.md)
-<!-- i18n:meta locale=ja source=README.md source-blob=bbf45a10aae9e88f68b27d84f51ee3e7e8a1e436 status=translated -->
+<!-- i18n:meta locale=ja source=README.md source-blob=ad78fdbbee096115a953813ed9a462e3393c5736 status=translated -->
 <!-- i18n:end -->
 
 <div align="center">
@@ -69,7 +69,7 @@
 任意のユーザー状態をクエリパラメータに保存します。ブラウザの URL に JSON があるイメージです。データの型と構造を保持したまま、たとえば数値は文字列ではなく数値として、日付は日付としてデコードされ、オブジェクトや配列もサポートされます。
 非常にシンプルで高速、そして静的 TypeScript バリデーション付き。ディープリンク(別名 URL 同期)が簡単になります。
 
-Next.js と react-router 用の `useUrlState` フックと、その他あらゆる JS 向けのヘルパーを備えています。
+Next.js、react-router、Remix、Astro 用の `useUrlState` フックと、その他あらゆる JS 向けのヘルパーを備えています。
 現代のブラウザは巨大な URL をサポートしており、ユーザーはクエリ文字列を気にしません(全選択してコピー/ペーストするワークフローです)。
 
 本来の目的どおりに、クエリ文字列を状態管理に使うときが来ました。
@@ -98,10 +98,32 @@ Next.js と react-router 用の `useUrlState` フックと、その他あらゆ
 - **サーバーサイドレンダリング**: サーバーコンポーネントで使用可能。Next.js 14、15、16 をサポート
 - **軽量**: 依存関係ゼロ。ライブラリは 2KB 未満
 - **DX**: 優れた開発者体験。ドキュメント、JSDoc コメント、サンプル付き
-- **フレームワークの柔軟性**: `Next.js` と `react-router` 用のフック、その他のフレームワークやピュア JS で使うためのヘルパー
+- **フレームワークの柔軟性**: `Next.js`、`react-router`、`Remix`、`Astro` 用のフック、その他のフレームワークやピュア JS で使うためのヘルパー
 - **十分にテスト済み**: [Chrome/Firefox/Safari 向けのユニットテストと Playwright テスト](https://github.com/asmyshlyaev177/state-in-url/actions/workflows/tests.yml)
 - **寛容なライセンス**: MIT
 
+### nuqs との比較
+
+[nuqs](https://github.com/47ng/nuqs) の代替をお探しですか？どちらも型付きの状態をクエリ文字列に保存しますが、必要な設定量と、値として扱えるものが異なります。
+
+| 項目 | `state-in-url` | `nuqs` |
+| --- | --- | --- |
+| セットアップ | 不要 — hook を import するだけ | アダプターコンポーネントでアプリをラップ |
+| 状態の形 | `React.useState` のような型付きオブジェクト1つ | キーごとの値、それぞれにパーサーを宣言 |
+| コンポーネント間の再利用 | hook を一度包むだけ — 全コンポーネントが状態を共有、props 不要 | パーサー群を包む hook は自分で抽出 |
+| ネストしたオブジェクトと配列 | 標準対応 — 構造と型を保持 | JSON パーサーに加えて自前のバリデーターが必要 |
+| 日付 | 自動的に保持 | 組み込みパーサーをキーごとに宣言 |
+| サイズ（全体 import） | 約 2.9 KB gzip | 約 6.7 KB gzip |
+| ランタイム依存 | なし | 1つ |
+| ルーター | Next.js、React Router v6/v7、Remix、Astro、素の JS 用ヘルパー | Next.js、React Router、Remix、TanStack Router、素の React |
+
+サイズはライブラリ全体の import を esbuild minify + gzip で計測（2026年8月、nuqs 2.10.1 と比較）。
+
+nuqs も優れたライブラリです。値ごとに読みやすいクエリパラメータが欲しいとき、TanStack Router を使っているときは nuqs を。型付きオブジェクトを丸ごと URL に、設定ゼロで入れたいなら state-in-url を選んでください。
+
+
+完全版の比較 — 同じ機能の両実装、ほかの代替（TanStack Router、use-query-params）、移行メモ — は <https://state-in-url.dev/vs/nuqs> にあります。
+
 ## 目次
 
 <!-- toc:start -->
@@ -111,6 +133,7 @@ Next.js と react-router 用の `useUrlState` フックと、その他あらゆ
   - [なぜ `state-in-url` を使うのか？](#なぜ-state-in-url-を使うのか)
     - [ユースケース](#ユースケース)
     - [特徴](#特徴)
+    - [nuqs との比較](#nuqs-との比較)
   - [目次](#目次)
   - [インストール](#インストール)
     - [1. パッケージのインストール](#1-パッケージのインストール)
@@ -127,6 +150,10 @@ Next.js と react-router 用の `useUrlState` フックと、その他あらゆ
       - [例](#例)
     - [React-Router 向け useUrlState フック](#react-router-向け-useurlstate-フック)
       - [例](#例-1)
+    - [React 向け useUrlState フック（ルーターなし）](#react-向け-useurlstate-フックルーターなし)
+      - [例](#例-2)
+    - [Astro 向け useUrlState フック](#astro-向け-useurlstate-フック)
+      - [例](#例-3)
   - [レシピ](#レシピ)
         - [状態の一部を便利に扱うカスタムフック](#状態の一部を便利に扱うカスタムフック)
         - [複雑な状態の形を使用](#複雑な状態の形を使用)
@@ -515,6 +542,156 @@ const tags = [
 
 [サンプルコード](packages/example-react-router6/src/Form-for-test.tsx)
 
+### React 向け useUrlState フック（ルーターなし）
+
+ルーターを持たない React アプリ向けです。Vite、Create React App、あるいは自分では管理できないページに埋め込むウィジェットなどが対象です。このフックは `window.history` で URL を書き込み、戻る/進むや他の `pushState`/`replaceState` のたびに読み戻します。同じ state オブジェクトを使うコンポーネントはすべて状態を共有するため、ラップするものも props で渡すものもありません。
+
+[API ドキュメント](packages/urlstate/react/useUrlState)
+
+#### 例
+
+```typescript
+// useFilters.ts
+import { useUrlState } from 'state-in-url/react';
+
+type FiltersState = { sort: 'name' | 'date'; page: number };
+const FILTERS_STATE: FiltersState = { sort: 'name', page: 1 };
+
+export function useFilters() {
+  return useUrlState(FILTERS_STATE);
+}
+```
+
+```typescript
+// FiltersBar.tsx
+import { useFilters } from './useFilters';
+
+export function FiltersBar() {
+  const { urlState, setUrl } = useFilters();
+
+  return <button onClick={() => setUrl({ page: urlState.page + 1 })}>Page {urlState.page}</button>;
+}
+```
+
+`state-in-url/astro` は同じフックです。islands では `searchParams` を prop として受け取るため、下で別に説明しています。
+
+### Astro 向け useUrlState フック
+
+React アイランド向けです。Astro にはデフォルトでクライアントサイドルーターがないため、このフックは `window.history` で URL を書き込み、戻る/進む操作時およびその他あらゆる `pushState`/`replaceState` の際（Astro 自身の `<ClientRouter />` を含む）に URL を読み戻します。ページ上のアイランドは状態を共有し、それらをラップするものは何も必要ありません。
+
+[API ドキュメント](packages/urlstate/astro/useUrlState)
+
+#### 例
+
+```typescript
+// src/state.ts
+export const form: Form = {
+  name: '',
+  age: undefined,
+  agree_to_terms: false,
+  tags: [],
+};
+
+type Form = {
+  name: string;
+  age?: number;
+  agree_to_terms: boolean;
+  tags: { id: string; value: { text: string; time: Date } }[];
+};
+```
+
+ページはオンデマンドでレンダリングされる必要があります（`output: 'server'`、またはページ側で `export const prerender = false` を指定し、アダプターを併用）。プリレンダリングされたページにはリクエストがないため、アイランドは `{}` を受け取り、ハイドレーション後に URL を読み取ります。
+
+```astro
+---
+// src/pages/index.astro
+import { Form } from '../components/Form';
+import { Status } from '../components/Status';
+
+// サーバーレンダリングが URL と一致するため、ハイドレーションで修正すべきものはありません。
+// プレーンなオブジェクトにします。アイランドの props はシリアライズされますが、URLSearchParams はされません。
+const searchParams = Object.fromEntries(Astro.url.searchParams);
+---
+
+<Form client:load searchParams={searchParams} />
+<Status client:load searchParams={searchParams} />
+```
+
+```typescript
+// src/components/Form.tsx
+import React from 'react';
+import { useUrlState } from 'state-in-url/astro';
+
+import { form } from '../state';
+
+export function Form({ searchParams }: { searchParams?: Record<string, string> }) {
+  const { urlState, setUrl, setState } = useUrlState(form, { searchParams });
+
+  const onChangeTags = React.useCallback(
+    (tag: (typeof tags)[number]) => {
+      setUrl((curr) => ({
+        ...curr,
+        tags: curr.tags.find((t) => t.id === tag.id)
+          ? curr.tags.filter((t) => t.id !== tag.id)
+          : curr.tags.concat(tag),
+      }));
+    },
+    [setUrl],
+  );
+
+  return (
+    <div>
+      {tags.map((tag) => (
+        <Tag
+          active={!!urlState.tags.find((t) => t.id === tag.id)}
+          text={tag.value.text}
+          onClick={() => onChangeTags(tag)}
+          key={tag.id}
+        />
+      ))}
+
+      <input value={urlState.name}
+        onChange={(ev) => { setState(curr => ({ ...curr, name: ev.target.value })) }}
+        // 状態は即座に更新しつつ、変更は必要に応じて URL に同期できます
+        onBlur={() => setUrl()}
+      />
+    </div>
+  );
+}
+
+const tags = [
+  { id: '1', value: { text: 'React.js', time: new Date('2024-07-17T04:53:17.000Z') } },
+  { id: '2', value: { text: 'Next.js', time: new Date('2024-07-18T04:53:17.000Z') } },
+  { id: '3', value: { text: 'TailwindCSS', time: new Date('2024-07-19T04:53:17.000Z') } },
+];
+
+// 2つ目のアイランド Status.tsx は同じ状態を読み取ります
+export function Status({ searchParams }: { searchParams?: Record<string, string> }) {
+  const { urlState } = useUrlState(form, { searchParams });
+  return <pre>{JSON.stringify(urlState, null, 2)}</pre>;
+}
+```
+
+Preact アイランドも同じように動作します。`@astrojs/preact` を `compat: true` で使うと、サーバービルドとクライアントビルドの両方で `react` が `preact/compat` に解決され、上記のインポートはそのまま変わりません。
+
+アイランドを使わず、クライアントフレームワークをまったく使わないページでは、同じ状態を [`decodeState` と `encodeState`](#encodestate-と-decodestate-ヘルパー) を通じてフロントマターに置けます:
+
+```astro
+---
+import { decodeState, encodeState } from 'state-in-url/encodeState';
+
+import { form } from '../state';
+
+const state = decodeState(Astro.url.searchParams, form);
+const withName = encodeState({ ...state, name: 'Alice' }, form, Astro.url.searchParams);
+---
+
+<pre>{JSON.stringify(state)}</pre>
+<a href={`?${withName}`}>Alice</a>
+```
+
+[サンプルコード](packages/example-astro/src/components/Form-for-test.tsx)、[素の Astro ページ](packages/example-astro/src/pages/pure-astro.astro)
+
 ## レシピ
 ##### 状態の一部を便利に扱うカスタムフック
 <details>
@@ -678,7 +855,37 @@ const tags = [
 
 ### 他のルーター向け `useUrlStateBase` フック
 
-react-router や tanstack router など、他のルーターで独自の `useUrlState` フックを作成するためのフックです。
+本パッケージがエントリーポイントを用意していないルーター（例: TanStack Router）向けに、自前の `useUrlState` を作るために使います。`push(url)` と `replace(url)` を持つメモ化されたオブジェクトを渡してください。
+
+ルーターが**まったくない**場合は不要です。[`state-in-url/react`](#react-向け-useurlstate-フックルーターなし) を使ってください。こちらは同じフックを `window.history` に接続済みのものです。
+
+```typescript
+import { useUrlStateBase } from 'state-in-url/useUrlStateBase';
+
+type FiltersState = { sort: 'name' | 'date'; page: number };
+const FILTERS_STATE: FiltersState = { sort: 'name', page: 1 };
+
+export function useFilters() {
+  const router = useYourRouter();
+  const nav = React.useMemo(
+    () => ({
+      push: (url: string) => router.navigate(url),
+      replace: (url: string) => router.navigate(url, { replace: true }),
+    }),
+    [router],
+  );
+
+  return useUrlStateBase(FILTERS_STATE, nav, ({ parse }) => parse(window.location.search));
+}
+```
+
+`useUrlState` との違いは 2 点です:
+
+- 返すのは `urlState`、`setUrl`、`setState` ではなく `state`、`updateUrl`、`updateState` です。また `updateUrl` の既定は push で、`setUrl` の既定は replace です。
+- 第 3 引数が初期 state を決めます。省略するとフックは読み込み時のクエリ文字列を無視するため、共有されたリンクを開いても既定値が表示されます。
+
+> [!NOTE]
+> `useUrlState` はパッケージのルートからはエクスポートされません。どの `useUrlState` もフレームワークに結び付いているため、それぞれ専用のエントリーポイント（`state-in-url/next`、`/react`、`/react-router`、`/react-router6`、`/remix`、`/astro`）にあります。ルートエントリーにはフレームワークに依存しないものだけが残ります: `useSharedState`、`useUrlEncode`、`useUrlStateBase`、`useLinkProps`、`encode`/`decode`、`encodeState`/`decodeState`。
 
 [API ドキュメント](packages/urlstate/useUrlStateBase)
 
@@ -787,7 +994,7 @@ export const useUserState = () => {
 - [x] `react-router` 向けフック
 - [x] `remix` 向けフック
 - [ ] `svelte` 向けフック
-- [ ] `astro` 向けフック
+- [x] `astro` 向けフック
 - [ ] ハッシュに状態を保存するフック?
 
 ## 連絡先とサポート

package/README.ko.md

@@ -1,6 +1,6 @@
 <!-- i18n:start -->
 [English](./README.md) · [简体中文](./README.zh-CN.md) · [日本語](./README.ja.md) · 한국어 · [Русский](./README.ru.md) · [Español](./README.es.md) · [Português (BR)](./README.pt-BR.md) · [Français](./README.fr.md) · [Tiếng Việt](./README.vi.md)
-<!-- i18n:meta locale=ko source=README.md source-blob=bbf45a10aae9e88f68b27d84f51ee3e7e8a1e436 status=translated -->
+<!-- i18n:meta locale=ko source=README.md source-blob=ad78fdbbee096115a953813ed9a462e3393c5736 status=translated -->
 <!-- i18n:end -->
 
 <div align="center">
@@ -69,7 +69,7 @@
 쿼리 매개변수에 모든 사용자 상태를 저장하세요. 브라우저 URL에 JSON이 있다고 상상해보세요. 데이터의 타입과 구조를 유지하면서 모든 것을 저장할 수 있습니다. 예를 들어 숫자는 문자열이 아닌 숫자로, 날짜는 날짜로 디코딩되며, 객체와 배열도 지원됩니다.
 매우 간단하고 빠르며 정적 Typescript 유효성 검사를 제공합니다. 딥 링크, 즉 URL 동기화가 쉬워집니다.
 
-Next.js와 react-router용 `useUrlState` 훅과 그 외 JS 환경을 위한 헬퍼를 포함합니다.
+Next.js, react-router, Remix, Astro용 `useUrlState` 훅과 그 외 JS 환경을 위한 헬퍼를 포함합니다.
 최신 브라우저는 거대한 URL을 지원하고 사용자는 쿼리 문자열을 신경 쓰지 않습니다(전체 선택 후 복사/붙여넣기 워크플로우입니다).
 
 쿼리 문자열을 원래 의도대로 상태 관리에 사용할 때입니다.
@@ -98,10 +98,32 @@ Next.js와 react-router용 `useUrlState` 훅과 그 외 JS 환경을 위한 헬
 - **서버 사이드 렌더링**: 서버 컴포넌트에서 사용 가능, Next.js 14 및 15 지원
 - **경량**: 의존성 없음, 라이브러리 크기 2KB 미만
 - **개발자 경험**: 좋은 개발자 경험, 문서, JSDoc 주석 및 예제
-- **프레임워크 유연성**: `Next.js` 및 `react-router`용 훅, 다른 프레임워크나 순수 JS와 함께 사용할 수 있는 헬퍼
+- **프레임워크 유연성**: `Next.js`, `react-router`, `Remix`, `Astro`용 훅, 다른 프레임워크나 순수 JS와 함께 사용할 수 있는 헬퍼
 - **충분한 테스트**: [Chrome/Firefox/Safari용 단위 테스트 및 Playwright 테스트](https://github.com/asmyshlyaev177/state-in-url/actions/workflows/tests.yml)
 - **자유로운 라이선스**: MIT
 
+### nuqs와 비교
+
+[nuqs](https://github.com/47ng/nuqs) 대안을 찾고 계신가요? 둘 다 타입이 유지되는 상태를 쿼리 문자열에 저장하지만, 필요한 설정량과 값으로 담을 수 있는 것이 다릅니다.
+
+| 항목 | `state-in-url` | `nuqs` |
+| --- | --- | --- |
+| 설정 | 불필요 — hook을 import하면 끝 | 어댑터 컴포넌트로 앱을 감싸야 함 |
+| 상태 형태 | `React.useState` 같은 타입 객체 하나 | 키별 값, 각 키마다 파서 선언 |
+| 컴포넌트 간 재사용 | hook을 한 번 감싸면 — 모든 컴포넌트가 상태 공유, props 불필요 | 파서 맵을 감싸는 hook은 직접 추출 |
+| 중첩 객체와 배열 | 기본 지원 — 구조와 타입 유지 | JSON 파서에 자체 런타임 검증 추가 필요 |
+| 날짜 | 자동으로 유지 | 내장 파서를 키마다 선언 |
+| 크기, 전체 import | 약 2.9 KB gzip | 약 6.7 KB gzip |
+| 런타임 의존성 | 없음 | 1개 |
+| 라우터 | Next.js, React Router v6/v7, Remix, Astro, 순수 JS 헬퍼 | Next.js, React Router, Remix, TanStack Router, 순수 React |
+
+크기: 라이브러리 전체 import, esbuild minify + gzip, 2026년 8월 nuqs 2.10.1 기준 측정.
+
+nuqs도 훌륭한 라이브러리입니다. 값마다 읽기 쉬운 쿼리 파라미터를 원하거나 TanStack Router를 쓴다면 nuqs를, 타입 객체 전체를 설정 없이 URL에 넣고 싶다면 state-in-url을 선택하세요.
+
+
+전체 비교 — 같은 기능의 두 구현, 다른 대안(TanStack Router, use-query-params), 마이그레이션 노트 — 는 <https://state-in-url.dev/vs/nuqs> 에 있습니다.
+
 ## 목차
 
 <!-- toc:start -->
@@ -111,6 +133,7 @@ Next.js와 react-router용 `useUrlState` 훅과 그 외 JS 환경을 위한 헬
   - [왜 `state-in-url`을 사용해야 하나요?](#왜-state-in-url을-사용해야-하나요)
     - [사용 사례](#사용-사례)
     - [특징](#특징)
+    - [nuqs와 비교](#nuqs와-비교)
   - [목차](#목차)
   - [설치](#설치)
     - [1. 패키지 설치](#1-패키지-설치)
@@ -127,6 +150,10 @@ Next.js와 react-router용 `useUrlState` 훅과 그 외 JS 환경을 위한 헬
       - [예제](#예제)
     - [React-Router용 useUrlState 훅](#react-router용-useurlstate-훅)
       - [예제](#예제-1)
+    - [React용 useUrlState 훅 (라우터 없음)](#react용-useurlstate-훅-라우터-없음)
+      - [예제](#예제-2)
+    - [Astro용 useUrlState 훅](#astro용-useurlstate-훅)
+      - [예제](#예제-3)
   - [레시피](#레시피)
         - [상태의 일부를 편리하게 다루기 위한 커스텀 훅](#상태의-일부를-편리하게-다루기-위한-커스텀-훅)
         - [복잡한 상태 구조 사용](#복잡한-상태-구조-사용)
@@ -511,6 +538,156 @@ const tags = [
 
 [예제 코드](packages/example-react-router6/src/Form-for-test.tsx)
 
+### React용 useUrlState 훅 (라우터 없음)
+
+라우터가 없는 React 앱을 위한 것입니다. Vite, Create React App, 또는 직접 제어할 수 없는 페이지에 끼워 넣는 위젯이 여기에 해당합니다. 이 훅은 `window.history` 로 URL 을 쓰고, 뒤로/앞으로 이동할 때와 다른 코드가 `pushState`/`replaceState` 를 호출할 때 다시 읽어 옵니다. 같은 state 객체를 쓰는 모든 컴포넌트가 상태를 공유하므로, 감쌀 것도 props 로 넘길 것도 없습니다.
+
+[API 문서](packages/urlstate/react/useUrlState)
+
+#### 예제
+
+```typescript
+// useFilters.ts
+import { useUrlState } from 'state-in-url/react';
+
+type FiltersState = { sort: 'name' | 'date'; page: number };
+const FILTERS_STATE: FiltersState = { sort: 'name', page: 1 };
+
+export function useFilters() {
+  return useUrlState(FILTERS_STATE);
+}
+```
+
+```typescript
+// FiltersBar.tsx
+import { useFilters } from './useFilters';
+
+export function FiltersBar() {
+  const { urlState, setUrl } = useFilters();
+
+  return <button onClick={() => setUrl({ page: urlState.page + 1 })}>Page {urlState.page}</button>;
+}
+```
+
+`state-in-url/astro` 는 바로 이 훅입니다. islands 는 `searchParams` 를 prop 으로도 받기 때문에 아래에서 따로 설명합니다.
+
+### Astro용 useUrlState 훅
+
+React 아일랜드용입니다. Astro에는 기본적으로 클라이언트 측 라우터가 없으므로, 이 훅은 `window.history`로 URL을 쓰고, 뒤로/앞으로 이동과 그 외 모든 `pushState`/`replaceState` 시점에 (Astro 자체의 `<ClientRouter />` 포함) URL을 다시 읽어 옵니다. 한 페이지의 아일랜드들은 감싸는 것 없이 상태를 공유합니다.
+
+[API 문서](packages/urlstate/astro/useUrlState)
+
+#### 예제
+
+```typescript
+// src/state.ts
+export const form: Form = {
+  name: '',
+  age: undefined,
+  agree_to_terms: false,
+  tags: [],
+};
+
+type Form = {
+  name: string;
+  age?: number;
+  agree_to_terms: boolean;
+  tags: { id: string; value: { text: string; time: Date } }[];
+};
+```
+
+페이지는 온디맨드로 렌더링되어야 합니다(어댑터와 함께 `output: 'server'`를 쓰거나, 해당 페이지에 `export const prerender = false`를 선언). 프리렌더링된 페이지에는 요청이 없으므로 아일랜드는 `{}`를 받고 하이드레이션 후에 URL을 읽습니다.
+
+```astro
+---
+// src/pages/index.astro
+import { Form } from '../components/Form';
+import { Status } from '../components/Status';
+
+// 서버 렌더링이 URL과 일치하므로 하이드레이션이 바로잡을 것이 없습니다.
+// 일반 객체여야 합니다. 아일랜드 props는 직렬화되지만 URLSearchParams는 직렬화되지 않습니다.
+const searchParams = Object.fromEntries(Astro.url.searchParams);
+---
+
+<Form client:load searchParams={searchParams} />
+<Status client:load searchParams={searchParams} />
+```
+
+```typescript
+// src/components/Form.tsx
+import React from 'react';
+import { useUrlState } from 'state-in-url/astro';
+
+import { form } from '../state';
+
+export function Form({ searchParams }: { searchParams?: Record<string, string> }) {
+  const { urlState, setUrl, setState } = useUrlState(form, { searchParams });
+
+  const onChangeTags = React.useCallback(
+    (tag: (typeof tags)[number]) => {
+      setUrl((curr) => ({
+        ...curr,
+        tags: curr.tags.find((t) => t.id === tag.id)
+          ? curr.tags.filter((t) => t.id !== tag.id)
+          : curr.tags.concat(tag),
+      }));
+    },
+    [setUrl],
+  );
+
+  return (
+    <div>
+      {tags.map((tag) => (
+        <Tag
+          active={!!urlState.tags.find((t) => t.id === tag.id)}
+          text={tag.value.text}
+          onClick={() => onChangeTags(tag)}
+          key={tag.id}
+        />
+      ))}
+
+      <input value={urlState.name}
+        onChange={(ev) => { setState(curr => ({ ...curr, name: ev.target.value })) }}
+        // 상태를 즉시 업데이트하되 필요에 따라 URL에 동기화
+        onBlur={() => setUrl()}
+      />
+    </div>
+  );
+}
+
+const tags = [
+  { id: '1', value: { text: 'React.js', time: new Date('2024-07-17T04:53:17.000Z') } },
+  { id: '2', value: { text: 'Next.js', time: new Date('2024-07-18T04:53:17.000Z') } },
+  { id: '3', value: { text: 'TailwindCSS', time: new Date('2024-07-19T04:53:17.000Z') } },
+];
+
+// 두 번째 아일랜드인 Status.tsx는 같은 상태를 읽습니다
+export function Status({ searchParams }: { searchParams?: Record<string, string> }) {
+  const { urlState } = useUrlState(form, { searchParams });
+  return <pre>{JSON.stringify(urlState, null, 2)}</pre>;
+}
+```
+
+Preact 아일랜드도 같은 방식으로 동작합니다. `@astrojs/preact`와 `compat: true`를 쓰면 서버 빌드와 클라이언트 빌드 모두에서 `react`가 `preact/compat`으로 해석되므로, 위의 import는 그대로입니다.
+
+아일랜드 없이, 클라이언트 프레임워크가 전혀 없는 페이지에서는 같은 상태가 [`decodeState`와 `encodeState`](#encodestate-및-decodestate-헬퍼)를 통해 프론트매터에 존재합니다:
+
+```astro
+---
+import { decodeState, encodeState } from 'state-in-url/encodeState';
+
+import { form } from '../state';
+
+const state = decodeState(Astro.url.searchParams, form);
+const withName = encodeState({ ...state, name: 'Alice' }, form, Astro.url.searchParams);
+---
+
+<pre>{JSON.stringify(state)}</pre>
+<a href={`?${withName}`}>Alice</a>
+```
+
+[예제 코드](packages/example-astro/src/components/Form-for-test.tsx), [순수 Astro 페이지](packages/example-astro/src/pages/pure-astro.astro)
+
 ## 레시피
 ##### 상태의 일부를 편리하게 다루기 위한 커스텀 훅
 <details>
@@ -674,7 +851,37 @@ const tags = [
 
 ### 다른 라우터용 `useUrlStateBase` 훅
 
-다른 라우터(예: react-router 또는 tanstack router)와 함께 자체 `useUrlState` 훅을 만들기 위한 훅입니다.
+이 패키지가 진입점을 제공하지 않는 라우터(예: TanStack Router)를 위해 직접 `useUrlState` 를 만들 때 사용합니다. `push(url)` 과 `replace(url)` 을 가진 메모이즈된 객체를 넘기면 됩니다.
+
+라우터가 **전혀 없다면** 이것은 필요 없습니다. 이미 `window.history` 에 연결된 같은 훅인 [`state-in-url/react`](#react용-useurlstate-훅-라우터-없음) 를 쓰세요.
+
+```typescript
+import { useUrlStateBase } from 'state-in-url/useUrlStateBase';
+
+type FiltersState = { sort: 'name' | 'date'; page: number };
+const FILTERS_STATE: FiltersState = { sort: 'name', page: 1 };
+
+export function useFilters() {
+  const router = useYourRouter();
+  const nav = React.useMemo(
+    () => ({
+      push: (url: string) => router.navigate(url),
+      replace: (url: string) => router.navigate(url, { replace: true }),
+    }),
+    [router],
+  );
+
+  return useUrlStateBase(FILTERS_STATE, nav, ({ parse }) => parse(window.location.search));
+}
+```
+
+`useUrlState` 와 다른 점은 두 가지입니다:
+
+- `urlState`, `setUrl`, `setState` 가 아니라 `state`, `updateUrl`, `updateState` 를 반환하며, `updateUrl` 의 기본값은 push, `setUrl` 의 기본값은 replace 입니다.
+- 세 번째 인자가 초기 state 를 채웁니다. 이를 생략하면 훅이 페이지가 로드된 시점의 쿼리 문자열을 무시하므로, 공유된 링크를 열어도 기본값만 보입니다.
+
+> [!NOTE]
+> `useUrlState` 는 패키지 루트에서 내보내지 않습니다. 모든 `useUrlState` 가 특정 프레임워크에 묶여 있어 각자 자신의 진입점(`state-in-url/next`, `/react`, `/react-router`, `/react-router6`, `/remix`, `/astro`)에 있습니다. 루트 진입점에는 프레임워크와 무관한 것만 남습니다: `useSharedState`, `useUrlEncode`, `useUrlStateBase`, `useLinkProps`, `encode`/`decode`, `encodeState`/`decodeState`.
 
 [API 문서](packages/urlstate/useUrlStateBase)
 
@@ -782,7 +989,7 @@ export const useUserState = () => {
 - [x] `react-router`용 훅
 - [x] `remix`용 훅
 - [ ] `svelte`용 훅
-- [ ] `astro`용 훅
+- [x] `astro`용 훅
 - [ ] 해시에 상태를 저장하는 훅?
 
 ## 문의 및 지원