docs: astro block on landing

Author: asmyshlyaev177

AGENTS.md

@@ -146,7 +146,7 @@ nothing but the `(tests)` group). It audits the production build: `build:demo`
 `dist/`) then `next start --port 3012`. Port 3012, not the demo's own 3002, so a
 server left over from `pnpm run dev` cannot be silently accepted in place of it.
 
-**Only the three public pages** — `/`, `/react-router`, `/remix`. The app also
+**Only the four public pages** — `/`, `/react-router`, `/remix`, `/astro`. The app also
 serves `/useUrlState`, `/test-ssr` and the rest of the `(tests)` group, but those
 are e2e fixtures that happen to be deployed: they exist to be asserted against,
 not read, and several render in ways no real page would.
@@ -176,7 +176,7 @@ answers agents in four overlapping ways — they disagree about which to try:
 | --- | --- |
 | `/llms.txt` | `public/llms.txt` — the single source |
 | `/` under `Accept: text/markdown`, or a known agent user-agent — 307 to `/index.md` | `src/proxy.ts` |
-| `/index.md`, `/react-router.md`, `/remix.md` | `src/app/<route>.md/route.ts`, all three through `src/app/llmsTxtResponse.ts` |
+| `/index.md`, `/react-router.md`, `/remix.md`, `/astro.md` | `src/app/<route>.md/route.ts`, all four through `src/app/llmsTxtResponse.ts` |
 | `<link rel="alternate">` and a `Link:` response header | `src/app/seoStuff.ts` (`markdownAlternates`), `next.config.mjs` |
 
 All three `.md` mirrors serve the same document, deliberately: this site is one

packages/example-nextjs16/next.config.mjs

