orpc-nuxt 0.3.1 → 0.4.0

package/README.md

@@ -289,9 +289,42 @@ Relative URLs resolve against the current request URL during SSR.
 Only headers listed in `forwardHeaders` are forwarded from the incoming SSR request.
 `credentials: "include"` allows browser cookies on cross-origin requests.
 
+### Custom link
+
+Return a custom `link` when the server needs a request-scoped transport while the browser should keep a regular HTTP transport:
+
+```ts
+// app/plugins/orpc.ts
+import { RPCLink } from "@orpc/client/fetch"
+import type { RouterClient } from "@orpc/server"
+import { getRequestURL } from "h3"
+import { defineNuxtPlugin } from "orpc-nuxt/plugin"
+import type { router } from "~~/server/rpc/router"
+
+export default defineNuxtPlugin<RouterClient<typeof router>>(() => ({
+  link: ({ event }) => {
+    if (!event) return new RPCLink({ url: "/api/rpc" })
+
+    const requestFetch = event.context.nuxtMultiApp.createFetch("web")
+    const endpoint = new URL("/api/rpc", getRequestURL(event))
+
+    return new RPCLink({
+      origin: endpoint.origin,
+      url: endpoint.pathname as `/${string}`,
+      fetch: requestFetch,
+    })
+  },
+}))
+```
+
+The link factory receives `{ nuxtApp, event }`, where `event` is the current H3 event during SSR and `undefined` in the browser.
+It runs once per Nuxt application, so every SSR request gets its own link.
+The plugin setup callback has the same lifecycle: once per SSR request and once when the browser app starts.
+`orpc-nuxt` still creates the typed client, decorates it with Vue Query composables, and provides `$orpc`.
+
 ### Manual client setup
 
-Use `createORPCNuxtClient` when you need a custom transport or want SSR to call the router directly.
+Use `createORPCNuxtClient` when you want SSR to call the router directly or need to own the complete client setup.
 Instead of the shared HTTP plugin above, add a browser plugin and a server plugin.
 
 Keep `orpc-nuxt` in `modules`: manual setup replaces that plugin, not the module that installs the QueryClient and the composables.

package/dist/module.json

@@ -4,7 +4,7 @@
   "compatibility": {
     "nuxt": "^3.14.1592 || ^4.0.1"
   },
