state-in-url 6.4.0 → 6.5.0

package/README.es.md

@@ -1,6 +1,6 @@
 <!-- i18n:start -->
 [English](./README.md) · [简体中文](./README.zh-CN.md) · [日本語](./README.ja.md) · [한국어](./README.ko.md) · [Русский](./README.ru.md) · Español · [Português (BR)](./README.pt-BR.md) · [Français](./README.fr.md) · [Tiếng Việt](./README.vi.md)
-<!-- i18n:meta locale=es source=README.md source-blob=bbf45a10aae9e88f68b27d84f51ee3e7e8a1e436 status=translated -->
+<!-- i18n:meta locale=es source=README.md source-blob=4d98ba970e6aab8f29987fbcba29fb6c61c2fc67 status=translated -->
 <!-- i18n:end -->
 
 <div align="center">
@@ -69,7 +69,7 @@ Comparte si te resulta útil.
 Guarda cualquier estado de usuario en los parámetros de consulta; imagina JSON en la URL de un navegador. Todo ello manteniendo los tipos y la estructura de los datos: por ejemplo, los números se decodificarán como números y no como cadenas, las fechas como fechas, etc.; se admiten objetos y matrices.
 Simple a más no poder, rápido y con validación estática de TypeScript. Los enlaces profundos, es decir, la sincronización de URL, se vuelven fáciles.
 
-Incluye el hook `useUrlState` para Next.js y react-router, y helpers para cualquier otra cosa en JS.
+Incluye el hook `useUrlState` para Next.js, react-router, Remix y Astro, y helpers para cualquier otra cosa en JS.
 Como los navegadores modernos soportan URLs enormes y a los usuarios no les importan las cadenas de consulta (es un flujo de seleccionar todo y copiar/pegar).
 
 Es hora de usar la cadena de consulta para gestionar el estado, como se pensó originalmente.
@@ -98,10 +98,32 @@ Esta biblioteca es una buena alternativa a NUQS.
 - **Renderizado en el servidor**: Se puede usar en componentes de servidor, se soportan Next.js 14, 15 y 16
 - **Ligero**: Cero dependencias, biblioteca de menos de 2KB
 - **DX**: Buena experiencia de desarrollo, documentación, comentarios JSDoc y ejemplos
