diff --git a/.gitignore b/.gitignore
index 7f7e15bc..918e298f 100644
--- a/.gitignore
+++ b/.gitignore
@@ -9,3 +9,4 @@ package-lock.json
.next/
.turbo/
.vercel
+.tsbuildinfo
diff --git a/errors/NUQS-404.md b/errors/NUQS-404.md
new file mode 100644
index 00000000..26ed0117
--- /dev/null
+++ b/errors/NUQS-404.md
@@ -0,0 +1,46 @@
+# `nuqs` requires an adapter to work with your framework
+
+## Probable cause
+
+You haven't wrapped the components calling `useQueryState(s)` with
+an adapter.
+
+Adapters are based on React Context, and provide nuqs hooks with
+the interfaces to work with your framework.
+
+## Possible solutions
+
+Follow the setup instructions to import and wrap your application
+using a suitable adapter.
+
+Example, for Next.js (app router)
+
+```tsx
+// src/app/layout.tsx
+import React from 'react'
+import { NuqsAdapter } from 'nuqs/adapters/next'
+
+export default function RootLayout({
+ children
+}: {
+ children: React.ReactNode
+}) {
+ return (
+
+
+ {children}
+
+
+ )
+}
+```
+
+### Test adapter
+
+If you encounter this error outside of the browser, like in a test
+runner, you may use the test adapter from `nuqs/adapters/test`
+to mock the context and access setup/assertion testing facilities.
+
+```tsx
+
+```
diff --git a/packages/docs/content/docs/options.mdx b/packages/docs/content/docs/options.mdx
index f958ae0a..a5f135a5 100644
--- a/packages/docs/content/docs/options.mdx
+++ b/packages/docs/content/docs/options.mdx
@@ -130,7 +130,7 @@ to get loading states while the server is re-rendering server components with
the updated URL.
Pass in the `startTransition` function from `useTransition` to the options
-to enable this behaviour _(this will set `shallow: false{:ts}` automatically for you)_:
+to enable this behaviour:
In `nuqs@2.0.0`, passing `startTransition` will no longer automatically set `shallow: false{:ts}`.
@@ -148,7 +148,7 @@ function ClientComponent({ data }) {
const [query, setQuery] = useQueryState(
'query',
// 2. Pass the `startTransition` as an option:
- parseAsString().withOptions({ startTransition })
+ parseAsString().withOptions({ startTransition, shallow: false })
)
// 3. `isLoading` will be true while the server is re-rendering
// and streaming RSC payloads, when the query is updated via `setQuery`.
@@ -161,6 +161,13 @@ function ClientComponent({ data }) {
}
```
+
+ In `nuqs@1.x.x`, passing `startTransition` as an option automatically sets
+ `shallow: false{:ts}`.
+
+ This is no longer the case in `nuqs@>=2.0.0`: you'll need to set it explicitly.
+
+
## Clear on default
By default, when the state is set to the default value, the search parameter is
diff --git a/packages/docs/src/app/playground/_demos/throttling/client.tsx b/packages/docs/src/app/playground/_demos/throttling/client.tsx
index fdefdc47..6a0fb557 100644
--- a/packages/docs/src/app/playground/_demos/throttling/client.tsx
+++ b/packages/docs/src/app/playground/_demos/throttling/client.tsx
@@ -13,6 +13,7 @@ export function Client() {
const [serverDelay, setServerDelay] = useQueryState(
'serverDelay',
delayParser.withOptions({
+ shallow: false,
startTransition: startDelayTransition
})
)
@@ -23,6 +24,7 @@ export function Client() {
const [q, setQ] = useQueryState(
'q',
queryParser.withOptions({
+ shallow: false,
throttleMs: clientDelay,
startTransition: startQueryTransition
})
diff --git a/packages/docs/src/components/ui/toggle-group.tsx b/packages/docs/src/components/ui/toggle-group.tsx
index 0a50680d..9e4d263c 100644
--- a/packages/docs/src/components/ui/toggle-group.tsx
+++ b/packages/docs/src/components/ui/toggle-group.tsx
@@ -1,17 +1,17 @@
-"use client"
+'use client'
-import * as React from "react"
-import * as ToggleGroupPrimitive from "@radix-ui/react-toggle-group"
-import { VariantProps } from "class-variance-authority"
+import * as ToggleGroupPrimitive from '@radix-ui/react-toggle-group'
+import { VariantProps } from 'class-variance-authority'
+import * as React from 'react'
-import { cn } from "@/src/lib/utils"
-import { toggleVariants } from "@/src/components/ui/toggle"
+import { toggleVariants } from '@/src/components/ui/toggle'
+import { cn } from '@/src/lib/utils'
const ToggleGroupContext = React.createContext<
VariantProps
>({
- size: "default",
- variant: "default",
+ size: 'default',
+ variant: 'default'
})
const ToggleGroup = React.forwardRef<
@@ -21,11 +21,11 @@ const ToggleGroup = React.forwardRef<
>(({ className, variant, size, children, ...props }, ref) => (
- {children}
+ <>{children}
))
@@ -45,7 +45,7 @@ const ToggleGroupItem = React.forwardRef<
className={cn(
toggleVariants({
variant: context.variant || variant,
- size: context.size || size,
+ size: context.size || size
}),
className
)}
diff --git a/packages/e2e/src/app/app/transitions/client.tsx b/packages/e2e/src/app/app/transitions/client.tsx
index 7212c76a..817bc136 100644
--- a/packages/e2e/src/app/app/transitions/client.tsx
+++ b/packages/e2e/src/app/app/transitions/client.tsx
@@ -1,14 +1,17 @@
'use client'
import { parseAsInteger, useQueryState } from 'nuqs'
-import React from 'react'
+import { useTransition } from 'react'
import { HydrationMarker } from '../../../components/hydration-marker'
export function Client() {
- const [isLoading, startTransition] = React.useTransition()
+ const [isLoading, startTransition] = useTransition()
const [counter, setCounter] = useQueryState(
'counter',
- parseAsInteger.withDefault(0).withOptions({ startTransition })
+ parseAsInteger.withDefault(0).withOptions({
+ shallow: false,
+ startTransition
+ })
)
return (
<>
diff --git a/packages/e2e/src/app/layout.tsx b/packages/e2e/src/app/layout.tsx
index 895150ad..26dccf06 100644
--- a/packages/e2e/src/app/layout.tsx
+++ b/packages/e2e/src/app/layout.tsx
@@ -1,3 +1,4 @@
+import { NuqsAdapter } from 'nuqs/adapters/next'
import React, { Suspense } from 'react'
import { HydrationMarker } from '../components/hydration-marker'
@@ -16,7 +17,7 @@ export default function RootLayout({
- {children}
+ {children}