nuqs

Coordinate type-safe URL query state in Next.js with nuqs parsers.

Updated Apr 9, 2026
One-click install
npx skills add https://github.com/remiconnesson/insights-garden --skill nuqs-remiconnesson
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: nuqs
Source: https://github.com/remiconnesson/insights-garden/tree/main/.agents/skills/nuqs
Command: npx skills add https://github.com/remiconnesson/insights-garden --skill nuqs-remiconnesson

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve?

Nuqs removes the friction of keeping URL query parameters, local UI state, and server-rendered data in sync across a Next.js app, so teams can build shareable and reliable stateful interfaces without manual parsing or brittle edge cases.

Core Features & Use Cases

  • Type-safe query state for filters, pagination, sorting, tabs, and search inputs.
  • Shared parser patterns that keep client components and Server Components consistent.
  • Guardrails for defaults, validation, history behavior, throttling, and loading states.
  • Useful for refactoring code that reads or writes search parameters, especially when state must survive refresh, back/forward navigation, or server re-rendering.

Quick Start

Ask the model to review or refactor your Next.js code so that all URL state uses nuqs parsers and adapter setup correctly.

Frequently Asked Questions about nuqs

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I keep URL search parameters in sync with client and server components in Next.js?

You can synchronize URL search parameters with client and server components by using type-safe query parsers and an adapter to maintain consistent state during refresh and navigation. Nuqs coordinates this synchronization for Next.js applications.

What is the best way to manage type-safe URL state for pagination and filters in Next.js?

Managing type-safe URL state for filters and pagination is best handled by applying typed parsers and default validation rules to search parameters, which ensures state survives back and forward navigation. Nuqs provides these shared parser patterns for Next.js.

How does URL query parsing work across Next.js Server Components and client components?

URL query parsing across Server Components and client components works by applying shared typed parsers that read and write search parameters consistently on both sides. Nuqs handles server cache parsing and URL synchronization to keep the data matched.

Can I use nuqs to refactor existing Next.js code that reads and writes search parameters?

Yes, you can use nuqs to refactor existing Next.js code that reads or writes search parameters by replacing manual parsing logic with typed parsers and adapter setup. This ensures proper default handling and consistent URL synchronization.

Do I need a specific adapter setup to handle URL state in Next.js server components?

You need proper nuqs adapter setup to handle URL state in Next.js server components, which enables server cache parsing and typed parser validation. This adapter ensures consistent query state synchronization across your application.

What are the limitations of manually parsing URL search parameters in Next.js?

Manually parsing URL search parameters in Next.js creates friction and brittle edge cases when keeping local UI state and server-rendered data in sync. Without type-safe parsers, state may not survive refresh or back and forward navigation reliably.