astro-setup

This skill builds on state-in-url/feature-state-hook. Read it first for the module-scoped default-state rule.

state-in-url — Astro

Two shapes of Astro project, two tools:

Astro has no client-side router by default. The hook writes the URL with window.history (replaceState by default, pushState with replace: false) and reads it back on back/forward, on its own writes, and on any other pushState/replaceState on the page.

Setup: React islands

// src/state.ts — module scope, one object, imported by every island that shares it
type FiltersState = { sort: 'name' | 'date'; page: number };
export const FILTERS_STATE: FiltersState = { sort: 'name', page: 1 };

// src/components/Filters.tsx
import { useUrlState } from 'state-in-url/astro';

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

export function Filters({ searchParams }: { searchParams?: Record<string, string> }) {
  const { urlState, setUrl } = useUrlState(FILTERS_STATE, { searchParams });
  return <button onClick={() => setUrl({ page: urlState.page + 1 })}>Next</button>;
}

---
// src/pages/index.astro
import { Filters } from '../components/Filters';

// A plain object: island props are serialized, URLSearchParams is not.
const searchParams = Object.fromEntries(Astro.url.searchParams);
---

<Filters client:load searchParams={searchParams} />

The page must be rendered on demand — output: 'server', or export const prerender = false on the page — and either way an adapter must be configured (@astrojs/node, @astrojs/vercel, …); on Astro's default static output the build fails. Only then does Astro.url.searchParams hold the request's query. A prerendered page has no request, so searchParams is {} and the island fills its state in the browser after hydration.