@@ -128,7 +128,7 @@ const nextConfig = {
     // an `age` far past `s-maxage=600` — the client never sees a fresh response
     // and `<Link>` prefetch revalidates on a loop, measured at ~26 requests a
     // second from one idle tab. Its layout's `revalidate` caches it for a week.
-    const demoPages = ['', '/react-router', '/remix'];
+    const demoPages = ['', '/react-router', '/remix', '/astro'];
     const pages = [...demoPages, '/vs/nuqs'];
     const prefixes = ['', ...LOCALES.map((locale) => `/${locale.dir}`)];
 

packages/example-nextjs16/public/llms.txt

@@ -1,6 +1,6 @@
 # state-in-url
 
-> A React hook library for storing typed, JSON-serializable state in URL query parameters. ~2 KB, zero runtime deps. Supports the Next.js App Router (14/15/16), React Router 6/7, Remix 2, and plain React. MIT licensed.
+> A React hook library for storing typed, JSON-serializable state in URL query parameters. ~2 KB, zero runtime deps. Supports the Next.js App Router (14/15/16), React Router 6/7, Remix 2, Astro (React/Preact islands), and plain React. MIT licensed.
 
 Last updated: 2026-08-31. Canonical: <https://state-in-url.dev/llms.txt>.
 
@@ -25,6 +25,7 @@ Available skills (under `node_modules/state-in-url/skills/`):
 | `input-handling` | core | Text inputs / sliders / fast-changing controls |
 | `nextjs-ssr` | framework | Next.js App Router: `searchParams` forwarding, Proxy for layouts |
 | `react-router-remix-setup` | framework | React Router v6/v7 or Remix v2 setup |
+| `astro-setup` | framework | Astro: React/Preact islands with the `searchParams` prop, or no client framework via `encodeState`/`decodeState` |
 | `form-library-integration` | composition | Pairing with `react-hook-form` (or formik) |
 | `shared-state-no-url` | core | `useSharedState` — cross-component state without URL sync |
 
@@ -36,7 +37,7 @@ Full page: <https://state-in-url.dev/vs/nuqs> (Markdown: /vs/nuqs.md). Sizes: wh
 
 | Library | Setup | Nested objects and dates | Size | Pick it when |
 |---|---|---|---|---|
-| state-in-url | None - import the hook | Preserved automatically, types included | ~2.9 KB gzip, zero deps | One typed object, zero setup, on Next.js / React Router / Remix |
+| state-in-url | None - import the hook | Preserved automatically, types included | ~2.9 KB gzip, zero deps | One typed object, zero setup, on Next.js / React Router / Remix / Astro |
 | nuqs | Adapter component, parser per key | JSON parser plus your own validator | ~6.7 KB gzip, one dep | Each value as its own readable query param |
 | TanStack Router | validateSearch on each route | JSON-first; dates need custom serialization | Built into the router | You are on TanStack Router |
 | use-query-params | Provider plus router adapter, param config per key | Via a JSON param type, loosely typed | ~4.4 KB gzip + serialize-query-params | A codebase already built on it |
@@ -57,6 +58,7 @@ Full page: <https://state-in-url.dev/vs/nuqs> (Markdown: /vs/nuqs.md). Sizes: wh
 | React Router | v7 | `state-in-url/react-router` |
 | React Router | v6 | `state-in-url/react-router6` |
 | Remix | v2 | `state-in-url/remix` |
+| Astro | React or Preact (compat) islands, on-demand rendered pages | `state-in-url/astro` |
 | Framework-agnostic | — | `state-in-url` (`useSharedState`), `state-in-url/encodeState` |
 
 Pages Router is **not** supported.
@@ -228,6 +230,29 @@ import { useUrlState } from 'state-in-url/remix';          // Remix v2
 setUrl({ tab: 'b' }, { replace: false, preventScrollReset: true });
 ```
 
+## Astro
+
+Same API inside a React (or Preact `compat: true`) island. Pass `Object.fromEntries(Astro.url.searchParams)` as the island's `searchParams` prop so the server render matches the URL — a plain object, `URLSearchParams` serializes to `{}`. The page must render on demand (`output: 'server'` or `export const prerender = false`, with an adapter). Islands sharing one default-state object share state; there is no client router, so `replace` defaults to `true`.
+
+```astro
+---
+import { Filters } from '../components/Filters';
+const searchParams = Object.fromEntries(Astro.url.searchParams);
+---
+<Filters client:load searchParams={searchParams} />
+```
+
+```typescript
+import { useUrlState } from 'state-in-url/astro';
+
+export function Filters({ searchParams }: { searchParams?: Record<string, string> }) {
+  const { urlState, setUrl } = useUrlState(FILTERS_STATE, { searchParams });
+  ...
+}
+```
+
+No client framework at all: `decodeState(Astro.url.searchParams, FILTERS_STATE)` and `encodeState(next, FILTERS_STATE, Astro.url.searchParams)` from `state-in-url/encodeState` do the same job in the frontmatter, for links.
+
 ## react-hook-form integration
 
 Share one defaults object, hydrate `useForm` from `urlState`, push form changes back via RHF `subscribe()` (not `watch()`):
@@ -278,7 +303,7 @@ Same module-scoped default-state-identity rule. Use only when URL sync is explic
 
 - Full README (humans): https://github.com/asmyshlyaev177/state-in-url/blob/master/README.md
 - URL size limits: https://github.com/asmyshlyaev177/state-in-url/blob/master/Limits.md
-- Working examples per framework: `packages/example-nextjs{14,15,16}`, `packages/example-react-router{6,7}`, `packages/example-remix2`
+- Working examples per framework: `packages/example-nextjs{14,15,16}`, `packages/example-react-router{6,7}`, `packages/example-remix2`, `packages/example-astro`
 - JSDoc comments are available in IDE for all exported functions
 
 ## Contact

packages/example-nextjs16/src/app/(en)/astro/CodeBlocksAstro.tsx

@@ -0,0 +1,111 @@
+import { File } from '../../components/File';
+import { CodeBlockState } from '../../CodeBlockState';
+import { tooltips } from '../../tooltips';
+import type { QuickStartCopy } from '../../i18n/copy/types';
+
+export const CodeBlocksAstro = ({ copy }: { copy: QuickStartCopy }) => {
+  return (
+    <div className="flex flex-col gap-4">
+      <h3 className="font-display text-ink text-3xl font-bold">{copy.title}</h3>
+      <div className="codeTitle">{copy.stateStep}</div>
+      <CodeBlockState />
+
+      <div className="codeTitle">{copy.hookStep}</div>
+      <File
+        name="useFormState"
+        matchers={tooltips}
+        content={`import { useUrlState } from 'state-in-url/astro';// [!code highlight:1]
+import { form } from './form';
+
+// One hook per feature - the whole API for this state.
+// searchParams is the island prop: with it the server render matches the URL
+export const useFormState = (searchParams?: Record<string, string>) =>
+  useUrlState(form, { searchParams });// [!code highlight:1]`}
+      />
+
+      <div className="codeTitle">{copy.componentsStep}</div>
+      <File
+        name="index.astro"
+        matchers={tooltips}
+        content={`---
+import { ComponentA } from '../components/ComponentA';
+import { ComponentB } from '../components/ComponentB';
+
+// A plain object: island props are serialized, URLSearchParams is not
+const searchParams = Object.fromEntries(Astro.url.searchParams);// [!code highlight:1]
+---
+
+<ComponentA client:load searchParams={searchParams} />
+<ComponentB client:load searchParams={searchParams} />`}
+      />
+      <File
+        name="ComponentA"
+        matchers={tooltips}
+        content={`import { useFormState } from './useFormState';// [!code highlight:1]
+
+export const ComponentA = ({ searchParams }: { searchParams?: Record<string, string> }) => {
+  // see docs for all possible params https://github.com/asmyshlyaev177/state-in-url/tree/master/packages/urlstate/astro/useUrlState
+  const { urlState, setUrl, setState } = useFormState(searchParams);// [!code highlight:1]
+
+  return <>
+    <input
+      id="name"
+      value={urlState.name} // [!code highlight:3]
+      onChange={(ev) => setUrl({ name: ev.target.value })}
+      />
+    // OR can update state immediately but sync change to url as needed
+    <input
+      value={urlState.name}
+      onChange={(ev) => { setState(curr => ({ ...curr, name: ev.target.value })) }}
+      onBlur={() => setUrl()}
+    />
+    <button onClick={() => setUrl((curr, initial) => initial)}>
+      Reset
+    </button>
+    </>
+};`}
+      />
+      <File
+        name="ComponentB"
+        matchers={tooltips}
+        content={`import { useFormState } from './useFormState';// [!code highlight:1]
+
+export const ComponentB = ({ searchParams }: { searchParams?: Record<string, string> }) => {
+  // same state as ComponentA - a separate island, no props between them, no context
+  const { urlState } = useFormState(searchParams);// [!code highlight:1]
+
+// will be defaultValue from \`form\` if not in url, no need to check
+// [!code word:urlState]
+  return <div>name: {urlState.name}</div>
+};`}
+      />
+      <div className="codeTitle">{copy.advancedStep}</div>
+      <File
+        name="useFormState - extended"
+        matchers={tooltips}
+        content={`import React from 'react';
+import { useUrlState } from 'state-in-url/astro';
+import { form } from './form';
+
+export const useFormState = (searchParams?: Record<string, string>) => {// [!code highlight:1]
+  const { urlState, setUrl: setUrlBase, reset } = useUrlState(form, { searchParams });
+
+  // first navigation will push new history entry
+  // all following will just replace that entry
+  // this way will have history with only 2 entries - ['/url', '/url?key=param']
+
+  const replace = React.useRef(false);
+  const setUrl = React.useCallback((
+      state: Parameters<typeof setUrlBase>[0],
+      opts?: Parameters<typeof setUrlBase>[1]
+    ) => {
+      setUrlBase(state, { replace: replace.current, ...opts });
+      replace.current = true;
+  }, [setUrlBase]);
+
+  return { urlState, setUrl, resetUrl: reset };
+};`}
+      />
+    </div>
+  );
+};

