Roadmap / Changelog

[franky47]

🗺️ Roadmap

Coming up

Library

• Showcasing the use of Zod in parsers for validation - [RFC] Zod integration #446
• Refactor the queue system to handle both throttle and debounce behaviours, see Discusson Debounce URL updates #291.
• 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.
• Add a global default options context provider → probably not needed
• Investigate support for shallow: false in Remix (Tweet, Skeet)
• Refactor shallow/deep optimistic updates and history spy to be shared across adapters
• Refactor the cache system to allow parsing from an object of parsers without caching, for other frameworks (eg: Remix loaders).

Research phase:

• Linking & search params interception à la TS Router middleware
• Middleware migrations to rename/edit search params keys & values, keeping support for old URLs while allowing app code to evolve. (Tweet)
• Showcase integration with other "external" state managers (Zustand, Jotai, Valtio, Redux, etc)
• Merging useQueryState and useQueryStates to a single API that accepts both types of params (typing this is going to be a wild ride).
• State init function as a default value? See Discussion Feature Idea: Load & save params to localStorage as an alternative default on page load #606
• Provide support for arrays of values with repeating keys (eg: ?q=foo&q=bar), see Discussion [Research] URLSearchParams array support #484.
• 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.
• Add support for different storage mechanisms in adapters (eg: hash, localStorage). This would require considerable refactoring of the queue system, to go hand in hand with support for debounce. Prerequisites: feat: Abstract reading from location.search in adapters interface #800

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?

🚀 Changelog

2.3.0

• feat: Added react-router v7 support #785
• chore: React 19 #796
• feat: Abstract reading from location.search in adapters interface #800
• fix(types): Export Nullable type for correctly inferring return type of createSerializer() #801
• fix: Preserve hash in React Router based adpaters #809
• feat: Shallow routing for everyone #811
• feat: Add loader feature  #818
• fix: Support ? characters in serializer base #821
• feat: Add UrlKeys type helper #824
• ref: Use a useEffect rather than useLayoutEffect #828
• ref: Enable history patching by default for React Router #833
• docs: Document testing nuqs based hooks #795
• test: Move relevant e2e tests to be unit tests #802
• test: Move e2e tests into shared library #807
• chore: Enable provenance #819
• doc: Fix link to options docs #825
• test: Add native HTML form test #829

2.2.3

• fix: Protection against null useSearchParams in Next.js #781
• fix: Encode invisible ASCII control characters #783

2.2.2

• fix: Update useQueryStates state cache when syncing from useSearchParams #776

2.2.1

• fix(serializer/types): Allow null value in serializer for parsers with default values #769

2.2.0

• feat: Add testing HOC to reduce test setup verbosity #765
• fix: Add React 19 RC in peer dep semver range #756
• fix: Support for dynamic default values in useQueryStates #762
• fix: Make the testing adapter clear the URL queue #764

2.1.2

• fix: Use correct keys for state sync #759
• fix: Log an error in development if URI size of 2000 characters is exceeded. #747

2.1.1

• fix(adapters/next): wrap setOptimisticSearchParams in startTransition #729

2.1.0

• feat: Add parseAsISODate #707
• feat: Export the SearchParams type in both client & server bundles #710
• feat: Export OnUrlUpdateFunction type for Vitest v2 #712
• feat: Add urlKeys & clearOnDefault support for serializer #720
• feat: Add support for urlKeys in cache #725
• fix: Use optimistic search params in app router #718

2.0.4

• fix: Read queued updates when initialising state #703

2.0.3

• fix: Add stub CJS exports for old ESLint plugins #701

2.0.2

• fix: Make clearOnDefault: true by default #700

2.0.1

• fix: Add back the .js extension to the pages router adapter #694
• fix: Mark framework packages as optional peer dependencies #697

2.0.0

• feat: [email protected] #459
• feat: Introducing adapters for other frameworks #644

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

[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.