doc: Add adapters docs

47ng · Oct 21, 2024 · 5be8e59 · 5be8e59
1 parent 45a7c90
commit 5be8e59
Show file tree

Hide file tree

Showing 6 changed files with 135 additions and 32 deletions.
diff --git a/errors/NUQS-404.md b/errors/NUQS-404.md
@@ -5,35 +5,19 @@
 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.
+[Adapters](https://nuqs.47ng.com/docs/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.
+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 (
-    <html>
-      <body>
-        <NuqsAdapter>{children}</NuqsAdapter>
-      </body>
-    </html>
-  )
-}
-```
+- [Next.js (app router)](https://nuqs.47ng.com/docs/adapters#nextjs-app-router)
+- [Next.js (pages router)](https://nuqs.47ng.com/docs/adapters#nextjs-pages-router)
+- [React SPA (eg: with Vite)](https://nuqs.47ng.com/docs/adapters#react-spa)
+- [Remix](https://nuqs.47ng.com/docs/adapters#remix)
+- [React Router](https://nuqs.47ng.com/docs/adapters#react-router)
 
 ### Test adapter
 

diff --git a/packages/docs/content/docs/adapters.mdx b/packages/docs/content/docs/adapters.mdx
@@ -0,0 +1,109 @@
+---
+title: Adapters
+description: Using nuqs in your React framework of choice
+---
+
+Since version 2, you can now use nuqs in the following React frameworks, by
+wrapping it with a `NuqsAdapter` context provider:
+
+- [Next.js (app router)](#nextjs-app-router)
+- [Next.js (pages router)](#nextjs-pages-router)
+- [React SPA (eg: with Vite)](#react-spa)
+- [Remix](#remix)
+- [React Router](#react-router)
+
+## Next.js (app router)
+
+```tsx title="src/app/layout.tsx"
+// [!code word:NuqsAdapter]
+import { NuqsAdapter } from 'nuqs/adapters/next/app'
+import { type ReactNode } from 'react'
+
+export default function RootLayout({
+  children
+}: {
+  children: ReactNode
+}) {
+  return (
+    <html>
+      <body>
+        <NuqsAdapter>{children}</NuqsAdapter>
+      </body>
+    </html>
+  )
+}
+```
+
+## Next.js (pages router)
+
+```tsx title="src/pages/_app.tsx"
+// [!code word:NuqsAdapter]
+import type { AppProps } from 'next/app'
+import { NuqsAdapter } from 'nuqs/adapters/next/pages'
+
+export default function MyApp({ Component, pageProps }: AppProps) {
+  return (
+    <NuqsAdapter>
+      <Component {...pageProps} />
+    </NuqsAdapter>
+  )
+}
+```
+
+The main reason for adapters is to open up nuqs to other React frameworks:
+
+## React SPA
+
+Example, with Vite:
+
+```tsx title="src/main.tsx"
+// [!code word:NuqsAdapter]
+import { NuqsAdapter } from 'nuqs/adapters/react'
+
+createRoot(document.getElementById('root')!).render(
+  <NuqsAdapter>
+    <App />
+  </NuqsAdapter>
+)
+```
+
+## Remix
+
+```tsx title="app/root.tsx"
+// [!code word:NuqsAdapter]
+import { NuqsAdapter } from 'nuqs/adapters/remix'
+
+// ...
+
+export default function App() {
+  return (
+    <NuqsAdapter>
+      <Outlet />
+    </NuqsAdapter>
+  )
+}
+```
+
+## React Router
+
+```tsx title="src/main.tsx"
+// [!code word:NuqsAdapter]
+import { NuqsAdapter } from 'nuqs/adapters/react-router'
+import { createBrowserRouter, RouterProvider } from 'react-router-dom'
+import App from './App'
+
+const router = createBrowserRouter([
+  {
+    path: '/',
+    element: <App />
+  }
+])
+
+export function ReactRouter() {
+  return (
+    <NuqsAdapter>
+      <RouterProvider router={router} />
+    </NuqsAdapter>
+  )
+}
+```
diff --git a/packages/docs/content/docs/basic-usage.mdx b/packages/docs/content/docs/basic-usage.mdx
@@ -9,6 +9,11 @@ import {
   GreetingsPrompt
 } from '@/content/docs/parsers/demos'
 
+<Callout title="Prerequisite">
+  Have you setup your app with the appropriate [**adapter**](./adapters)? Then you
+  are all set!
+</Callout>
+
 If you are using `React.useState` to manage your local UI state,
 you can replace it with `useQueryState` to sync it with the URL.
 

diff --git a/...ages/docs/content/docs/adapters/onejs.mdx → ...content/docs/community-adapters/onejs.mdx b/...ages/docs/content/docs/adapters/onejs.mdx → ...content/docs/community-adapters/onejs.mdx
diff --git a/packages/docs/content/docs/installation.mdx b/packages/docs/content/docs/installation.mdx
@@ -23,11 +23,12 @@ bun add nuqs
 
 ## Which version should I use?
 
-| Next.js version range   | Supported `nuqs` version                                                                                                                        |
-| ----------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------- |
-| >= 14.2.0               | `nuqs@latest`                                                                                                                                   |
-| >=14.0.4 && \<\= 14.1.4 | `nuqs@^1`                                                                                                                                       |
-| 14.0.3                  | `nuqs@^1`, with the `windowHistorySupport` experimental flag, see [#417](https://github.com/47ng/nuqs/issues/417)                               |
-| 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) |
-| >= 13.1 && \<\= 14.0.1  | `nuqs@^1`                                                                                                                                       |
-| < 13.1                  | `next-usequerystate@1.7.3`                                                                                                                      |
+`nuqs` supports the following frameworks and their respective versions:
+
+- [Next.js](./adapters#nextjs-app-router): 14.2.0 and above (including Next.js 15)
+- [React SPA](./adapters#react-spa): 18.3.0 & 19 RC
+- [Remix](./adapters#remix): 2 and above
+- [React Router](./adapters#react-router): 6 and above
+
+For older versions of Next.js, you may use `nuqs@^1`.
+
diff --git a/packages/docs/content/docs/meta.json b/packages/docs/content/docs/meta.json
@@ -2,12 +2,16 @@
   "title": "Documentation",
   "root": true,
   "pages": [
+    "---Getting started---",
     "installation",
+    "adapters",
     "basic-usage",
+    "---Guide---",
     "parsers",
     "options",
     "batching",
     "server-side",
+    "---Going further---",
     "utilities",
     "debugging",
     "testing",