Move React framework docs (Next.js/TanStack Start) to their own category (#41328)

Nicolapps · Convex, Inc. · commit b7174f497c53 · 2025-09-25T23:29:46.000Z
This moves the Next.js and TanStack Start docs out of the React category and creates new categories. There is now a TanStack category that contains the doc for both TanStack Query and TanStack Start. I also added a short section in the Next.js docs that leads to the React library docs and moved the Next.js server rendering docs above.

GitOrigin-RevId: 9fdf6988ce6a22900bc04387531201658d51060f
diff --git a/npm-packages/demos/nextjs-pages-router/README.md b/npm-packages/demos/nextjs-pages-router/README.md
@@ -17,7 +17,7 @@ Convex functions were added to the `convex/` directory and a provider was added
 to `_app.tsx`.
 
 To learn more about using Convex with Next.js, see the
-[Convex Next.js documentation](https://docs.convex.dev/client/react/nextjs)!
+[Convex Next.js documentation](https://docs.convex.dev/client/nextjs)!
 
 ## Running the App
 
diff --git a/npm-packages/docs/_redirects b/npm-packages/docs/_redirects
@@ -77,10 +77,10 @@
 /using/indexes                      /database/indexes
 /using/integrations/airbyte         /database/import-export/streaming
 /using/integrations/external-functions /functions/http-actions
-/using/integrations/nextjs          /client/react/nextjs
+/using/integrations/nextjs          /client/nextjs
 /using/integrations/react-native    /client/react-native
 /using/integrations/s3-photo-upload /file-storage
-/using/nextjs                       /client/react/nextjs
+/using/nextjs                       /client/nextjs
 /using/optimistic-updates           /client/react/optimistic-updates
 /using/pagination                   /database/pagination
 /using/project-setup                /client/react/deployment-urls
@@ -99,9 +99,16 @@
 /using/writing-convex-functions     /functions
 /vector_search                      /vector-search
 /vector-search                      /search/vector-search
-/client/react/nextjs/pages          /client/react/nextjs-pages-router
-/client/react/nextjs/pages-quickstart    /client/react/nextjs-pages-router/quickstart
+/client/react/nextjs/pages          /client/nextjs/pages-router
+/client/react/nextjs/pages-quickstart    /client/nextjs/pages-router/quickstart
 /client/react/quickstart-create-react-app    /quickstart/react
+/client/react/nextjs/               /client/nextjs/app-router/
+/client/react/nextjs/server-rendering  /client/nextjs/app-router/server-rendering
+/client/react/tanstack-start/       /client/tanstack/tanstack-start/
+/client/react/tanstack-start/tanstack-start-with-clerk    /client/tanstack/tanstack-start/clerk
+/client/nextjs/                     /client/nextjs/app-router/
+/client/tanstack                    /client/tanstack/tanstack-query
+/client/tanstack-query              /client/tanstack/tanstack-query
 /deployments                        /dashboard/deployments
 /database/import-export/streaming /production/integrations/streaming-import-export
 /auth/custom-auth                   /auth/advanced/custom-auth
diff --git a/npm-packages/docs/docs/auth/auth0.mdx b/npm-packages/docs/docs/auth/auth0.mdx
@@ -20,7 +20,7 @@ multi-factor authentication, and single sign on and basic user management.
 [Convex Authentication with Auth0](https://github.com/get-convex/convex-demos/tree/main/users-and-auth)
 
 If you're using Next.js see the
-[Next.js setup guide](https://docs.convex.dev/client/react/nextjs).
+[Next.js setup guide](https://docs.convex.dev/client/nextjs).
 
 ## Get started
 
diff --git a/npm-packages/docs/docs/auth/clerk.mdx b/npm-packages/docs/docs/auth/clerk.mdx
@@ -431,7 +431,7 @@ follow the [Convex Next.js Quickstart](/quickstart/nextjs.mdx) first. Then:
 [Tanstack Start with Convex and Clerk](https://github.com/get-convex/templates/tree/main/template-tanstack-start)
 
 See the
-[Tanstack Start with Clerk guide](/client/react/tanstack-start/clerk.mdx) for
+[Tanstack Start with Clerk guide](/client/tanstack/tanstack-start/clerk.mdx) for
 more information.
 
 ## Next steps
diff --git a/npm-packages/docs/docs/auth/debug.mdx b/npm-packages/docs/docs/auth/debug.mdx
@@ -30,9 +30,9 @@ To handle this, you can either:
    on the client
 
 If you are using `fetchQuery` for
-[Next.js Server Rendering](/client/react/nextjs/nextjs-server-rendering.mdx),
-make sure you are explicitly passing in a JWT token as documented
-[here](/client/react/nextjs/nextjs-server-rendering.mdx#server-side-authentication).
+[Next.js Server Rendering](/client/nextjs/app-router/server-rendering.mdx), make
+sure you are explicitly passing in a JWT token as documented
+[here](/client/nextjs/app-router/server-rendering.mdx#server-side-authentication).
 
 If this hasn't helped, follow the steps below to resolve your issue.
 
diff --git a/npm-packages/docs/docs/client/nextjs/app-router/_category_.json b/npm-packages/docs/docs/client/nextjs/app-router/_category_.json
@@ -0,0 +1,4 @@
+{
+  "label": "App Router",
+  "position": 10
+}
diff --git a/npm-packages/docs/docs/client/nextjs/app-router/index.mdx b/npm-packages/docs/docs/client/nextjs/app-router/index.mdx
@@ -17,14 +17,42 @@ with Convex, Next.js provides:
 and more!
 
 This page covers the App Router variant of Next.js. Alternatively see the
-[Pages Router](/client/react/nextjs-pages-router/nextjs-pages-router.mdx)
-version of this page.
+[Pages Router](/client/nextjs/pages-router/index.mdx) version of this page.
 
 ## Getting started
 
 Follow the [Next.js Quickstart](/quickstart/nextjs.mdx) to add Convex to a new
 or existing Next.js project.
 
+## Calling Convex functions from client code
+
+To fetch and edit the data in your database from client code, use hooks of the
+[Convex React library](/client/react).
+
+<CardLink
+  className="convex-hero-card"
+  item={{
+    href: "/client/react",
+    label: "Convex React library documentation",
+  }}
+/>
+
+## Server rendering (SSR)
+
+Next.js automatically renders both Client and Server Components on the server
+during the initial page load.
+
+To keep your UI
+[automatically reactive](/functions/query-functions.mdx#caching--reactivity--consistency)
+to changes in your Convex database it needs to use Client Components. The
+`ConvexReactClient` will maintain a connection to your deployment and will get
+updates as data changes and that must happen on the client.
+
+See the dedicated
+[Server Rendering](/client/nextjs/app-router/server-rendering.mdx) page for more
+details about preloading data for Client Components, fetching data and
+authentication in Server Components, and implementing Route Handlers.
+
 ## Adding authentication
 
 ### Client-side only
@@ -92,19 +120,3 @@ mutations, and actions in server components and API routes.
 Obtain the appropriate OpenID Identity JWT in both locations and you should be
 able to use any auth provider. See
 [Custom Auth](https://docs.convex.dev/auth/advanced/custom-auth) for more.
-
-## Server rendering (SSR)
-
-Next.js automatically renders both Client and Server Components on the server
-during the initial page load.
-
-To keep your UI
-[automatically reactive](/functions/query-functions.mdx#caching--reactivity--consistency)
-to changes in your Convex database it needs to use Client Components. The
-`ConvexReactClient` will maintain a connection to your deployment and will get
-updates as data changes and that must happen on the client.
-
-See the dedicated
-[Server Rendering](/client/react/nextjs/nextjs-server-rendering.mdx) page for
-more details about preloading data for Client Components, fetching data and
-authentication in Server Components, and implementing Route Handlers.
diff --git a/npm-packages/docs/docs/client/nextjs/app-router/server-rendering.mdx b/npm-packages/docs/docs/client/nextjs/app-router/server-rendering.mdx
@@ -1,6 +1,5 @@
 ---
 title: "Next.js Server Rendering"
-slug: "server-rendering"
 sidebar_label: "Server Rendering"
 sidebar_position: 10
 description:
diff --git a/npm-packages/docs/docs/client/nextjs/pages-router/_category_.json b/npm-packages/docs/docs/client/nextjs/pages-router/_category_.json
@@ -0,0 +1,4 @@
+{
+  "label": "Pages Router",
+  "position": 20
+}
diff --git a/npm-packages/docs/docs/client/nextjs/pages-router/index.mdx b/npm-packages/docs/docs/client/nextjs/pages-router/index.mdx
@@ -1,6 +1,5 @@
 ---
 title: "Next.js Pages Router"
-slug: "nextjs-pages-router"
 sidebar_position: 250
 sidebar_label: "Next.js Pages Router"
 description:
@@ -12,12 +11,12 @@ import simpleAuthedAppTSX from "!!raw-loader!@site/../demos/nextjs-pages-router/
 import apiTS from "!!raw-loader!@site/../demos/nextjs-pages-router/pages/api/clicks.ts";
 
 This pages covers the Pages Router variant of Next.js. Alternatively see the
-[App Router](/client/react/nextjs/nextjs.mdx) version of this page.
+[App Router](/client/nextjs/app-router/index.mdx) version of this page.
 
 ## Getting started
 
 Follow the
-[Next.js Pages Router Quickstart](/client/react/nextjs-pages-router/quickstart-nextjs-pages-router.mdx)
+[Next.js Pages Router Quickstart](/client/nextjs/pages-router/quickstart-nextjs-pages-router.mdx)
 to add Convex to a new or existing Next.js project.
 
 ## Adding client-side authentication
@@ -96,5 +95,5 @@ third argument of `fetchQuery`.
 
 To preload data on server side before rendering a reactive query on the client
 side use [`preloadQuery`](/api/modules/nextjs#preloadquery). Check out the
-[App Router version of these docs](/client/react/nextjs/nextjs-server-rendering.mdx)
+[App Router version of these docs](/client/nextjs/app-router/server-rendering.mdx)
 for more details.
diff --git a/npm-packages/docs/docs/client/nextjs/pages-router/quickstart-nextjs-pages-router.mdx b/npm-packages/docs/docs/client/nextjs/pages-router/quickstart-nextjs-pages-router.mdx
diff --git a/npm-packages/docs/docs/client/tanstack/tanstack-query/_category_.json b/npm-packages/docs/docs/client/tanstack/tanstack-query/_category_.json
@@ -0,0 +1,4 @@
+{
+  "label": "TanStack Query",
+  "position": 10
+}
diff --git a/npm-packages/docs/docs/client/tanstack/tanstack-query/index.mdx b/npm-packages/docs/docs/client/tanstack/tanstack-query/index.mdx
@@ -1,7 +1,6 @@
 ---
 title: "Convex with TanStack Query"
 sidebar_label: "TanStack Query"
-sidebar_position: 325
 description:
   "Integrate Convex with TanStack Query for advanced data fetching patterns"
 ---
diff --git a/npm-packages/docs/docs/client/tanstack/tanstack-start/_category_.json b/npm-packages/docs/docs/client/tanstack/tanstack-start/_category_.json
@@ -0,0 +1,4 @@
+{
+  "label": "TanStack Start",
+  "position": 20
+}
diff --git a/npm-packages/docs/docs/client/tanstack/tanstack-start/clerk.mdx b/npm-packages/docs/docs/client/tanstack/tanstack-start/clerk.mdx
@@ -1,8 +1,6 @@
 ---
 title: "TanStack Start with Clerk"
-slug: "tanstack-start-with-clerk"
 sidebar_label: With Clerk
-sidebar_position: 10
 description:
   "Learn how to integrate Clerk authentication with Convex in TanStack Start
   applications using ID tokens and ConvexProviderWithClerk."
@@ -53,5 +51,5 @@ and modifying `app/routes/__root.tsx` like this:
 />
 
 Now all queries, mutations and action made with
-[TanStack Query](/client/tanstack-query.mdx) will be authenticated by a Clerk
-identity token.
+[TanStack Query](/client/tanstack/tanstack-query/index.mdx) will be
+authenticated by a Clerk identity token.
diff --git a/npm-packages/docs/docs/client/tanstack/tanstack-start/index.mdx b/npm-packages/docs/docs/client/tanstack/tanstack-start/index.mdx
@@ -1,7 +1,6 @@
 ---
 title: "TanStack Start"
 sidebar_label: "TanStack Start"
-sidebar_position: 180
 description: "How Convex works with TanStack Start"
 ---
 
@@ -20,8 +19,9 @@ and more!
 
 This page describes the recommended way to use Convex with TanStack Start, via
 React Query. The standard Convex React hooks work also with TanStack Start
-without React Query, as do the [React Query hooks](/client/tanstack-query.mdx)
-without TanStack Start! But using all three is a sweet spot.
+without React Query, as do the
+[React Query hooks](/client/tanstack/tanstack-query/index.mdx) without TanStack
+Start! But using all three is a sweet spot.
 
 <Admonition type="caution" title="TanStack Start is in Beta">
   TanStack Start is a new React framework currently in beta. You can use it
@@ -35,8 +35,9 @@ Convex to a new TanStack Start project.
 
 ## Using Convex with React Query
 
-You can read more about [React Query hooks](/client/tanstack-query.mdx), but a
-few highlights relevant to TanStack Start.
+You can read more about
+[React Query hooks](/client/tanstack/tanstack-query/index.mdx), but a few
+highlights relevant to TanStack Start.
 
 ### Staying subscribed to queries
 
@@ -117,6 +118,6 @@ Client-side authentication in Start works the way
 works in React because TanStack Start works well as a client-side framework.
 
 To use Clerk auth to make authenticated Convex calls on the server as well see
-the [TanStack Start + Clerk guide](/client/react/tanstack-start/clerk.mdx).
+the [TanStack Start + Clerk guide](/client/tanstack/tanstack-start/clerk.mdx).
 
 Clerk is an official partner of TanStack, see our setup guide.
diff --git a/npm-packages/docs/docs/quickstart/nextjs.mdx b/npm-packages/docs/docs/quickstart/nextjs.mdx
@@ -23,8 +23,8 @@ with Next.js.
 
 Once you've gotten started, see how to set up
 [hosting](/production/hosting/hosting.mdx),
-[server rendering](/client/react/nextjs/nextjs-server-rendering.mdx), and
-[auth](https://docs.convex.dev/client/react/nextjs/).
+[server rendering](/client/nextjs/app-router/server-rendering.mdx), and
+[auth](https://docs.convex.dev/client/nextjs/).
 
 </Admonition>
 
@@ -44,7 +44,7 @@ Learn how to query data from Convex in a Next.js app using the App Router
 and<LanguageSelector verbose />
 
 Alternatively see the
-[Pages Router](/client/react/nextjs-pages-router/quickstart-nextjs-pages-router.mdx)
+[Pages Router](/client/nextjs/pages-router/quickstart-nextjs-pages-router.mdx)
 version of this quickstart.
 
 <StepByStep>
@@ -179,4 +179,4 @@ version of this quickstart.
 
 </StepByStep>
 
-See the complete [Next.js documentation](/client/react/nextjs/nextjs.mdx).
+See the complete [Next.js documentation](/client/nextjs/app-router/index.mdx).
diff --git a/npm-packages/docs/docs/quickstart/tanstack-start.mdx b/npm-packages/docs/docs/quickstart/tanstack-start.mdx
@@ -31,7 +31,7 @@ To get setup quickly with Convex and TanStack Start run
 or follow the guide below.
 
 To use Clerk with Convex and TanStack Start, see the
-[TanStack Start + Clerk guide](/client/react/tanstack-start/clerk.mdx)
+[TanStack Start + Clerk guide](/client/tanstack/tanstack-start/clerk.mdx)
 
 ---
 
@@ -178,5 +178,5 @@ TanStack Start app in it.
 </StepByStep>
 
 For more see the
-[TanStack Start with Convex](/client/react/tanstack-start/tanstack-start.mdx)
-client documentation page.
+[TanStack Start with Convex](/client/tanstack/tanstack-start/index.mdx) client
+documentation page.
diff --git a/npm-packages/docs/sidebars.js b/npm-packages/docs/sidebars.js
@@ -213,10 +213,18 @@ const sidebars = {
       className: "convex-sidebar-react",
     },
     {
-      type: "doc",
-      id: "client/tanstack-query",
-      label: "React Query",
-      className: "convex-sidebar-tanstack",
+      type: "category",
+      label: "Next.js",
+      link: { type: "doc", id: "client/nextjs/app-router/index" },
+      items: [{ type: "autogenerated", dirName: "client/nextjs" }],
+      className: "convex-sidebar-nextjs convex-sidebar-no-category-page",
+    },
+    {
+      type: "category",
+      label: "TanStack",
+      link: { type: "doc", id: "client/tanstack/tanstack-query/index" },
+      items: [{ type: "autogenerated", dirName: "client/tanstack" }],
+      className: "convex-sidebar-tanstack convex-sidebar-no-category-page",
     },
     {
       type: "doc",
diff --git a/npm-packages/docs/src/css/custom.css b/npm-packages/docs/src/css/custom.css
@@ -1002,6 +1002,10 @@ html[data-theme="dark"] .convex-menu-header {
   --convex-icon: url("../../static/img/sidebar-icons/svelte.svg");
 }
 
+.convex-sidebar-nextjs {
+  --convex-icon: url("../../static/img/sidebar-icons/nextjs.svg");
+}
+
 .convex-sidebar-tanstack {
   --convex-icon: url("../../static/img/sidebar-icons/tanstack.svg");
 }
diff --git a/npm-packages/docs/static/img/sidebar-icons/nextjs.svg b/npm-packages/docs/static/img/sidebar-icons/nextjs.svg
@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 180 180" width="15"><mask height="180" id=":r8:mask0_408_134" maskUnits="userSpaceOnUse" width="180" x="0" y="0" style="mask-type: alpha;"><circle cx="90" cy="90" fill="black" r="90"></circle></mask><g mask="url(#:r8:mask0_408_134)"><circle cx="90" cy="90" data-circle="true" fill="black" r="90"></circle><path d="M149.508 157.52L69.142 54H54V125.97H66.1136V69.3836L139.999 164.845C143.333 162.614 146.509 160.165 149.508 157.52Z" fill="url(#:r8:paint0_linear_408_134)"></path><rect fill="url(#:r8:paint1_linear_408_134)" height="72" width="12" x="115" y="54"></rect></g><defs><linearGradient gradientUnits="userSpaceOnUse" id=":r8:paint0_linear_408_134" x1="109" x2="144.5" y1="116.5" y2="160.5"><stop stop-color="white"></stop><stop offset="1" stop-color="white" stop-opacity="0"></stop></linearGradient><linearGradient gradientUnits="userSpaceOnUse" id=":r8:paint1_linear_408_134" x1="121" x2="120.799" y1="54" y2="106.875"><stop stop-color="white"></stop><stop offset="1" stop-color="white" stop-opacity="0"></stop></linearGradient></defs></svg>

-Original file line number
+Diff line change
@@ @@ -0,0 +1,4 @@ @@
 +{
 +  "label": "App Router",
 +  "position": 10
 +}