state-in-url 6.4.0 → 6.5.0

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=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` 훅과 그 외 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,8 @@ Next.js와 react-router용 `useUrlState` 훅과 그 외 JS 환경을 위한 헬
       - [예제](#예제)
     - [React-Router용 useUrlState 훅](#react-router용-useurlstate-훅)
       - [예제](#예제-1)
+    - [Astro용 useUrlState 훅](#astro용-useurlstate-훅)
+      - [예제](#예제-2)
   - [레시피](#레시피)
         - [상태의 일부를 편리하게 다루기 위한 커스텀 훅](#상태의-일부를-편리하게-다루기-위한-커스텀-훅)
         - [복잡한 상태 구조 사용](#복잡한-상태-구조-사용)
@@ -511,6 +536,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') } },
+];
+
+// 두 번째 아일랜드인 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>
@@ -782,7 +924,7 @@ export const useUserState = () => {
 - [x] `react-router`용 훅
 - [x] `remix`용 훅
 - [ ] `svelte`용 훅
-- [ ] `astro`용 훅
+- [x] `astro`용 훅
 - [ ] 해시에 상태를 저장하는 훅?
 
 ## 문의 및 지원

package/README.md

@@ -69,7 +69,7 @@ Share if it useful for you.
 Store any user state in query parameters; imagine JSON in a browser URL. All of it with keeping types and structure of data, e.g. numbers will be decoded as numbers not strings, dates as dates, etc, objects and arrays supported.
 Dead simple, fast, and with static Typescript validation. Deep links, aka URL synchronization, made easy.
 
-Contains `useUrlState` hook for Next.js and react-router, and helpers for anything else on JS.
+Contains `useUrlState` hook for Next.js, react-router, Remix and Astro, and helpers for anything else on JS.
 Since modern browsers support huge URLs and users don't care about query strings (it is a select all and copy/past workflow).
 
 Time to use query string for state management, as it was originally intended.
@@ -98,10 +98,31 @@ This library is a good alternative for NUQS.
 - **Server Side Rendering**: Can use it in Server Components, Next.js 14, 15, and 16 are supported
 - **Lightweight**: Zero dependencies, library less than 2KB
 - **DX**: Good developer experience, documentation, JSDoc comments, and examples
-- **Framework Flexibility**: Hooks for `Next.js` and `react-router`, helpers to use it with other frameworks or pure JS
+- **Framework Flexibility**: Hooks for `Next.js`, `react-router`, `Remix` and `Astro`, helpers to use it with other frameworks or pure JS
 - **Well tested**: [Unit tests and Playwright tests for Chrome/Firefox/Safari](https://github.com/asmyshlyaev177/state-in-url/actions/workflows/tests.yml)
 - **Permissive license**: MIT
 
+### Comparison with nuqs
+
+Searching for a [nuqs](https://github.com/47ng/nuqs) alternative? Both keep typed state in the query string; they differ in how much you set up and what a value can be.
+
+| What | `state-in-url` | `nuqs` |
+| --- | --- | --- |
+| Setup | None — import the hook and go | Adapter component wraps the app |
+| State shape | One typed object, like `React.useState` | Per-key values, a parser declared for each |
+| Reuse across components | Wrap the hook once — every component shares the state, no props | Extract your own hook around the parser map |
+| Nested objects and arrays | Built in — structure and types preserved | JSON parser plus your own runtime validator |
+| Dates | Preserved automatically | Built-in parser, declared per key |
+| Size, full import | ~2.9 KB gzipped | ~6.7 KB gzipped |
+| Runtime dependencies | None | One |
+| Routers | Next.js, React Router v6/v7, Remix, Astro, plain JS helpers | Next.js, React Router, Remix, TanStack Router, plain React |
+
+Sizes: whole-library import, esbuild minify + gzip, measured August 2026 against nuqs 2.10.1.
+
+nuqs is a fine library — reach for it when you want each value as its own readable query param, or you are on TanStack Router. Reach for state-in-url when you want a whole typed object in the URL with zero setup.
+
+The full comparison — the same feature built in both, other alternatives (TanStack Router, use-query-params) and migration notes — lives at <https://state-in-url.dev/vs/nuqs>.
+
 ## Table of content
 
 <!-- toc:start -->
@@ -111,6 +132,7 @@ This library is a good alternative for NUQS.
   - [Why use `state-in-url`?](#why-use-state-in-url)
     - [Use cases](#use-cases)
     - [Features](#features)
+    - [Comparison with nuqs](#comparison-with-nuqs)
   - [Table of content](#table-of-content)
   - [installation](#installation)
     - [1. Install package](#1-install-package)
@@ -127,6 +149,8 @@ This library is a good alternative for NUQS.
       - [Example](#example)
     - [useUrlState hook for React-Router](#useurlstate-hook-for-react-router)
       - [Example](#example-1)
+    - [useUrlState hook for Astro](#useurlstate-hook-for-astro)
+      - [Example](#example-2)
   - [Recipes](#recipes)
         - [Custom hook to work with slice of state conveniently](#custom-hook-to-work-with-slice-of-state-conveniently)
         - [With complex state shape](#with-complex-state-shape)
@@ -515,6 +539,123 @@ const tags = [
 
 [Example code](packages/example-react-router6/src/Form-for-test.tsx)
 
+### useUrlState hook for Astro
+
+For React islands. Astro has no client-side router by default, so the hook writes the URL with `window.history` and reads it back on back/forward and on any other `pushState`/`replaceState`, Astro's own `<ClientRouter />` included. Islands on a page share the state, with nothing to wrap them in.
+
+[API Docs](packages/urlstate/astro/useUrlState)
+
+#### Example
+
+```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 } }[];
+};
+```
+
+The page must be rendered on demand (`output: 'server'`, or `export const prerender = false` on the page, with an adapter): a prerendered page has no request, so the island gets `{}` and reads the URL after hydration.
+
+```astro
+---
+// src/pages/index.astro
+import { Form } from '../components/Form';
+import { Status } from '../components/Status';
+
+// The server render matches the URL, so hydration has nothing to correct.
+// A plain object: island props are serialized, URLSearchParams is not.
+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 })) }}
+        // Can update state immediately but sync change to url as needed
+        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, a second island, reads the same state
+export function Status({ searchParams }: { searchParams?: Record<string, string> }) {
+  const { urlState } = useUrlState(form, { searchParams });
+  return <pre>{JSON.stringify(urlState, null, 2)}</pre>;
+}
+```
+
+Preact islands work the same way: with `@astrojs/preact` and `compat: true`, `react` resolves to `preact/compat` in both the server and the client build, and the import above is unchanged.
+
+Without islands, on a page with no client framework at all, the same state lives in the frontmatter through [`decodeState` and `encodeState`](#encodestate-and-decodestate-helpers):
+
+```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>
+```
+
+[Example code](packages/example-astro/src/components/Form-for-test.tsx), [pure Astro page](packages/example-astro/src/pages/pure-astro.astro)
+
 ## Recipes
 ##### Custom hook to work with slice of state conveniently
 <details>
@@ -787,7 +928,7 @@ See [Contributing doc](CONTRIBUTING.md)
 - [x] hook for `react-router`
 - [x] hook for `remix`
 - [ ] hook for `svelte`
-- [ ] hook for `astro`
+- [x] hook for `astro`
 - [ ] hook for store state in hash ?
 
 ## Contact & Support

package/README.pt-BR.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) · [Français](./README.fr.md) · [Tiếng Việt](./README.vi.md)
-<!-- i18n:meta locale=pt-BR source=README.md source-blob=bbf45a10aae9e88f68b27d84f51ee3e7e8a1e436 status=translated -->
+<!-- i18n:meta locale=pt-BR source=README.md source-blob=4d98ba970e6aab8f29987fbcba29fb6c61c2fc67 status=translated -->
 <!-- i18n:end -->
 
 <div align="center">
@@ -69,7 +69,7 @@ Compartilhe se for útil para você.
 Armazene qualquer estado de usuário nos parâmetros de consulta; imagine JSON na URL de um navegador. Tudo isso mantendo os tipos e a estrutura dos dados: por exemplo, números serão decodificados como números e não como strings, datas como datas, etc., objetos e arrays são suportados.
 Extremamente simples, rápido e com validação estática de TypeScript. Links profundos, ou seja, sincronização de URL, facilitados.
 
-Contém o hook `useUrlState` para Next.js e react-router, e helpers para qualquer outra coisa em JS.
+Contém o hook `useUrlState` para Next.js, react-router, Remix e Astro, e helpers para qualquer outra coisa em JS.
 Como os navegadores modernos suportam URLs enormes e os usuários não se importam com as strings de consulta (é um fluxo de selecionar tudo e copiar/colar).
 
 É hora de usar a string de consulta para gerenciamento de estado, como foi originalmente planejado.
@@ -98,10 +98,32 @@ Esta biblioteca é uma boa alternativa ao NUQS.
 - **Renderização no servidor**: Pode ser usado em componentes de servidor, Next.js 14, 15 e 16 são suportados
 - **Leve**: Zero dependências, biblioteca com menos de 2KB
 - **DX**: Boa experiência de desenvolvimento, documentação, comentários JSDoc e exemplos
-- **Flexibilidade de frameworks**: Hooks para `Next.js` e `react-router`, helpers para usar com outros frameworks ou JS puro
+- **Flexibilidade de frameworks**: Hooks para `Next.js`, `react-router`, `Remix` e `Astro`, helpers para usar com outros frameworks ou JS puro
 - **Bem testada**: [Testes unitários e testes Playwright para Chrome/Firefox/Safari](https://github.com/asmyshlyaev177/state-in-url/actions/workflows/tests.yml)
 - **Licença permissiva**: MIT
 
+### Comparação com o nuqs
+
+Procurando uma alternativa ao [nuqs](https://github.com/47ng/nuqs)? Ambas guardam estado tipado na query string; diferem em quanta configuração exigem e no que um valor pode ser.
+
+| O quê | `state-in-url` | `nuqs` |
+| --- | --- | --- |
+| Configuração | Nenhuma — importe o hook e pronto | Um componente adaptador envolve o app |
+| Formato do estado | Um objeto tipado, como `React.useState` | Valores por chave, com um parser declarado para cada uma |
+| Reuso entre componentes | Envolva o hook uma vez — cada componente compartilha o estado, sem props | Você extrai seu próprio hook em volta do mapa de parsers |
+| Objetos e arrays aninhados | Nativo — estrutura e tipos preservados | Parser JSON mais seu próprio validador |
+| Datas | Preservadas automaticamente | Parser embutido, declarado por chave |
+| Tamanho, import completo | ~2,9 KB gzip | ~6,7 KB gzip |
+| Dependências em runtime | Nenhuma | Uma |
+| Roteadores | Next.js, React Router v6/v7, Remix, Astro, helpers para JS puro | Next.js, React Router, Remix, TanStack Router, React puro |
+
+Tamanhos: import da biblioteca inteira, esbuild minify + gzip, medido em agosto de 2026 contra o nuqs 2.10.1.
+
+nuqs é uma boa biblioteca — prefira-o se quiser cada valor como seu próprio query param legível, ou se usa TanStack Router. Prefira state-in-url quando quiser um objeto tipado inteiro na URL sem configuração.
+
+
+A comparação completa — a mesma feature nas duas, outras alternativas (TanStack Router, use-query-params) e notas de migração — está em <https://state-in-url.dev/vs/nuqs>.
+
 ## Índice
 
 <!-- toc:start -->
@@ -111,6 +133,7 @@ Esta biblioteca é uma boa alternativa ao NUQS.
   - [Por que usar `state-in-url`?](#por-que-usar-state-in-url)
     - [Casos de uso](#casos-de-uso)
     - [Recursos](#recursos)
+    - [Comparação com o nuqs](#comparação-com-o-nuqs)
   - [Índice](#índice)
   - [Instalação](#instalação)
     - [1. Instalar o pacote](#1-instalar-o-pacote)
@@ -127,6 +150,8 @@ Esta biblioteca é uma boa alternativa ao NUQS.
       - [Exemplo](#exemplo)
     - [Hook useUrlState para React-Router](#hook-useurlstate-para-react-router)
       - [Exemplo](#exemplo-1)
+    - [Hook useUrlState para Astro](#hook-useurlstate-para-astro)
+      - [Exemplo](#exemplo-2)
   - [Receitas](#receitas)
         - [Hook personalizado para trabalhar convenientemente com uma fatia do estado](#hook-personalizado-para-trabalhar-convenientemente-com-uma-fatia-do-estado)
         - [Com forma de estado complexa](#com-forma-de-estado-complexa)
@@ -515,6 +540,123 @@ const tags = [
 
 [Exemplo de código](packages/example-react-router6/src/Form-for-test.tsx)
 
+### Hook useUrlState para Astro
+
+Para ilhas React. O Astro não tem um router no lado do cliente por padrão, então o hook escreve a URL com `window.history` e a lê de volta ao navegar para trás/para frente e em qualquer outro `pushState`/`replaceState`, incluindo o próprio `<ClientRouter />` do Astro. As ilhas de uma página compartilham o estado, sem precisar envolvê-las em nada.
+
+[Documentação da API](packages/urlstate/astro/useUrlState)
+
+#### Exemplo
+
+```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 } }[];
+};
+```
+
+A página precisa ser renderizada sob demanda (`output: 'server'`, ou `export const prerender = false` na página, com um adapter): uma página pré-renderizada não tem requisição, então a ilha recebe `{}` e lê a URL após a hidratação.
+
+```astro
+---
+// src/pages/index.astro
+import { Form } from '../components/Form';
+import { Status } from '../components/Status';
+
+// A renderização no servidor corresponde à URL, então a hidratação não tem nada a corrigir.
+// Um objeto simples: as props de ilhas são serializadas, URLSearchParams não.
+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 })) }}
+        // Pode atualizar o estado imediatamente, mas sincronizar a alteração com a url conforme necessário
+        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, uma segunda ilha, lê o mesmo estado
+export function Status({ searchParams }: { searchParams?: Record<string, string> }) {
+  const { urlState } = useUrlState(form, { searchParams });
+  return <pre>{JSON.stringify(urlState, null, 2)}</pre>;
+}
+```
+
+As ilhas Preact funcionam da mesma forma: com `@astrojs/preact` e `compat: true`, `react` resolve para `preact/compat` tanto no build do servidor quanto no do cliente, e o import acima permanece inalterado.
+
+Sem ilhas, em uma página sem nenhum framework no cliente, o mesmo estado vive no frontmatter por meio de [`decodeState` e `encodeState`](#helpers-encodestate-e-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>
+```
+
+[Exemplo de código](packages/example-astro/src/components/Form-for-test.tsx), [página em Astro puro](packages/example-astro/src/pages/pure-astro.astro)
+
 ## Receitas
 ##### Hook personalizado para trabalhar convenientemente com uma fatia do estado
 <details>
@@ -787,7 +929,7 @@ Veja o [documento de contribuição](CONTRIBUTING.md)
 - [x] hook para `react-router`
 - [x] hook para `remix`
 - [ ] hook para `svelte`
-- [ ] hook para `astro`
+- [x] hook para `astro`
 - [ ] hook para armazenar estado no hash ?
 
 ## Contato e suporte