-- **Flexibilidad de frameworks**: Hooks para `Next.js` y `react-router`, helpers para usarla con otros frameworks o JS puro
+- **Flexibilidad de frameworks**: Hooks para `Next.js`, `react-router`, `Remix` y `Astro`, helpers para usarla con otros frameworks o JS puro
 - **Bien probada**: [Pruebas unitarias y pruebas de Playwright para Chrome/Firefox/Safari](https://github.com/asmyshlyaev177/state-in-url/actions/workflows/tests.yml)
 - **Licencia permisiva**: MIT
 
+### Comparación con nuqs
+
+¿Buscas una alternativa a [nuqs](https://github.com/47ng/nuqs)? Ambas guardan estado tipado en la query string; difieren en cuánto hay que configurar y en qué puede ser un valor.
+
+| Qué | `state-in-url` | `nuqs` |
+| --- | --- | --- |
+| Configuración | Ninguna — importa el hook y listo | Un componente adaptador envuelve la app |
+| Forma del estado | Un objeto tipado, como `React.useState` | Valores por clave, con un parser declarado para cada una |
+| Reutilización entre componentes | Envuelve el hook una vez — cada componente comparte el estado, sin props | Extraes tu propio hook alrededor del mapa de parsers |
+| Objetos y arrays anidados | Integrado — estructura y tipos se conservan | Parser JSON más tu propio validador |
+| Fechas | Se conservan automáticamente | Parser integrado, declarado por clave |
+| Tamaño, import completo | ~2,9 KB gzip | ~6,7 KB gzip |
+| Dependencias en runtime | Ninguna | Una |
+| Routers | Next.js, React Router v6/v7, Remix, Astro, helpers para JS puro | Next.js, React Router, Remix, TanStack Router, React puro |
+
+Tamaños: import de toda la librería, esbuild minify + gzip, medido en agosto de 2026 contra nuqs 2.10.1.
+
+nuqs es una buena librería: elígela si quieres cada valor como su propio query param legible o usas TanStack Router. Elige state-in-url cuando quieras un objeto tipado completo en la URL sin configuración.
+
+
+La comparación completa — la misma feature en ambas, otras alternativas (TanStack Router, use-query-params) y notas de migración — está en <https://state-in-url.dev/vs/nuqs>.
+
 ## Tabla de contenido
 
 <!-- toc:start -->
@@ -111,6 +133,7 @@ Esta biblioteca es una buena alternativa a NUQS.
   - [¿Por qué usar `state-in-url`?](#por-qué-usar-state-in-url)
     - [Casos de uso](#casos-de-uso)
     - [Características](#características)
+    - [Comparación con nuqs](#comparación-con-nuqs)
   - [Tabla de contenido](#tabla-de-contenido)
   - [Instalación](#instalación)
     - [1. Instalar el paquete](#1-instalar-el-paquete)
@@ -127,6 +150,8 @@ Esta biblioteca es una buena alternativa a NUQS.
       - [Ejemplo](#ejemplo)
     - [Hook useUrlState para React-Router](#hook-useurlstate-para-react-router)
       - [Ejemplo](#ejemplo-1)
+    - [Hook useUrlState para Astro](#hook-useurlstate-para-astro)
+      - [Ejemplo](#ejemplo-2)
   - [Recetas](#recetas)
         - [Hook personalizado para trabajar cómodamente con una porción del estado](#hook-personalizado-para-trabajar-cómodamente-con-una-porción-del-estado)
         - [Con una forma de estado compleja](#con-una-forma-de-estado-compleja)
@@ -515,6 +540,123 @@ const tags = [
 
 [Ejemplo de código](packages/example-react-router6/src/Form-for-test.tsx)
 
+### Hook useUrlState para Astro
+
+Para islas de React. Astro no tiene router del lado del cliente por defecto, así que el hook escribe la URL con `window.history` y la vuelve a leer al navegar atrás/adelante y en cualquier otro `pushState`/`replaceState`, incluido el propio `<ClientRouter />` de Astro. Las islas de una página comparten el estado, sin nada que las envuelva.
+
+[Documentación de la API](packages/urlstate/astro/useUrlState)
+
+#### Ejemplo
+
+```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 } }[];
+};
+```
+
+La página debe renderizarse bajo demanda (`output: 'server'`, o `export const prerender = false` en la página, con un adaptador): una página prerenderizada no tiene petición, así que la isla recibe `{}` y lee la URL después de la hidratación.
+
+```astro
+---
+// src/pages/index.astro
+import { Form } from '../components/Form';
+import { Status } from '../components/Status';
+
+// El renderizado en el servidor coincide con la URL, así que la hidratación no tiene nada que corregir.
+// Un objeto plano: las props de las islas se serializan, URLSearchParams no.
+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 })) }}
+        // Puede actualizar el estado inmediatamente pero sincronizar el cambio con la url según sea necesario
+        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, una segunda isla, lee el mismo estado
+export function Status({ searchParams }: { searchParams?: Record<string, string> }) {
+  const { urlState } = useUrlState(form, { searchParams });
+  return <pre>{JSON.stringify(urlState, null, 2)}</pre>;
+}
+```
+
+Las islas de Preact funcionan igual: con `@astrojs/preact` y `compat: true`, `react` se resuelve a `preact/compat` tanto en la compilación del servidor como en la del cliente, y el import de arriba no cambia.
+
+Sin islas, en una página sin ningún framework de cliente, el mismo estado vive en el frontmatter a través de [`decodeState` y `encodeState`](#helpers-encodestate-y-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>
+```
+
+[Ejemplo de código](packages/example-astro/src/components/Form-for-test.tsx), [página en Astro puro](packages/example-astro/src/pages/pure-astro.astro)
+
 ## Recetas
 ##### Hook personalizado para trabajar cómodamente con una porción del estado
 <details>
@@ -787,7 +929,7 @@ Consulta el [documento de contribución](CONTRIBUTING.md)
 - [x] hook para `react-router`
 - [x] hook para `remix`
 - [ ] hook para `svelte`
-- [ ] hook para `astro`
+- [x] hook para `astro`
 - [ ] hook para guardar el estado en el hash ?
 
 ## Contacto y soporte

package/README.fr.md

@@ -1,6 +1,6 @@
 <!-- i18n:start -->
 [English](./README.md) · [简体中文](./README.zh-CN.md) · [日本語](./README.ja.md) · [한국어](./README.ko.md) · [Русский](./README.ru.md) · [Español](./README.es.md) · [Português (BR)](./README.pt-BR.md) · Français · [Tiếng Việt](./README.vi.md)
-<!-- i18n:meta locale=fr source=README.md source-blob=bbf45a10aae9e88f68b27d84f51ee3e7e8a1e436 status=translated -->
+<!-- i18n:meta locale=fr source=README.md source-blob=4d98ba970e6aab8f29987fbcba29fb6c61c2fc67 status=translated -->
 <!-- i18n:end -->
 
 <div align="center">
@@ -69,7 +69,7 @@ Partagez si cela vous est utile.
 Stockez n'importe quel état utilisateur dans les paramètres de requête ; imaginez du JSON dans une URL de navigateur. Tout cela en conservant les types et la structure des données : par exemple, les nombres seront décodés comme des nombres et non comme des chaînes, les dates comme des dates, etc., les objets et les tableaux sont pris en charge.
 Extrêmement simple, rapide et avec une validation TypeScript statique. Les liens profonds, autrement dit la synchronisation d'URL, deviennent faciles.
 
-Contient le hook `useUrlState` pour Next.js et react-router, ainsi que des helpers pour tout le reste en JS.
+Contient le hook `useUrlState` pour Next.js, react-router, Remix et Astro, ainsi que des helpers pour tout le reste en JS.
 Comme les navigateurs modernes prennent en charge d'énormes URL et que les utilisateurs ne se soucient pas des chaînes de requête (c'est un flux de travail « tout sélectionner et copier/coller »).
 
 Il est temps d'utiliser la chaîne de requête pour la gestion d'état, comme cela était prévu à l'origine.
@@ -98,10 +98,32 @@ Cette bibliothèque est une bonne alternative à NUQS.
 - **Rendu côté serveur** : Utilisable dans les composants serveur, Next.js 14, 15 et 16 sont pris en charge
 - **Léger** : Zéro dépendance, bibliothèque de moins de 2KB
 - **DX** : Bonne expérience de développement, documentation, commentaires JSDoc et exemples
-- **Flexibilité de frameworks** : Hooks pour `Next.js` et `react-router`, helpers pour l'utiliser avec d'autres frameworks ou du JS pur
+- **Flexibilité de frameworks** : Hooks pour `Next.js`, `react-router`, `Remix` et `Astro`, helpers pour l'utiliser avec d'autres frameworks ou du JS pur
 - **Bien testée** : [Tests unitaires et tests Playwright pour Chrome/Firefox/Safari](https://github.com/asmyshlyaev177/state-in-url/actions/workflows/tests.yml)
 - **Licence permissive** : MIT
 
+### Comparaison avec nuqs
+
+Vous cherchez une alternative à [nuqs](https://github.com/47ng/nuqs) ? Les deux gardent un état typé dans la query string ; elles diffèrent par la configuration requise et par ce qu’une valeur peut être.
+
+| Quoi | `state-in-url` | `nuqs` |
+| --- | --- | --- |
+| Mise en place | Aucune — importez le hook et c’est parti | Un composant adaptateur enveloppe l’application |
+| Forme de l’état | Un objet typé, comme `React.useState` | Valeurs par clé, un parseur déclaré pour chacune |
+| Réutilisation entre composants | Enveloppez le hook une fois — chaque composant partage l’état, sans props | Vous extrayez votre propre hook autour de la table de parseurs |
+| Objets et tableaux imbriqués | Intégré — structure et types préservés | Parseur JSON plus votre propre validateur |
+| Dates | Préservées automatiquement | Parseur intégré, déclaré par clé |
+| Taille, import complet | ~2,9 Ko gzip | ~6,7 Ko gzip |
+| Dépendances au runtime | Aucune | Une |
+| Routeurs | Next.js, React Router v6/v7, Remix, Astro, helpers pour JS pur | Next.js, React Router, Remix, TanStack Router, React pur |
+
+Tailles : import de la bibliothèque entière, esbuild minify + gzip, mesuré en août 2026 face à nuqs 2.10.1.
+
+nuqs est une bonne bibliothèque — choisissez-la pour un query param lisible par valeur, ou si vous êtes sur TanStack Router. Choisissez state-in-url pour un objet typé complet dans l’URL, sans configuration.
+
+
+La comparaison complète — la même fonctionnalité dans les deux, d’autres alternatives (TanStack Router, use-query-params) et des notes de migration — se trouve sur <https://state-in-url.dev/vs/nuqs>.
+
 ## Table des matières
 
 <!-- toc:start -->
@@ -111,6 +133,7 @@ Cette bibliothèque est une bonne alternative à NUQS.
   - [Pourquoi utiliser `state-in-url` ?](#pourquoi-utiliser-state-in-url-)
     - [Cas d'utilisation](#cas-dutilisation)
     - [Fonctionnalités](#fonctionnalités)
+    - [Comparaison avec nuqs](#comparaison-avec-nuqs)
   - [Table des matières](#table-des-matières)
   - [Installation](#installation)
     - [1. Installer le paquet](#1-installer-le-paquet)
@@ -127,6 +150,8 @@ Cette bibliothèque est une bonne alternative à NUQS.
       - [Exemple](#exemple)
     - [Hook useUrlState pour React-Router](#hook-useurlstate-pour-react-router)
       - [Exemple](#exemple-1)
+    - [Hook useUrlState pour Astro](#hook-useurlstate-pour-astro)
+      - [Exemple](#exemple-2)
   - [Recettes](#recettes)
         - [Hook personnalisé pour travailler confortablement avec une tranche d'état](#hook-personnalisé-pour-travailler-confortablement-avec-une-tranche-détat)
         - [Avec une forme d'état complexe](#avec-une-forme-détat-complexe)
@@ -515,6 +540,123 @@ const tags = [
 
 [Exemple de code](packages/example-react-router6/src/Form-for-test.tsx)
 
+### Hook useUrlState pour Astro
+
+Pour les îlots React. Astro n'a pas de routeur côté client par défaut, donc le hook écrit l'URL avec `window.history` et la relit lors des navigations précédent/suivant et lors de tout autre `pushState`/`replaceState`, y compris le `<ClientRouter />` d'Astro. Les îlots d'une page partagent l'état, sans avoir à les envelopper dans quoi que ce soit.
+
+[Documentation de l'API](packages/urlstate/astro/useUrlState)
+
+#### Exemple
+
+```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 } }[];
+};
+```
+
+La page doit être rendue à la demande (`output: 'server'`, ou `export const prerender = false` sur la page, avec un adaptateur) : une page prérendue n'a pas de requête, donc l'îlot reçoit `{}` et lit l'URL après l'hydratation.
+
+```astro
+---
+// src/pages/index.astro
+import { Form } from '../components/Form';
+import { Status } from '../components/Status';
+
+// Le rendu serveur correspond à l'URL, donc l'hydratation n'a rien à corriger.
+// Un objet simple : les props d'îlot sont sérialisées, URLSearchParams ne l'est pas.
+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 })) }}
+        // Peut mettre à jour l'état immédiatement mais synchroniser le changement avec l'url selon les besoins
+        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, un second îlot, lit le même état
+export function Status({ searchParams }: { searchParams?: Record<string, string> }) {
+  const { urlState } = useUrlState(form, { searchParams });
+  return <pre>{JSON.stringify(urlState, null, 2)}</pre>;
+}
+```
+
+Les îlots Preact fonctionnent de la même manière : avec `@astrojs/preact` et `compat: true`, `react` est résolu vers `preact/compat` aussi bien dans le build serveur que dans le build client, et l'import ci-dessus reste inchangé.
+
+Sans îlots, sur une page sans aucun framework client, le même état vit dans le frontmatter via [`decodeState` et `encodeState`](#helpers-encodestate-et-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>
+```
+
+[Exemple de code](packages/example-astro/src/components/Form-for-test.tsx), [page Astro pure](packages/example-astro/src/pages/pure-astro.astro)
+
 ## Recettes
 ##### Hook personnalisé pour travailler confortablement avec une tranche d'état
 <details>
@@ -787,7 +929,7 @@ Voir le [document de contribution](CONTRIBUTING.md)
 - [x] hook pour `react-router`
 - [x] hook pour `remix`
 - [ ] hook pour `svelte`
-- [ ] hook pour `astro`
+- [x] hook pour `astro`
 - [ ] hook pour stocker l'état dans le hash ?
 
 ## Contact et support

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=4d98ba970e6aab8f29987fbcba29fb6c61c2fc67 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,8 @@ Next.js と react-router 用の `useUrlState` フックと、その他あらゆ
       - [例](#例)
     - [React-Router 向け useUrlState フック](#react-router-向け-useurlstate-フック)
       - [例](#例-1)
+    - [Astro 向け useUrlState フック](#astro-向け-useurlstate-フック)
+      - [例](#例-2)
   - [レシピ](#レシピ)
         - [状態の一部を便利に扱うカスタムフック](#状態の一部を便利に扱うカスタムフック)
         - [複雑な状態の形を使用](#複雑な状態の形を使用)
@@ -515,6 +540,123 @@ const tags = [
 
 [サンプルコード](packages/example-react-router6/src/Form-for-test.tsx)
 
+### 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>
@@ -787,7 +929,7 @@ export const useUserState = () => {
 - [x] `react-router` 向けフック
 - [x] `remix` 向けフック
 - [ ] `svelte` 向けフック
-- [ ] `astro` 向けフック
+- [x] `astro` 向けフック
 - [ ] ハッシュに状態を保存するフック?
 
 ## 連絡先とサポート