[OSS Review] nuqs

This article shares my research findings on an OSS library used in Giselle.
While originally written as an internal memo, I've structured it to be helpful for other developers considering similar OSS adoption decisions.

1. Overview of nuqs

• Name: nuqs

• Summary: nuqs is a type-safe search-params (URL query string) state manager for React frameworks. It provides a useState-like hook API to keep UI state synchronized with the URL, making it the source of truth.

• Core Features:

  • Type-Safe Hooks: Offers useQueryState (for single keys) and useQueryStates (for batch updates) with a familiar React hook experience. It includes built-in parsers for common types like strings, numbers, booleans, and arrays, and supports custom parsers.

  • Broad Framework Support: Works seamlessly across Next.js (App & Pages routers), Remix, React Router, TanStack Router, and standard React SPAs via lightweight adapters, enabling universal component logic.

  • Server-Side Rendering (SSR) Utilities: Provides server helpers (nuqs/server) like createSearchParamsCache to parse and share type-safe search params in nested React Server Components, eliminating prop drilling and aligning server/client defaults.

  • Granular Navigation Control: Allows fine-tuned control over browser history (push vs. replace), shallow routing, scroll behavior, and throttling to manage URL update frequency and respect browser API limits.

2. About the Organization: 47ng

• GitHub Org / Maintainers: 47ng

• Summary: 47ng is the GitHub organization for projects led by François Best (franky47), a freelance web developer and prolific open-source contributor. The organization hosts a collection of small, focused libraries for web development, spanning security, Next.js utilities, and backend plugins.

• Development Activity: The project is actively maintained, with a responsive maintainer who frequently posts release notes, engages in GitHub discussions, and manages issues. The library evolved from next-usequerystate and was rebranded to nuqs in January 2024, demonstrating ongoing development and modernization.

3. Software License: MIT

• License: MIT

• Notes: The MIT license is permissive, allowing for commercial use, modification, and distribution. It is compatible with other common licenses like Apache 2.0, making it straightforward to integrate into most projects without significant licensing conflicts.

4. Key Use Cases & Examples

• Major Use Cases:

  • Shareable Filters and Search UIs: Ideal for managing state for filters, sorting, and pagination in the URL. This makes the UI state deep-linkable, shareable, and ensures browser back/forward buttons work as expected.

  • Persistent Form and View State: Can replace local component state for forms, wizards, tabs, and toggles, so user selections persist through page reloads and can be shared via URL.

  • Consistent Server/Client State in Next.js: Enables parsing and validating search params on the server and propagating them to React Server Components, ensuring type-safety and consistency between server-rendered content and client-side interactions.

• Potential Applications:

  • An engineering blog post details migrating complex App Router filtering patterns to nuqs for a more robust and maintainable solution.

• Example Usage in Giselle:

  • feat(app): integrate NuqsAdapter into app layout and add nuqs deps by toyamarinyon · Pull Request #1723 · giselles-ai/giselle

Reference

• GitHub: https://github.com/47ng/nuqs

• OSSInsight: https://ossinsight.io/analyze/47ng/nuqs

• Official Documentation: https://nuqs.47ng.com

This article was written with the help of giselles.ai.