From 5be8e595e169ff6cfc9930966c68cf4db5fc6662 Mon Sep 17 00:00:00 2001 From: Francois Best Date: Mon, 21 Oct 2024 22:46:11 +0200 Subject: [PATCH] doc: Add adapters docs --- errors/NUQS-404.md | 32 ++--- packages/docs/content/docs/adapters.mdx | 109 ++++++++++++++++++ packages/docs/content/docs/basic-usage.mdx | 5 + .../onejs.mdx | 0 packages/docs/content/docs/installation.mdx | 17 +-- packages/docs/content/docs/meta.json | 4 + 6 files changed, 135 insertions(+), 32 deletions(-) create mode 100644 packages/docs/content/docs/adapters.mdx rename packages/docs/content/docs/{adapters => community-adapters}/onejs.mdx (100%) diff --git a/errors/NUQS-404.md b/errors/NUQS-404.md index 26ed0117..5a00e7d7 100644 --- 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 ( - - - {children} - - - ) -} -``` +- [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 new file mode 100644 index 00000000..c3f662fa --- /dev/null +++ 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 ( + + + {children} + + + ) +} +``` + +## 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 ( + + + + ) +} +``` + +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( + + + +) +``` + +## Remix + +```tsx title="app/root.tsx" +// [!code word:NuqsAdapter] +import { NuqsAdapter } from 'nuqs/adapters/remix' + +// ... + +export default function App() { + return ( + + + + ) +} +``` + +## 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: + } +]) + +export function ReactRouter() { + return ( + + + + ) +} +``` diff --git a/packages/docs/content/docs/basic-usage.mdx b/packages/docs/content/docs/basic-usage.mdx index 66634b3e..52e8b576 100644 --- 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' + + Have you setup your app with the appropriate [**adapter**](./adapters)? Then you + are all set! + + 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/packages/docs/content/docs/adapters/onejs.mdx b/packages/docs/content/docs/community-adapters/onejs.mdx similarity index 100% rename from packages/docs/content/docs/adapters/onejs.mdx rename to packages/docs/content/docs/community-adapters/onejs.mdx diff --git a/packages/docs/content/docs/installation.mdx b/packages/docs/content/docs/installation.mdx index 9691da07..a26d4780 100644 --- 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 index 8505e6f4..e2706370 100644 --- 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",