Skip to content

Commit 9f6df68

Browse files
franky47franky47
committedOct 21, 2024
doc: Add adapters docs
1 parent acc988a commit 9f6df68

File tree

6 files changed

+135
-32
lines changed

6 files changed

+135
-32
lines changed
 

Diff for: ‎errors/NUQS-404.md

+8-24
Original file line numberDiff line numberDiff line change
@@ -5,35 +5,19 @@
55
You haven't wrapped the components calling `useQueryState(s)` with
66
an adapter.
77

8-
Adapters are based on React Context, and provide nuqs hooks with
9-
the interfaces to work with your framework.
8+
[Adapters](https://nuqs.47ng.com/docs/adapters) are based on React Context,
9+
and provide nuqs hooks with the interfaces to work with your framework.
1010

1111
## Possible solutions
1212

1313
Follow the setup instructions to import and wrap your application
14-
using a suitable adapter.
14+
using a suitable adapter:
1515

16-
Example, for Next.js (app router)
17-
18-
```tsx
19-
// src/app/layout.tsx
20-
import React from 'react'
21-
import { NuqsAdapter } from 'nuqs/adapters/next'
22-
23-
export default function RootLayout({
24-
children
25-
}: {
26-
children: React.ReactNode
27-
}) {
28-
return (
29-
<html>
30-
<body>
31-
<NuqsAdapter>{children}</NuqsAdapter>
32-
</body>
33-
</html>
34-
)
35-
}
36-
```
16+
- [Next.js (app router)](https://nuqs.47ng.com/docs/adapters#nextjs-app-router)
17+
- [Next.js (pages router)](https://nuqs.47ng.com/docs/adapters#nextjs-pages-router)
18+
- [React SPA (eg: with Vite)](https://nuqs.47ng.com/docs/adapters#react-spa)
19+
- [Remix](https://nuqs.47ng.com/docs/adapters#remix)
20+
- [React Router](https://nuqs.47ng.com/docs/adapters#react-router)
3721

3822
### Test adapter
3923

Diff for: ‎packages/docs/content/docs/adapters.mdx

+109
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,109 @@
1+
---
2+
title: Adapters
3+
description: Using nuqs in your React framework of choice
4+
---
5+
6+
Since version 2, you can now use nuqs in the following React frameworks, by
7+
wrapping it with a `NuqsAdapter` context provider:
8+
9+
- [Next.js (app router)](#nextjs-app-router)
10+
- [Next.js (pages router)](#nextjs-pages-router)
11+
- [React SPA (eg: with Vite)](#react-spa)
12+
- [Remix](#remix)
13+
- [React Router](#react-router)
14+
15+
## Next.js (app router)
16+
17+
```tsx title="src/app/layout.tsx"
18+
// [!code word:NuqsAdapter]
19+
import { NuqsAdapter } from 'nuqs/adapters/next/app'
20+
import { type ReactNode } from 'react'
21+
22+
export default function RootLayout({
23+
children
24+
}: {
25+
children: ReactNode
26+
}) {
27+
return (
28+
<html>
29+
<body>
30+
<NuqsAdapter>{children}</NuqsAdapter>
31+
</body>
32+
</html>
33+
)
34+
}
35+
```
36+
37+
## Next.js (pages router)
38+
39+
```tsx title="src/pages/_app.tsx"
40+
// [!code word:NuqsAdapter]
41+
import type { AppProps } from 'next/app'
42+
import { NuqsAdapter } from 'nuqs/adapters/next/pages'
43+
44+
export default function MyApp({ Component, pageProps }: AppProps) {
45+
return (
46+
<NuqsAdapter>
47+
<Component {...pageProps} />
48+
</NuqsAdapter>
49+
)
50+
}
51+
```
52+
53+
The main reason for adapters is to open up nuqs to other React frameworks:
54+
55+
## React SPA
56+
57+
Example, with Vite:
58+
59+
```tsx title="src/main.tsx"
60+
// [!code word:NuqsAdapter]
61+
import { NuqsAdapter } from 'nuqs/adapters/react'
62+
63+
createRoot(document.getElementById('root')!).render(
64+
<NuqsAdapter>
65+
<App />
66+
</NuqsAdapter>
67+
)
68+
```
69+
70+
## Remix
71+
72+
```tsx title="app/root.tsx"
73+
// [!code word:NuqsAdapter]
74+
import { NuqsAdapter } from 'nuqs/adapters/remix'
75+
76+
// ...
77+
78+
export default function App() {
79+
return (
80+
<NuqsAdapter>
81+
<Outlet />
82+
</NuqsAdapter>
83+
)
84+
}
85+
```
86+
87+
## React Router
88+
89+
```tsx title="src/main.tsx"
90+
// [!code word:NuqsAdapter]
91+
import { NuqsAdapter } from 'nuqs/adapters/react-router'
92+
import { createBrowserRouter, RouterProvider } from 'react-router-dom'
93+
import App from './App'
94+
95+
const router = createBrowserRouter([
96+
{
97+
path: '/',
98+
element: <App />
99+
}
100+
])
101+
102+
export function ReactRouter() {
103+
return (
104+
<NuqsAdapter>
105+
<RouterProvider router={router} />
106+
</NuqsAdapter>
107+
)
108+
}
109+
```

Diff for: ‎packages/docs/content/docs/basic-usage.mdx

+5
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,11 @@ import {
99
GreetingsPrompt
1010
} from '@/content/docs/parsers/demos'
1111

12+
<Callout title="Prerequisite">
13+
Have you setup your app with the appropriate [**adapter**](./adapters)? Then you
14+
are all set!
15+
</Callout>
16+
1217
If you are using `React.useState` to manage your local UI state,
1318
you can replace it with `useQueryState` to sync it with the URL.
1419

Diff for: ‎packages/docs/content/docs/installation.mdx

+9-8
Original file line numberDiff line numberDiff line change
@@ -23,11 +23,12 @@ bun add nuqs
2323

2424
## Which version should I use?
2525

26-
| Next.js version range | Supported `nuqs` version |
27-
| ----------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------- |
28-
| >= 14.2.0 | `nuqs@latest` |
29-
| >=14.0.4 && \<\= 14.1.4 | `nuqs@^1` |
30-
| 14.0.3 | `nuqs@^1`, with the `windowHistorySupport` experimental flag, see [#417](https://github.com/47ng/nuqs/issues/417) |
31-
| 14.0.2 | Not compatible, see issue [#388](https://github.com/47ng/nuqs/issues/388) and Next.js PR [#58297](https://github.com/vercel/next.js/pull/58297) |
32-
| >= 13.1 && \<\= 14.0.1 | `nuqs@^1` |
33-
| < 13.1 | `next-usequerystate@1.7.3` |
26+
`nuqs` supports the following frameworks and their respective versions:
27+
28+
- [Next.js](./adapters#nextjs-app-router): 14.2.0 and above (including Next.js 15)
29+
- [React SPA](./adapters#react-spa): 18.3.0 & 19 RC
30+
- [Remix](./adapters#remix): 2 and above
31+
- [React Router](./adapters#react-router): 6 and above
32+
33+
For older versions of Next.js, you may use `nuqs@^1`.
34+

Diff for: ‎packages/docs/content/docs/meta.json

+4
Original file line numberDiff line numberDiff line change
@@ -2,12 +2,16 @@
22
"title": "Documentation",
33
"root": true,
44
"pages": [
5+
"---Getting started---",
56
"installation",
7+
"adapters",
68
"basic-usage",
9+
"---Guide---",
710
"parsers",
811
"options",
912
"batching",
1013
"server-side",
14+
"---Going further---",
1115
"utilities",
1216
"debugging",
1317
"testing",

0 commit comments

Comments
 (0)