mcpField
N
nuqs

nuqs

github.com/fixmyberlinDevelopment039 installsUpdated 2d ago
Repository

About nuqs

A development skill for managing URL state with nuqs in Vite React apps that do not use TanStack Router. It outlines URL-state conventions and key configuration details, while directing apps with TanStack Router to use its search parameters instead.

Key features

  1. 01URL-shareable state conventions
  2. 02Vite React setup without a router
  3. 03Default history and shallow behavior
  4. 04JSON parsing validation guidance
  5. 05Batching related query parameters

Use cases

  1. 01Keeping shareable filters in the URL
  2. 02Storing map coordinates and zoom in query parameters
  3. 03Separating URL state from ephemeral UI state

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/fixmyberlin/fixmyskills --skill nuqs

After installing, type/nuqsin Claude Code to confirm it loaded.

Details

From the project README

LLM reference: Fetch llms.txt for the documentation index and latest API. Full docs in one file: llms-full.txt. Human-readable docs: nuqs.dev/docs.

Do not duplicate upstream API reference in this skill — use llms.txt / llms-full.txt for parsers, options, testing adapter, and troubleshooting.

URL state rule (FMC)

AppURL state
Uses TanStack Router (SPA or Start)Router search params: validateSearch — skill tanstack-router-conventions. Never nuqs.
Vite React app WITHOUT TanStack Routernuqs

On TanStack Router use validateSearch instead (tanstack-router-conventions → references/params-search-ui-routes.md).

Setup (Vite, no router)

Upstream detail: Installation · Adapters.

import { NuqsAdapter } from 'nuqs/adapters/react'

createRoot(root).render(
  <NuqsAdapter>
    <App />
  </NuqsAdapter>,
)

Adapter export verified in nuqs 2.9.5: NuqsAdapter from nuqs/adapters/react. Tests: NuqsTestingAdapter from nuqs/adapters/testing (see upstream Testing).

State split: URL-shareable state → nuqs; ephemeral UI → Zustand (zustand-state-management).

High-impact gotchas

  1. clearOnDefault — defaults to true (value equal to the default is removed from the URL). Set false only if the param must stay visible at its default.
  2. History and shallow — default history is replace (pass history: 'push' when back-button entries are wanted); shallow defaults to true.
  3. parseAsJson — requires a runtime validator (e.g. Zod schema) in v2+.
  4. Debug — localStorage.debug = 'nuqs'.
  5. Package — ESM-only; the nuqs/parsers entry was removed in v2, import parsers from nuqs.
  6. useQueryStates — batch related params (filters, lat/lng/zoom) into one URL update.

Related FMC skills

SkillRole
tanstack-router-conventionsvalidateSearch for apps with TanStack Router
zustand-state-managementEphemeral client state that does not belong in the URL

Comments

Markdown supported