packages/example-nextjs16/src/app/(en)/astro/page.tsx

@@ -0,0 +1,16 @@
+import { copy } from '../../i18n/copy/en';
+import { DemoPage } from '../../pages/DemoPage';
+import { pageMetadata } from '../../seoStuff';
+import { CodeBlocksAstro } from './CodeBlocksAstro';
+
+export const metadata = pageMetadata({
+  path: '/astro',
+  title: copy.meta.astro.title,
+  description: copy.meta.astro.description,
+});
+
+export default async function Home({ searchParams }: { searchParams: Promise<object> }) {
+  return (
+    <DemoPage searchParams={searchParams} copy={copy} codeBlocks={<CodeBlocksAstro copy={copy.quickStart} />} />
+  );
+}

packages/example-nextjs16/src/app/(en)/layout.tsx

@@ -13,7 +13,7 @@ export const revalidate = 604800; // 7 days
 
 /**
  * Root layout for the English pages, which are served unprefixed: `/`,
- * `/react-router`, `/remix`, and the Playwright fixture routes under
+ * `/react-router`, `/remix`, `/astro`, and the Playwright fixture routes under
  * `(tests)`. `[locale]/layout.tsx` is the second root layout, for the eight
  * translations. See shell/RootDocument.tsx for why there are two.
  */

