Roadmap / Changelog #375
Description
🗺️ Roadmap
Coming up
Library
- Showcasing the use of Zod in parsers for validation - [RFC] Validation (Zod, Standard Schema etc) #446, doc: Add Zod codecs community parsers #1097
- Refactor the queue system to handle both throttle and debounce behaviours: Done in 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.refreshon 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.6.0
Features:
- feat(debounce): add warning when shallow: true is used with debounce #1104
- feat: Add processUrlSearchParams middleware as adapter prop #1110
- feat: add processUrlSearchParams to createSerializer #1115
Documentation:
- doc: Add Zod codecs community parsers #1097
- doc: Fix all-time stats skeletons #1103
- doc: use URLSearchParams.sort #1113
- doc: Fix links & add framework icons #1116
Other changes:
- chore: Securing workflows #1105
- chore: Use semantic-release/github 11.0.5 to handle deprecated search endpoints #1108
2.5.2
2.5.1
2.5.0
See blog post: https://nuqs.47ng.com/blog/nuqs-2.5
Features:
- feat: Key isolation #855
- feat: Debounce #900
- feat: Add support for TanStack Router #953
- feat: Add Standard Schema interface #965
- feat(types): Add
constmodifier to literal parsers to auto-infer their arguments as literals #1038 - feat: Export ./package.json in exports field for Module Federation support #1062
- feat: defaultOptions for NuqsAdapter #1066
- feat: Add support for more global default options at the adapter level #1079
- feat: Allow specifying a different base type for the serializer #1083
Bug fixes:
- fix: Replace require by default conditional export field #996
- fix: Type inference for defaultValue of object syntax #1057
- fix: Remove esm-only on TanStack Router export #1063
- fix: Handle JSON in TanStack Router #1073
Documentation:
- docs: Add inertia community adapter #787
- doc: Add blog section #976
- doc: Vercel OSS program #1000
- doc: Add code.store & oxom as sponsors 💖 #1004
- doc(blog): The URL type-safety iceberg #1005
- doc: Fix non-null assertions #1017
- doc: Add Deploy on Vercel button #1021
- docs: Extend next-app example to include more features #1025
- doc: Fix mobile navbar collapse & sticky #1027
- doc: Fix 500 error on Vercel ISR #1032
- doc: Add Aurora Scharff as a sponsor 💖 #1037
- doc: Fix transition docs to not call parser as function #1041
- doc: Title is hidden behind headers on mobile #1043
- Update NUQS-404.md #1046
- doc: add effect schema parser page #1051
- doc: Debounce docs edits #1052
- doc: Migrate docs to Fumadocs 15, Tailwind CSS v4 #1056
- doc: Fix default value for shallow in React Router disclaimer #1058
- doc: prevent NaN appearing in pagination example #1070
- doc: Add nuqs 2.5 release blog post #1082
Other changes:
- chore: Use React Compiler RC #985
- chore: Replace tsup with tsdown #990
- chore: Add RSS feed auto-discovery #1011
- chore: Fix API stability test #1029
- chore: Linting PR titles #1033
- chore: Add TanStack Router to og:images #1065
- chore: Improve stats page #1067
- chore: Configure MDX types #1074
- chore: Track beta versions adoption in the stats page #1077
- chore: Update dependencies #1078
- chore: Pass children as config in createElement to avoid ts-expect-error #1080
- chore: Reduce the bundle size #1081
- ci: Add publint step to CI workflow #1086
2.4.3
- fix: Multiple query reordering in Next.js pages router internal state #983
- chore: Update runners to ubuntu-24.04-arm #980
2.4.2
- fix: Prettify inferred types #967
- fix: Import from next/navigation.js #939
- fix: Increase rate-limit factor for Next.js app router #973
- test: Add property-based testing with fast-check #961
- doc: Add "works with" icons #933
- doc: add missing commas #936
- doc: Add link tree for React Paris #937
- doc: React Paris is over 😥 #946
- doc: Various minor edits #951
- chore: Update React Router to 7.3.0 #932
- chore: Update dependencies #949
- chore: Update React to 19.1.0 & PNPM to 10.7 #952
- chore(deps-dev): bump @react-router/express from 7.4.0 to 7.4.1 #959
- chore(deps-dev): bump vite from 6.2.3 to 6.2.4 #955
- chore(deps): bump actions/setup-node from 4.2.0 to 4.3.0 #956
- chore(deps): bump actions/upload-artifact from 4.6.1 to 4.6.2 #957
- chore(deps-dev): bump vite from 6.2.4 to 6.2.5 #962
- chore(docs): Waku v0.22 community adapter useRouter update #963
- chore: Next.js 15.3.0 with Turbopack build #971
- chore(deps-dev): bump vite from 6.2.5 to 6.2.6 #975
- chore: Update dependencies #977
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
parseAsPageIndexparser #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: falseupdates 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
Nullabletype for correctly inferring return type ofcreateSerializer()#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
2.2.1
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
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
2.0.3
2.0.2
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
1.20.0
- feat: Allow remapping keys in useQueryStates #671
- feat(serializer): allow
nullto clear all param values from base #657
1.19.3
- fix(serializer): Allow serializers to operate on derived
UrlSearchParamsclasses #647 - fix: Handle Promises for the searchParams page prop #652
1.19.2
1.19.1
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
1.17.8
1.17.7
1.17.6
1.17.5
1.17.4
1.17.3
1.17.2
- fix: Don't rely on URL for initial state (9912eef)
1.17.1
1.17.0
1.16.1
1.16.0
1.15.4
1.15.3
1.15.2
1.15.1
Fixes a bug where debugging information would only show when using next-usequerystate (not nuqs) in localStorage.debug.
1.15.0
1.14.1
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
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
1.12.0
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