orpc-nuxt 0.3.0 → 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.
@@ -454,34 +487,22 @@ Each procedure leaf in `procedures` has a `.handle()` method that registers a ty
 // test/nuxt/setup.ts
 import { mockNuxtImport } from "@nuxt/test-utils/runtime"
 import type { RouterClient } from "@orpc/server"
-import { QueryClient } from "@tanstack/vue-query"
 import { createTestORPCClient } from "orpc-nuxt/testing"
 import { afterEach } from "vitest"
 
 import type { router } from "~~/server/rpc/router"
 
-const queryClient = new QueryClient({
-  // Report a failing procedure instead of retrying it until the test times out.
-  defaultOptions: { queries: { retry: false } },
-})
-
-export const { client, procedures, reset } = createTestORPCClient<RouterClient<typeof router>>({
-  queryClient,
-})
+export const { client, procedures, reset } = createTestORPCClient<RouterClient<typeof router>>()
 
 // Return the composable itself; Vitest hoists this factory before the setup file runs.
 mockNuxtImport("useOrpc", () => () => client)
 
-afterEach(() => {
-  reset() // Remove registered handlers.
-  queryClient.clear() // Remove cached responses.
-})
+afterEach(reset)
 ```
 
 `orpc-nuxt/testing` does not import `nuxt/app`, so the hoisted `mockNuxtImport()` factory can load it safely.
-The explicit QueryClient keeps the test cache isolated and lets the setup clear it after each test.
-To use the application's QueryClient instead, omit the option and configure its defaults through `orpc.queryClient`.
-In that mode, import `useOrpcQueryClient()` only from a module that the hoisted factory cannot reach.
+The client owns a QueryClient that never retries, so a failing procedure fails the test instead of timing out, and `reset()` removes the registered handlers together with the cached responses.
+Reach that cache as `queryClient` to seed or inspect it, or pass your own to `createTestORPCClient()`; `reset()` clears that one as well.
 
 Register the required handlers before mounting; `mountSuspended()` waits for awaited queries before assertions:
 

package/dist/module.json

@@ -4,7 +4,7 @@
   "compatibility": {
     "nuxt": "^3.14.1592 || ^4.0.1"
   },
-  "version": "0.3.0",
+  "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/dist/runtime/testing.d.ts

@@ -1,4 +1,5 @@
 import type { AnyNestedClient, Client } from "@orpc/client";
+import { QueryClient } from "@tanstack/vue-query";
 import type { Mock } from "vitest";
 import type { ORPCNuxtClient, ORPCNuxtClientOptions } from "./types.js";
 type MaybePromise<T> = T | Promise<T>;
@@ -19,7 +20,9 @@ export interface TestORPCClient<T extends AnyNestedClient> {
     client: ORPCNuxtClient<T>;
     /** Register typed implementations and receive Vitest mocks for call assertions. */
     procedures: TestORPCProcedures<T>;
-    /** Remove every registered procedure implementation. */
+    /** The cache the client reads and writes, to seed or inspect from a test. */
+    queryClient: QueryClient;
+    /** Remove every registered procedure implementation and clear the query cache. */
     reset: () => void;
 }
 /**
@@ -27,8 +30,11 @@ export interface TestORPCClient<T extends AnyNestedClient> {
  * The entrypoint has no Nuxt runtime dependency.
  * A shared setup file can therefore import it when Vitest hoists `mockNuxtImport()`.
  *
- * @param options - Cache key prefix and an optional test-owned QueryClient.
- * @returns A decorated client, its typed registration tree and a registration reset function.
+ * Without a `queryClient` the client owns one that never retries, so a failing procedure fails
+ * the test instead of retrying until it times out.
+ *
+ * @param options - Cache key prefix and a QueryClient to use instead of the owned one.
+ * @returns A decorated client, its typed registration tree, its cache and a reset function.
  */
 export declare function createTestORPCClient<T extends AnyNestedClient>(options?: ORPCNuxtClientOptions): TestORPCClient<T>;
 export {};

package/dist/runtime/testing.js

@@ -1,8 +1,15 @@
 import { createORPCClient } from "@orpc/client";
+import { QueryClient } from "@tanstack/vue-query";
 import { vi } from "vitest";
 import { createORPCNuxtClient } from "./client/create.js";
 export function createTestORPCClient(options = {}) {
   const registrations = /* @__PURE__ */ new Map();
+  const queryClient = options.queryClient ?? new QueryClient({
+    defaultOptions: {
+      // Retries turn a failing procedure into a test timeout instead of a reported failure.
+      queries: { retry: false }
+    }
+  });
   function registerHandler(path, handler) {
     const mock = vi.fn(handler);
     registrations.set(path, mock);
@@ -20,7 +27,7 @@ export function createTestORPCClient(options = {}) {
       return await callHandler(path.join("."), input);
     }
   };
-  const client = createORPCNuxtClient(createORPCClient(link), options);
+  const client = createORPCNuxtClient(createORPCClient(link), { ...options, queryClient });
   const procedures = createRecursiveProxy([], (path, args) => {
     if (path.at(-1) !== "handle") {
       throw new Error(`Unknown test procedure call: ${path.join(".")}`);
@@ -36,7 +43,11 @@ export function createTestORPCClient(options = {}) {
   return {
     client,
     procedures,
-    reset: () => registrations.clear()
+    queryClient,
+    reset: () => {
+      registrations.clear();
+      queryClient.clear();
+    }
   };
 }
 function createRecursiveProxy(path, call) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "orpc-nuxt",
-  "version": "0.3.0",
+  "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",