nextjs-ssr

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

state-in-url — Next.js App Router SSR

Without searchParams, the first render of a useUrlState component has no URL knowledge. It renders defaults, then a client useEffect re-syncs from the URL → visible flash and a React hydration warning. The fix is to feed the URL into the hook on the server (via searchParams prop or a Proxy header) so the very first render is correct.

App Router only. Pages Router uses next/router, which state-in-url/next does not support — there are no plans to add it.

Setup

Server page forwarding searchParams (recommended)

// app/jobs/page.tsx  (Server Component)
import { JobsList } from './JobsList';

export default async function Page({
  searchParams,
}: {
  searchParams: Promise<Record<string, string | string[] | undefined>>;
}) {
  const sp = await searchParams; // Next.js 15+: searchParams is a Promise
  return <JobsList searchParams={sp} />;
}

// app/jobs/JobsList.tsx
'use client';
import { useUrlState } from 'state-in-url/next';
import { JOBS_STATE } from 'features/jobs/jobsState';

export function JobsList({ searchParams }: { searchParams: object }) {
  const { urlState, setUrl } = useUrlState(JOBS_STATE, { searchParams });
  return <pre>{JSON.stringify(urlState)}</pre>;
}

Fallback: useSearchParams when the prop cannot reach the component

Use this only when a client component genuinely cannot receive searchParams from a server parent. It is not the default and not an equivalent alternative: on a statically rendered route useSearchParams() needs a <Suspense> boundary — next build fails without one — and everything inside that boundary is client-rendered, so it shows the fallback until hydration. On an already-dynamic route it costs nothing extra, but it still buys nothing the server prop does not — on the client the hook already reads window.location.search for itself.