nuqs

Manage URL state in Next.js with type-safe parsers and NuqsAdapter.

Updated Feb 8, 2026
One-click install
npx skills add https://github.com/not-ani/elevated-school-takehome --skill nuqs-not-ani
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: nuqs
Source: https://github.com/not-ani/elevated-school-takehome/tree/main/.agents/skills/nuqs
Command: npx skills add https://github.com/not-ani/elevated-school-takehome --skill nuqs-not-ani

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

In Next.js projects, URL-based state is easy to mishandle without strong guarantees. This skill consolidates best practices for nuqs to ensure type-safe parsing, predictable defaults, and reliable client/server integration, reducing hydration errors and state drift across routes and components.

Core Features & Use Cases

  • Type-safe URL state with typed parsers and withDefault to eliminate nullable headaches.
  • Unified adapter and server/client patterns (NuqsAdapter, nuqs/server) to enable consistent behavior across Next.js app routes and server components.
  • Reusable parser configurations and options (withOptions) to minimize boilerplate and avoid mismatches during reviews or refactors.
  • Real-world scenarios include dashboards, search filters, pagination, and URL-driven UI state in Next.js projects.

Quick Start

Install Nuqs, wrap your app with NuqsAdapter, and start using useQueryState to manage URL state in Next.js.

Frequently Asked Questions about nuqs

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

FAQPage Schema
How do I manage type-safe URL state in Next.js server components?

Type-safe URL state in Next.js server components is managed by wrapping your app with NuqsAdapter and importing server utilities. This ensures consistent behavior across app routes and enables reliable client-server integration.

What is the best way to prevent hydration errors with Next.js search params?

Preventing hydration errors with Next.js search params requires a unified adapter pattern like NuqsAdapter. It provides predictable defaults and strict type-safety to eliminate state drift across routes and components.

How do I set default values for URL search parameters without nullable headaches?

Setting default values for URL search parameters is done using the withDefault function alongside typed parsers. This approach eliminates nullable headaches by guaranteeing type-safe fallbacks during option merging.

Can I use nuqs for URL-driven UI state like dashboards and pagination in Next.js?

nuqs is designed for URL-driven UI state in Next.js projects including dashboards, search filters, and pagination. It uses useQueryState and reusable parser configurations to manage these scenarios.

Why does my URL state drift across routes and how do I fix it in Next.js?

URL state drift across Next.js routes happens when state is mishandled without strong guarantees. Fix it by applying centralized type-safe parsers and NuqsAdapter to ensure predictable defaults and consistent behavior.

Do I need a special adapter for URL state in Next.js app routes?

A special adapter is needed for URL state in Next.js app routes. Wrapping your application with NuqsAdapter enables unified server-client patterns and ensures reliable integration across your project.