packages/example-nextjs16/src/app/DemoPart.tsx

@@ -78,6 +78,7 @@ function getUrls(pathname: string) {
   let routerKind: keyof typeof sourceUrls = 'next.js'
   if (pathname.includes('/react-router')) routerKind = 'react-router';
   else if (pathname.includes('/remix')) routerKind = 'remix.js';
+  else if (pathname.includes('/astro')) routerKind = 'astro';
   else routerKind = 'next.js';
   const urls = sourceUrls[routerKind]
   return { routerKind, urls }
@@ -95,5 +96,9 @@ const sourceUrls = {
   'remix.js': {
     form: 'https://github.com/asmyshlyaev177/state-in-url/blob/master/packages/example-remix2/app/routes/Form-for-test.tsx',
     status: 'https://github.com/asmyshlyaev177/state-in-url/blob/master/packages/example-remix2/app/routes/Status-for-test.tsx'
+  },
+  astro: {
+    form: 'https://github.com/asmyshlyaev177/state-in-url/blob/master/packages/example-astro/src/components/Form-for-test.tsx',
+    status: 'https://github.com/asmyshlyaev177/state-in-url/blob/master/packages/example-astro/src/components/Status-for-test.tsx'
   }
 } as const;

packages/example-nextjs16/src/app/[locale]/astro/page.tsx

@@ -0,0 +1,30 @@
+import { notFound } from 'next/navigation';
+
+import { localeFromParam } from '../../i18n';
+import { copyFor } from '../../i18n/copy';
+import { DemoPage } from '../../pages/DemoPage';
+import { localeMetadata } from '../../seoStuff';
+import { CodeBlocksAstro } from '../../(en)/astro/CodeBlocksAstro';
+
+export async function generateMetadata({ params }: { params: Promise<{ locale: string }> }) {
+  const { locale } = await params;
+  return localeMetadata({ localeDir: locale, path: '/astro' });
+}
+
+export default async function Home({
+  params,
+  searchParams,
+}: {
+  params: Promise<{ locale: string }>;
+  searchParams: Promise<object>;
+}) {
+  const { locale: dir } = await params;
+  const locale = localeFromParam(dir);
+  if (!locale) notFound();
+
+  const copy = copyFor(locale.code);
+
+  return (
+    <DemoPage searchParams={searchParams} copy={copy} vsHref={`/${dir}/vs/nuqs`} codeBlocks={<CodeBlocksAstro copy={copy.quickStart} />} />
+  );
+}

packages/example-nextjs16/src/app/astro.md/route.ts

@@ -0,0 +1,9 @@
+import { llmsTxtResponse } from '../llmsTxtResponse';
+
+/**
+ * `/astro.md` — the Markdown mirror of the Astro demo page.
+ * See llmsTxtResponse.ts for why all three mirrors serve the same document.
+ */
+export const dynamic = 'force-static';
+
+export const GET = llmsTxtResponse;

packages/example-nextjs16/src/app/components/AiSkills.tsx

@@ -18,6 +18,7 @@ const SKILLS: ReadonlyArray<readonly [string, keyof AiSkillsTableCopy]> = [
   ['input-handling', 'inputHandling'],
   ['nextjs-ssr', 'nextjsSsr'],
   ['react-router-remix-setup', 'reactRouterRemixSetup'],
+  ['astro-setup', 'astroSetup'],
   ['form-library-integration', 'formLibraryIntegration'],
   ['shared-state-no-url', 'sharedStateNoUrl'],
 ];