@beignet/nuqs

nuqs integration for Beignet

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

It does not replace @beignet/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 @beignet/nuqs @beignet/core @beignet/react-query nuqs react @tanstack/react-query
Copy

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

import { NuqsAdapter } from "@beignet/nuqs/next/app";

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

Setup

import { createClient } from "@beignet/core/client";
import { createReactQuery } from "@beignet/react-query";
import { createNuqs } from "@beignet/nuqs";

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

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

Usage

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

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;
}
Copy

API

createNuqs()

Creates the Beignet 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 Beignet query object.

• omitNullish defaults to true
• null and undefined are removed
• valid falsy values like 0, false, and "" are preserved
• Date state is serialized as ISO-8601 and parseAsJson object state is serialized as JSON by the Beignet client used by toQueryOptions(...)

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

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

When to use this

@beignet/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 @beignet/react-query directly.