-  "version": "0.3.1",
+  "version": "0.4.0",
   "builder": {
     "@nuxt/module-builder": "1.0.3",
     "unbuild": "3.6.1"

package/dist/runtime/nuxt/define-plugin.d.ts

@@ -1,8 +1,23 @@
-import { type AnyNestedClient } from "@orpc/client";
+import { type AnyNestedClient, type ClientLink, type InferClientContext } from "@orpc/client";
 import { type NuxtApp, type Plugin } from "nuxt/app";
 import type { ORPCNuxtClient, ORPCNuxtClientOptions } from "../types.js";
-/** Configure the HTTP transport and cache used by a Nuxt app's injected oRPC client. */
-export interface OrpcPluginOptions extends ORPCNuxtClientOptions {
+/** Nuxt state available while creating one app's custom oRPC link. */
+export interface OrpcLinkContext {
+    /** The Nuxt application that will own the client. */
+    nuxtApp: NuxtApp;
+    /** The current H3 request event during SSR, or undefined in the browser. */
+    event: NonNullable<NuxtApp["ssrContext"]>["event"] | undefined;
+}
+/** Configure the transport and cache used by a Nuxt app's injected oRPC client. */
+export type OrpcPluginOptions<T extends AnyNestedClient = AnyNestedClient> = ORPCNuxtClientOptions & ({
+    /** Use an application-owned link or create one for each Nuxt application. */
+    link: ClientLink<InferClientContext<T>> | ((context: OrpcLinkContext) => ClientLink<InferClientContext<T>>);
+    url?: never;
+    serverUrl?: never;
+    credentials?: never;
+    forwardHeaders?: never;
+} | {
+    link?: never;
     /** RPC handler URL, including its path; relative URLs resolve against the current page URL. */
     url: string;
     /** Optional SSR handler URL; an absent or empty value falls back to url. */
@@ -11,13 +26,14 @@ export interface OrpcPluginOptions extends ORPCNuxtClientOptions {
     credentials?: RequestCredentials;
     /** Incoming headers to forward during SSR; only explicitly listed headers are forwarded. */
     forwardHeaders?: readonly string[];
-}
+});
 /**
- * Create an HTTP client per Nuxt app and provide it as $orpc with inferred router types.
+ * Create an oRPC client per Nuxt app and provide it as $orpc with inferred router types.
  * The setup callback runs once per SSR request and once when the browser app starts.
+ * A custom link factory also runs once per app and receives its Nuxt app and H3 event.
  * Install Vue Query before this plugin, or return an explicit queryClient from setup.
  * Its QueryClient is captured immediately, so invalidate works before any composable runs.
  */
-export declare function defineNuxtPlugin<T extends AnyNestedClient>(setup: (nuxtApp: NuxtApp) => OrpcPluginOptions): Plugin<{
+export declare function defineNuxtPlugin<T extends AnyNestedClient>(setup: (nuxtApp: NuxtApp) => OrpcPluginOptions<T>): Plugin<{
     orpc: ORPCNuxtClient<T>;
 }>;

package/dist/runtime/nuxt/define-plugin.js

@@ -1,4 +1,6 @@
-import { createORPCClient } from "@orpc/client";
+import {
+  createORPCClient
+} from "@orpc/client";
 import { RPCLink } from "@orpc/client/fetch";
 import {
   defineNuxtPlugin as createNuxtPlugin,
@@ -16,25 +18,7 @@ export function defineNuxtPlugin(setup) {
         "orpc-nuxt: install Vue Query before the oRPC plugin. Enable the module's QueryClient, use enforce: 'pre' in your Vue Query plugin, or pass queryClient explicitly."
       );
     }
-    const url = import.meta.server ? options.serverUrl || options.url : options.url;
-    const endpoint = new URL(url, useRequestURL());
-    if (endpoint.protocol !== "http:" && endpoint.protocol !== "https:") {
-      throw new Error("orpc-nuxt: the RPC handler URL must use HTTP or HTTPS.");
-    }
-    const link = new RPCLink({
-      // oRPC v2 accepts the origin separately from the handler path and query string.
-      origin: endpoint.origin,
-      // HTTP URL.pathname always starts with the slash required by StandardUrl.
-      url: `${endpoint.pathname}${endpoint.search}`,
-      // An explicit empty list is essential: undefined would forward every incoming header.
-      headers: useRequestHeaders([...options.forwardHeaders ?? []]),
-      fetch(url2, init) {
-        return globalThis.fetch(url2, {
-          ...init,
-          credentials: options.credentials
-        });
-      }
-    });
+    const link = typeof options.link === "function" ? options.link({ nuxtApp, event: nuxtApp.ssrContext?.event }) : options.link ?? createHTTPLink(options);
     const client = createORPCClient(link);
     const orpc = createORPCNuxtClient(client, {
       prefix: options.prefix,
@@ -45,3 +29,24 @@ export function defineNuxtPlugin(setup) {
     };
   });
 }
+function createHTTPLink(options) {
+  const url = import.meta.server ? options.serverUrl || options.url : options.url;
+  const endpoint = new URL(url, useRequestURL());
+  if (endpoint.protocol !== "http:" && endpoint.protocol !== "https:") {
+    throw new Error("orpc-nuxt: the RPC handler URL must use HTTP or HTTPS.");
+  }
+  return new RPCLink({
+    // oRPC v2 accepts the origin separately from the handler path and query string.
+    origin: endpoint.origin,
+    // HTTP URL.pathname always starts with the slash required by StandardUrl.
+    url: `${endpoint.pathname}${endpoint.search}`,
+    // An explicit empty list is essential: undefined would forward every incoming header.
+    headers: useRequestHeaders([...options.forwardHeaders ?? []]),
+    fetch(url2, init) {
+      return globalThis.fetch(url2, {
+        ...init,
+        credentials: options.credentials
+      });
+    }
+  });
+}

package/dist/runtime/plugin.d.ts

@@ -1,2 +1,2 @@
 export { defineNuxtPlugin } from "./nuxt/define-plugin.js";
-export type { OrpcPluginOptions } from "./nuxt/define-plugin.js";
+export type { OrpcLinkContext, OrpcPluginOptions } from "./nuxt/define-plugin.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "orpc-nuxt",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "oRPC integration for Nuxt with TanStack Vue Query composables.",
   "homepage": "https://github.com/IlyaSemenov/orpc-nuxt#readme",
   "bugs": "https://github.com/IlyaSemenov/orpc-nuxt/issues",