Instruction file imported from abhimanyujangid/next_arti (.cursor/rules/nuqs-url-state.mdc). Copyright stays with the author.

nuqs URL State

Setup

• Wrap the app in <NuqsAdapter> (root layout.tsx, inside providers).
• Define parsers per feature in feature/<name>/lib/params.ts.

Define parsers once

import { createSearchParamsCache, parseAsString } from "nuqs/server";

export const voicesSearchParams = {
  query: parseAsString.withDefault(""),
};

export const voicesSearchParamsCache = createSearchParamsCache(voicesSearchParams);

Server page — parse then prefetch

const { query } = await voicesSearchParamsCache.parse(searchParams);
prefetch(trpc.voices.getAll.queryOptions({ query }));

Client — same parser object

const [query, setQuery] = useQueryState("query", voicesSearchParams.query);
const { data } = useSuspenseQuery(trpc.voices.getAll.queryOptions({ query }));

Rules

• Share the same parser between server cache and client useQueryState.
• Debounce text inputs before setQuery (use-debounce) to avoid refetch spam.
• Keep URL as source of truth for filters/search — not local-only state (except debounce input).
• Type page searchParams as Promise<SearchParams> from nuqs/server when using the cache.