{"name":"nuqs: Type-Safe URL State Management for React Frameworks","description":"nuqs is a powerful, type-safe state manager for React frameworks that stores component state directly in the URL query string. It offers a `useState`-like API, making it intuitive to manage URL parameters while ensuring type safety across various React environments. This library simplifies complex URL state synchronization, providing a robust solution for modern web applications.","github":"https://github.com/47ng/nuqs","url":"https://osrepos.com/repo/47ng-nuqs","source":"osrepos.com","sourceDescription":"This repository profile is provided by osrepos.com, an open source repository discovery platform.","repositoryProfile":"https://osrepos.com/repo/47ng-nuqs","generatedFor":"open source discovery and AI-assisted research","markdown":"https://osrepos.com/repo/47ng-nuqs.md","json":"https://osrepos.com/repo/47ng-nuqs.json","topics":["query-params","react","search-params","state-management","type-safe","url-state","TypeScript","Frontend Development"],"keywords":["query-params","react","search-params","state-management","type-safe","url-state","TypeScript","Frontend Development"],"stars":null,"summary":"nuqs is a powerful, type-safe state manager for React frameworks that stores component state directly in the URL query string. It offers a `useState`-like API, making it intuitive to manage URL parameters while ensuring type safety across various React environments. This library simplifies complex URL state synchronization, providing a robust solution for modern web applications.","content":"## Introduction\n\n`nuqs` is an innovative, type-safe state manager designed for React frameworks, allowing you to store and manage component state directly within the URL query string. Think of it as `useState`, but with the added benefit of persistence and shareability through the URL. This approach makes the URL the single source of truth for your application's state, enhancing user experience and SEO.\n\nIt supports a wide array of React environments, including Next.js (both `app` and `pages` routers), plain React (SPA), Remix, React Router, and TanStack Router, thanks to its flexible adapter system. Key features include built-in parsers for common data types, batching of state updates, server-side capabilities for accessing search parameters, and integration with React's `useTransition` for loading states.\n\n## Installation\n\nGetting started with `nuqs` is straightforward. You can install it using your preferred package manager:\n\nshell\npnpm add nuqs\n\n\nshell\nyarn add nuqs\n\n\nshell\nnpm install nuqs\n\n\nAfter installation, you will need to wrap your React component tree with the appropriate adapter for your framework. For example, with Next.js (app router):\n\ntsx\n// src/app/layout.tsx\nimport { NuqsAdapter } from 'nuqs/adapters/next/app'\nimport { type ReactNode } from 'react'\n\nexport default function RootLayout({ children }: { children: ReactNode }) {\n return (\n \n \n {children}\n \n \n )\n}\n\n\n## Examples\n\n`nuqs` provides a familiar API, similar to React's `useState`. Here's a basic example demonstrating how to manage a `name` parameter in the URL:\n\ntsx\n'use client' // Only works in client components\n\nimport { useQueryState } from 'nuqs'\n\nexport default () => {\n const [name, setName] = useQueryState('name')\n return (\n <>\n
Hello, {name || 'anonymous visitor'}!
\n setName(e.target.value)} />\n \n \n )\n}\n\n\nFor non-string state types, `nuqs` offers a variety of built-in parsers, such as `parseAsInteger`, `parseAsBoolean`, `parseAsTimestamp`, and `parseAsJson`, ensuring your URL state is always correctly typed and handled:\n\nts\nimport {\n parseAsInteger,\n parseAsBoolean\n} from 'nuqs'\n\nuseQueryState('count', parseAsInteger)\nuseQueryState('darkMode', parseAsBoolean)\n\n\n## Why Use nuqs?\n\n* **Type Safety**: `nuqs` enforces type safety for your URL parameters, significantly reducing common bugs and improving code reliability. You define the expected types, and the library handles the parsing and serialization.\n* **URL as Source of Truth**: By storing state in the URL, your application becomes more shareable, bookmarkable, and resilient to page refreshes. This is crucial for applications with filters, pagination, or complex views.\n* **Framework Agnostic**: With dedicated adapters, `nuqs` seamlessly integrates with popular React frameworks and routers, providing a consistent API regardless of your chosen stack.\n* **Rich Features**: Beyond basic state management, `nuqs` offers advanced features like custom parsers, batching of multiple query updates, server-side search parameter access, and SEO considerations for canonical URLs.\n* **Developer Experience**: The `useState`-like API makes `nuqs` incredibly intuitive for React developers, allowing for quick adoption and efficient development of URL-driven UIs.\n\n## Links\n\n* **GitHub Repository**: [https://github.com/47ng/nuqs](https://github.com/47ng/nuqs){:target=\"_blank\"}\n* **Official Documentation**: [https://nuqs.dev](https://nuqs.dev){:target=\"_blank\"}\n* **NPM Package**: [https://www.npmjs.com/package/nuqs](https://www.npmjs.com/package/nuqs){:target=\"_blank\"}","metrics":{"detailViews":3,"githubClicks":11},"dates":{"published":null,"modified":"2025-10-12T17:16:18.000Z"}}