nuqs

Build and review query state with nuqs

Treat the URL as the state contract. Follow the steps in order, and load only the reference branches whose conditions match the application.

1. Model the URL contract

For every query key, record:

• its URL spelling and domain type;
• the value to use when the key is absent or invalid;
• whether setting the default should remove the key;
• whether an update represents navigation or ephemeral UI state;
• which client components, loaders, routes, or server components read it.

Inspect the installed nuqs, framework, and router major versions before choosing integration paths.

Read the matching branch references:

• Adapter branch: select and mount the matching adapter when installing nuqs, changing routers, or reviewing the provider boundary.
• URL-key branch: define shorter external key names when domain property names should differ from URL keys.
• Provider-policy branch: configure adapter defaults and URL middleware when update policy or URL processing belongs at the application boundary.

Complete when every query key has one documented URL representation and the adapter import and provider boundary match the installed router.

2. Define one parser contract

Put related parsers in a dependency-neutral module. Import parsers from nuqs/server when any server-side consumer imports that module; client hooks can reuse the exported parser object.

Prefer built-ins that match the wire format. Use .withDefault(value) only when absent and invalid values should resolve to a non-null domain default. Defaults stay internal unless explicitly written; setting state to null removes the query key.

import {
  parseAsInteger,
  parseAsString,
  parseAsStringLiteral,
} from "nuqs/server";

export const searchParams = {
  q: parseAsString.withDefault(""),
  page: parseAsInteger.withDefault(1),
  sort: parseAsStringLiteral(["relevance", "date"] as const).withDefault(
    "relevance",
  ),
};