@contract-kit/nuqs

nuqs integration for Contract Kit

This package gives you a thin bridge between contract query params and nuqs URL state.

It does not replace @contract-kit/react-query. Instead, it helps you keep URL-backed filters aligned with a contract's query shape and then pass that state into rq(contract).queryOptions(...).

Installation

npm install @contract-kit/nuqs @contract-kit/react-query nuqs react @tanstack/react-query

In Next.js App Router, mount the NuqsAdapter once near the root:

import { NuqsAdapter } from "@contract-kit/nuqs/next/app";

export function Providers({ children }: { children: React.ReactNode }) {
  return <NuqsAdapter>{children}</NuqsAdapter>;
}

Setup

import { createClient } from "contract-kit";
import { createReactQuery } from "@contract-kit/react-query";
import { createNuqs } from "@contract-kit/nuqs";

const client = createClient({ baseUrl: "/api" });

export const rq = createReactQuery(client);
export const nq = createNuqs();

Usage

import { parseAsInteger, parseAsString } from "nuqs";
import { useQuery } from "@tanstack/react-query";
import { nq } from "@/client/nq";
import { rq } from "@/client/rq";
import { listContacts } from "@/contracts/contacts";

const contactsSearch = nq(listContacts).query({
  parsers: {
    search: parseAsString.withDefault(""),
    offset: parseAsInteger.withDefault(0),
  },
});

function ContactsPage() {
  const [filters, setFilters] = contactsSearch.useState();

  const query = useQuery(
    contactsSearch.toQueryOptions(rq(listContacts), filters)
  );

  return null;
}

API

createNuqs()

Creates the Contract Kit nuqs adapter factory.

nq(contract).query({ parsers, ...options })

Creates a contract-aware URL query helper.

• parsers: required nuqs parser map keyed by the contract's query params
• history, shallow, scroll, urlKeys, etc.: forwarded to useQueryStates

.useState(options?)

Wraps nuqs useQueryStates(parsers, options) with the configured parser map.

.toQuery(state, { omitNullish })

Converts nuqs state into a Contract Kit query object.

• omitNullish defaults to true
• null and undefined are removed
• valid falsy values like 0, false, and "" are preserved

.toQueryOptions(rq(contract), state, options?)

Convenience helper that calls rq(contract).queryOptions({ query, ...options }).

When to use this

@contract-kit/nuqs is a good fit for pages where the URL should reflect search or filter state:

• admin tables
• search screens
• dashboards
• reporting pages
• index/list views with tabs, pagination, or filters

If you just need typed fetching, use @contract-kit/react-query directly.