Roadmap / Changelog

[franky47]

🗺️ Roadmap

Next

Library

• Showcasing the use of Zod in parsers for validation - [RFC] Zod integration #446
• Update docs about shallow routing and WHS -> This is now in Next.js docs
• Add caveat about using router.refresh on shallow updates (resets the query string). Solutions are to use non-shallow updates, or to enable WHS. See wrong url after refresh page #392 (comment) -> This needs a test to ensure whether this behaviour is still present or not.
• State init function as a default value? See Discussion Feature Idea: Load & save params to localStorage as an alternative default on page load #606
• Merging useQueryState and useQueryStates to a single API that accepts both types of params (typing this is going to be a wild ride).
• Provide support for arrays of values with repeating keys (eg: ?q=foo&q=bar), see Discussion [Research] URLSearchParams array support #484.
• Refactor the queue system to handle both throttle and debounce behaviours, see Discusson Debounce URL updates #291.
• Investigate mock-next-router for testing -> Better to use end-to-end tests to test against actual behaviours. -> Unit testing with mock adapter is being worked on in feat: Introducing adapters for other frameworks #644
• Provide ways to read current search params and set them to the URL in a one-off way (outside of a React hook context), using the same parsers and options.
• Reduce dependency on the router, both to open to other frameworks, but also to allow router wrappers like next-view-transitions - feat: Introducing adapters for other frameworks #644
• Add a global default options context provider
• Showcase integration with other "external" state managers (Zustand, Jotai, Valtio, Redux, etc)

Docs

• Rename the "playground" into a "recipes" section
• Showcase a complete pagination + filtering + ordering/sorting example with data fetching (no artificial delay). Maybe using shadcn table.
• Figure out how to add interactive (editable + runnable) demos of the hooks, client-side only. HMR in prod?
• Middleware migrations to rename/edit search params keys & values, keeping support for old URLs while allowing app code to evolve. (Tweet)

2.0.0

Planned after the release of Next.js 15 and React 19.

• v2 #459
• feat: Introducing adapters for other frameworks #644

🚀 Changelog

1.20.0

• feat: Allow remapping keys in useQueryStates #671
• feat(serializer): allow null to clear all param values from base #657

1.19.3

• fix(serializer): Allow serializers to operate on derived UrlSearchParams classes #647
• fix: Handle Promises for the searchParams page prop #652

1.19.2

• fix: Serialization of default values in createSerializer #642

1.19.1

• fix: Cache the query string in useQueryStates #631

1.19.0

• feat: Allow clearing all search params managed by useQueryStates #622
• fix: Allow parser-level options in useQueryStates #621
• fix: Ensure referential stability for values #617

1.18.0

• feat: Add parser type inference helpers #578

1.17.8

• fix: Encode special characters in keys #600

1.17.7

• fix: Move debug localStorage detection inline #592

1.17.6

• fix: localStorage availability check update #588

1.17.5

• fix: Shallow equality check on cache parsing input #580

1.17.4

• fix: Harden debug reading of localStorage #560

1.17.3

• fix: don't fail parse if called again with identical input #557

1.17.2

• fix: Don't rely on URL for initial state (9912eef)

1.17.1

• fix: Equality check for non-primitives in clearOnDefault #504

1.17.0

• feat: Add "clear on default" option #493

1.16.1

• fix: Shallow state #482

1.16.0

• doc: Refactor playground #473
• feat: Add serializer helper #475

1.15.4

• fix: Mark global next internal as optional #465

1.15.3

• fix: Regression in mounting components #461

1.15.2

• fix: Check for undefined next property on window #456

1.15.1

Fixes a bug where debugging information would only show when using next-usequerystate (not nuqs) in localStorage.debug.

1.15.0

• feat: Add literal parsers #453

1.14.1

• fix: Hash preservation #451

1.14.0

Project rebranding to nuqs - #438

1.13.2

• fix: Push #419 (history: "push" was broken for pages router)

1.13.1

Released when Next.js 14.0.4 landed with the shallow routing fix in vercel/next.js#58861

• fix: Deprecate subscribeToQueryUpdates #425

1.13.0

• feat: Add search params cache #397
• feat: Add support for transitions #406
• Fix basePath pathname stability #413

1.12.2

Released when Next.js 14.0.3 landed with the prefetch fix in vercel/next.js#58297.

• fix: Restore compatibility with next@latest #395
• Update CI to replace 14.0.1 with latest (and update branch protection to match)
• Get fix: Don't reset shallow URL updates on prefetch vercel/next.js#58297 reviewed and merged to re-enable compatibility with next@latest. See Resets to initial state when there is Link with prefetch #388.

1.12.1

• Switch debug logging to console.log #398
• bug_report template: Use emoji as checkboxes #401

1.12.0

• feat: Add support for experimental WHS #394

1.11.0

• Handle higher rate limits on Safari (~100ms for 17+, ~300ms for older versions)
• Allow catching unapplied search params when rate-limited
• URLs to docs in errors

1.10.0

• feat: Allow chaining parser options & default values #387
• feat: Configurable throttling #374

[franky47]

Tests

Redirects & Rewrites

Handle source and destination search params in both

Middleware

• Search params injected by middleware get parsed correctly (client and server side)
• Setting a non-shallow query state which gets overriden by a middleware

[Talent30]

I'd like to try creating a new documentation site. But I'm not very artistic and in the end you might get a copy of the T3-env site if you don't mind....

[franky47]

@Talent30 I've opened a discussion dedicated to the new docs, let's move the conversation there.