v1.8.0

1.8.0 (2023-09-15)

Announcement blog post: https://francoisbest.com/posts/2023/storing-react-state-in-the-url-with-nextjs

This release brings support for the app router, and requires Next.js 13.4+.

It is a complete internal rewrite, that gives us:

• Optimal performance (now identical to React.useState)
• Shallow mode by default
• Batched updates
• SSR in Server Components with correct query values (no more hydration tricks or errors)
• Better DX for creating and configuring parsers
• Finer control over options

Refer to the documentation for more details.

Behavioural changes

Query updates are using the following defaults, that changed from the previous version:

• scroll: false
• shallow: true

Read the options documentation to configure those behaviours.

Features

• Add hex parser (7d9e7b9)
• Add parser argument for JSON types (a2e7c3d)
• Add server-side parser utility (e225975), closes #348
• Allow server-side parser access (29d4d86), closes #348
• App router now uses history API (ba5e3e0)
• Cache returned promise until next flush (aa0619b)
• Name patched functions for better stack traces (5b7c494)
• Single app/pages implementation (f4817f5)
• Spy on all query changes (b9a24cc)
• Update to useRouter from next/navigation (a604351), closes #327

Bug Fixes

• Add file extension to next/navigation imports (bcea00d), closes #352
• Don't parse NaNs, but serialise them (4da7786)
• empty arrays include NaN after navigation (8a50113)
• ESM default export and typings files (1b164db)
• Import useQueryState from src, and not from dist (1f65c20)
• No need to encode JSON (65ad3c9), closes /github.com/47ng/next-usequerystate/discussions/343#discussioncomment-6984110
• Parser builder requires a serializer (432ed56)
• Pass through the unused title parameter (731bde4)
• Patch history before navigation occurs (f31bead)
• Race condition with navigation (be7b5bb), closes /github.com/47ng/next-usequerystate/discussions/343#discussioncomment-6975945
• Reduce package size by hotlinking GIF (000aa62)
• State updater function should be based on state (f788381)
• Use re-exports rather than symlinks (7bde5a1)
• useInsertionEffect for useQueryStates (8b8b2e9)
• Version .d.ts redirection files (e90b752)

Deprecations

The queryTypes parser bag is marked as deprecated, as it wasn't tree-shakeable. It is replaced by individual parsers.

- import { useQueryState, queryTypes } from 'next-usequerystate'
+ import { useQueryState, parseAsInteger } from 'next-usequerystate'

- useQueryState('counter', queryTypes.integer.withDefault(0))
+ useQueryState('counter', parseAsInteger.withDefault(0))

Some internal type definitions have been renamed for consistency across the codebase.
Since they were exported, the change is retro-compatible with deprecation notices on the old type names.

Those deprecated exports will be removed in the next major version (2.0.0).

Credits

A big thanks to all who have helped testing the beta versions, and especially:

• @andreisocaciu for laying the ground work (#328).
• @caillou for early performance testing.
• @tacomanator for fishing out two race-conditions on initial navigation (#343).
• @ryan-walsh-forte for uncovering a race condition in state updater functions (#345).
• @r1chm8 for the idea of making the parsers server-side accessible to let server components hydrate and validate query values (#348).
• @jdddog for uncovering issues with module resolution (#352).

Full Changelog: v1.7.3...v1.8.0