Roadmap / Changelog

[franky47]

🗺️ Roadmap

Coming up

Library

• Showcasing the use of Zod in parsers for validation - [RFC] Validation (Zod, Standard Schema etc) #446
• Refactor the queue system to handle both throttle and debounce behaviours: feat: Debounce #900.
• Provide ways to read current search params (loaders: feat: Add loader feature  #818) 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

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 [RFC] 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.4.1

• fix: Import React.cache only when needed #923
• test: Add vitest-package-exports #930
• doc: Fix the parseAsIndex demo #922
• doc: Update withDefault JSDocs #926
• doc: Add React Paris banner #931
• chore(deps): bump actions/upload-artifact from 4.6.0 to 4.6.1 #928
• chore(deps): bump pnpm/action-setup from 4.0.0 to 4.1.0 #929

2.4.0

• feat: Add parseAsPageIndex parser #791
• feat: Add custom parsers testing helpers #853
• feat: Add scroll option support for React SPA adapter #911
• feat: Full-page navigation option for shallow: false updates in React SPA #891
• feat: Detect multiple contexts loaded at the same time #861
• fix: useQueryStates does not update values correctly when config changes #908
• fix: Dynamic segments & multitenancy for Next.js pages router #917
• fix: Ship react-router v6/v7 .d.ts redirects on NPM #899
• fix: Handle console.log of null values in React Devtools #909
• doc: Add Unkey as sponsor 💖 #915
• doc: Add OpenStatus as sponsor 💖 #920
• test: Add React Router Fog of War test #885
• chore: Update deps #894
• chore: Create CODE_OF_CONDUCT.md #892
• chore: Move type tests away from src #897
• chore: Trying ubuntu-22.04-arm runners #903
• chore: Update pkg.pr.new comments #918

2.3.2

• fix: Allow useQueryStates' state updater function to return null #871
• fix: Dynamic keys for useQueryStates #858
• fix: Conditional rendering in React Router #882
• fix: React Router stale values after remount #887
• test: Add test for the agnostic adapter #878
• doc: Update wording for the "missing suspense boundary" guidelines #847
• doc: Add Waku community adapter #848
• doc: add break word all for better ux #753
• chore(deps): bump actions/setup-node from 4.1.0 to 4.2.0 #888
• chore(deps): bump actions/upload-artifact from 4.5.0 to 4.6.0 #889
• chore: Update PNPM to v10 #872
• chore: Test running CI on arm64 GHA runners #864
• chore: Update deps #867

2.3.1

• fix: Referential stability for the state updater function #841
• fix: Maintain location.state in React Router frameworks #840
• fix: Export UrlKeys type helper #854
• chore: Update version range to include react-router@^6 #844
• perf: Optimise render counts #849
• chore: Update deps #851
• chore: Try to avoid bursting e2e-next CI caching #859

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: nuqs@2.0.0 #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.