docs: nuxt ssr

apps/content/docs/adapters/next.md

@@ -13,7 +13,7 @@ oRPC also provides out-of-the-box support for [Server Action](/docs/server-actio
 
 ## Server
 
-You can integrate oRPC with Next.js using its [Route Handlers](https://nextjs.org/docs/app/building-your-application/routing/route-handlers).
+You set up an oRPC server inside Next.js using its [Route Handlers](https://nextjs.org/docs/app/building-your-application/routing/route-handlers).
 
 ::: code-group
 
@@ -89,7 +89,7 @@ export const config = {
 
 ## Client
 
-Next.js doesn’t natively support isomorphic functions, so you need a workaround to make client-side code compatible with SSR. This example uses `globalThis.$headers` as that workaround. Alternatively, you can use React Context like the approach mentioned in [discussions#330](https://github.com/unnoq/orpc/discussions/330#discussioncomment-12727779).
+Next.js doesn't natively support isomorphic functions, so you need a workaround to make client-side code compatible with SSR. This example uses `globalThis.$headers` as that workaround. Alternatively, you can use React Context like the approach mentioned in [discussions#330](https://github.com/unnoq/orpc/discussions/330#discussioncomment-12727779).
 
 ::: code-group
 
@@ -177,7 +177,7 @@ globalThis.$client = createRouterClient(router, {
    * For per-request context, use middleware context or pass a function as the initial context.
    */
   context: async () => ({
-    headers: await headers(),
+    headers: await headers(), // provide headers if initial context required
   }),
 })
 ```

apps/content/docs/adapters/nuxt.md

@@ -7,7 +7,9 @@ description: Use oRPC inside an Nuxt.js project
 
 [Nuxt.js](https://nuxtjs.org/) is a popular Vue.js framework for building server-side applications. It built on top of [Nitro](https://nitro.build/) server a lightweight, high-performance Node.js runtime. For more details, see the [HTTP Adapter](/docs/adapters/http) guide.
 
-## Basic
+## Server
+
+You set up an oRPC server inside Nuxt using its [Server Routes](https://nuxt.com/docs/guide/directory-structure/server#server-routes).
 
 ::: code-group
 
@@ -44,3 +46,73 @@ export { default } from './[...]'
 ::: info
 The `handler` can be any supported oRPC handler, such as [RPCHandler](/docs/rpc-handler), [OpenAPIHandler](/docs/openapi/openapi-handler), or another custom handler.
 :::
+
+## Client
+
+To make the oRPC client compatible with SSR, set it up inside a [Nuxt Plugin](https://nuxt.com/docs/guide/directory-structure/plugins).
+
+```ts [plugins/orpc.ts]
+export default defineNuxtPlugin(() => {
+  const event = useRequestEvent()
+
+  const link = new RPCLink({
+    url: `${typeof window !== 'undefined' ? window.location.origin : 'http://localhost:3000'}/rpc`,
+    headers: () => Object.fromEntries(event?.headers ?? []),
+  })
+
+  const client: RouterClient<typeof router> = createORPCClient(link)
+
+  return {
+    provide: {
+      client,
+    },
+  }
+})
+```
+
+:::info
+You can learn more about client setup in [Client-Side Clients](/docs/client/client-side).
+:::
+
+## Optimize SSR
+
+To reduce HTTP requests and improve latency during SSR, you can utilize a [Server-Side Client](/docs/client/server-side) during SSR. Below is a quick setup, see [Optimize SSR](/docs/best-practices/optimize-ssr) for more details.
+
+::: code-group
+
+```ts [plugins/orpc.client.ts]
+export default defineNuxtPlugin(() => {
+  const link = new RPCLink({
+    url: `${window.location.origin}/rpc`,
+    headers: () => ({}),
+  })
+
+  const client: RouterClient<typeof router> = createORPCClient(link)
+
+  return {
+    provide: {
+      client,
+    },
+  }
+})
+```
+
+```ts [plugins/orpc.server.ts]
+export default defineNuxtPlugin((nuxt) => {
+  const event = useRequestEvent()
+
+  const client = createRouterClient(router, {
+    context: {
+      headers: event?.headers, // provide headers if initial context required
+    },
+  })
+
+  return {
+    provide: {
+      client,
+    },
+  }
+})
+```
+
+:::

apps/content/docs/adapters/solid-start.md

@@ -117,7 +117,7 @@ globalThis.$client = createRouterClient(router, {
     const headers = getRequestEvent()?.request.headers
 
     return {
-      headers,
+      headers, // provide headers if initial context required
     }
   },
 })

apps/content/docs/adapters/tanstack-start.md

@@ -9,7 +9,7 @@ description: Use oRPC inside a TanStack Start project
 
 ## Server
 
-You can integrate oRPC with TanStack Start using its [API Routes](https://tanstack.com/start/latest/docs/framework/react/api-routes).
+You set up an oRPC server inside TanStack Start using its [API Routes](https://tanstack.com/start/latest/docs/framework/react/api-routes).
 
 ::: code-group
 
@@ -97,7 +97,7 @@ const getORPCClient = createIsomorphicFn()
      * For per-request context, use middleware context or pass a function as the initial context.
      */
     context: async () => ({
-      headers: getHeaders(),
+      headers: getHeaders(), // provide headers if initial context required
     }),
   }))
   .client((): RouterClient<typeof router> => {

playgrounds/next/src/lib/orpc.server.ts

@@ -18,6 +18,6 @@ globalThis.$client = createRouterClient(router, {
    * For per-request context, use middleware context or pass a function as the initial context.
    */
   context: async () => ({
-    headers: await headers(),
+    headers: await headers(), // provide headers if initial context required
   }),
 })

playgrounds/nuxt/components/orpc-mutation.vue

@@ -1,13 +1,14 @@
 <script setup lang="ts">
 import { useMutation, useQueryClient } from '@tanstack/vue-query'
-import { orpc } from '~/lib/orpc'
+
+const { $orpc } = useNuxtApp()
 
 const queryClient = useQueryClient()
 
-const { mutate } = useMutation(orpc.planet.create.mutationOptions({
+const { mutate } = useMutation($orpc.planet.create.mutationOptions({
   onSuccess() {
     queryClient.invalidateQueries({
-      queryKey: orpc.planet.list.key(),
+      queryKey: $orpc.planet.list.key(),
     })
   },
   onError(error) {

playgrounds/nuxt/components/orpc-query.vue

@@ -1,12 +1,15 @@
 <script setup lang="ts">
 import { useInfiniteQuery } from '@tanstack/vue-query'
-import { orpc } from '~/lib/orpc'
 
-const query = useInfiniteQuery(orpc.planet.list.infiniteOptions({
+const { $orpc } = useNuxtApp()
+
+const query = useInfiniteQuery($orpc.planet.list.infiniteOptions({
   input: cursor => ({ cursor, limit: 10 }),
   getNextPageParam: lastPage => lastPage.length === 10 ? lastPage.at(-1)?.id : null,
   initialPageParam: 0,
 }))
+
+await query.suspense()
 </script>
 
 <template>

playgrounds/nuxt/plugins/orpc.client.ts

@@ -0,0 +1,22 @@
+import type { RouterClient } from '@orpc/server'
+import type { router } from '~/server/router'
+import { createORPCClient } from '@orpc/client'
+import { RPCLink } from '@orpc/client/fetch'
+import { createTanstackQueryUtils } from '@orpc/tanstack-query'
+
+export default defineNuxtPlugin(() => {
+  const link = new RPCLink({
+    url: `${window.location.origin}/rpc`,
+    headers: () => ({}),
+  })
+
+  const client: RouterClient<typeof router> = createORPCClient(link)
+
+  const orpc = createTanstackQueryUtils(client)
+
+  return {
+    provide: {
+      orpc,
+    },
+  }
+})

playgrounds/nuxt/plugins/orpc.server.ts

@@ -0,0 +1,26 @@
+import { createRouterClient } from '@orpc/server'
+import { router } from '~/server/router'
+import { createTanstackQueryUtils } from '@orpc/tanstack-query'
+
+/**
+ * This is part of the Optimize SSR setup.
+ *
+ * @see {@link https://orpc.unnoq.com/docs/adapters/nuxt#optimize-ssr}
+ */
+export default defineNuxtPlugin((nuxt) => {
+  const event = useRequestEvent()
+
+  const client = createRouterClient(router, {
+    context: {
+      // headers: event?.headers, // provide headers if initial context required
+    },
+  })
+
+  const orpc = createTanstackQueryUtils(client)
+
+  return {
+    provide: {
+      orpc,
+    },
+  }
+})

playgrounds/nuxt/server/routes/rpc/[...].ts

@@ -11,10 +11,7 @@ const rpcHandler = new RPCHandler(router, {
 })
 
 export default defineEventHandler(async (event) => {
-  const authorization = getHeader(event, 'authorization')
-  const context = authorization
-    ? { user: { id: 'test', name: 'John Doe', email: 'john@doe.com' } }
-    : {}
+  const context = { user: { id: 'test', name: 'John Doe', email: 'john@doe.com' } }
 
   const { matched } = await rpcHandler.handle(event.node.req, event.node.res, {
     prefix: '/rpc',

playgrounds/solid-start/src/lib/orpc.server.ts

@@ -23,7 +23,7 @@ globalThis.$client = createRouterClient(router, {
     const headers = getRequestEvent()?.request.headers
 
     return {
-      headers,
+      headers, // provide headers if initial context required
     }
   },
 })

playgrounds/tanstack-start/src/lib/orpc.ts

@@ -23,7 +23,7 @@ const getORPCClient = createIsomorphicFn()
      * For per-request context, use middleware context or pass a function as the initial context.
      */
     context: async () => ({
-      headers: getHeaders(),
+      headers: getHeaders(), // provide headers if initial context required
     }),
   }))
   .client((): RouterClient<typeof router> => {