orpc-nuxt 0.1.1 → 0.3.0

package/README.md

@@ -16,7 +16,7 @@ Inspired by [trpc-nuxt](https://github.com/wobsoriano/trpc-nuxt).
 npm install orpc-nuxt @orpc/client@2.0.0-beta.35 @orpc/server@2.0.0-beta.35 @orpc/tanstack-query@2.0.0-beta.35 @tanstack/vue-query
 ```
 
-Use the oRPC v2 beta versions shown above.
+Install oRPC by version: v2 is still in beta, and this package needs `2.0.0-beta.35` or newer.
 
 ## Setup
 
@@ -68,8 +68,6 @@ const query = await orpc.blog.posts.get.useQuery({ id: 1 })
 - `query.refetch()` fetches the current query again.
 - `query.invalidate()` marks its cached result as stale and refetches it if it is active.
 
-You can also access the client as `useNuxtApp().$orpc`; both accessors infer types from your plugin.
-
 ### Reactive input and options
 
 Pass a ref, reactive object, or getter when the input can change.
@@ -296,6 +294,9 @@ Only headers listed in `forwardHeaders` are forwarded from the incoming SSR requ
 Use `createORPCNuxtClient` when you need a custom transport or want SSR to call the router directly.
 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.
+Both plugins provide the client under the `orpc` key: `useOrpc()` reads it as `useNuxtApp().$orpc` and infers the router type from that injection.
+
 The browser plugin sends requests to `/rpc` over HTTP:
 
 ```ts
@@ -336,6 +337,9 @@ export default defineNuxtPlugin(() => {
 })
 ```
 
+Let both plugins infer the client type instead of annotating it.
+Nuxt combines what they provide, so a widened type in either one leaves `useOrpc()` without procedure types.
+
 ### SSR and cache configuration
 
 The module gives each server request its own QueryClient, which manages the query cache.
@@ -390,6 +394,19 @@ export default defineNuxtPlugin({
 
 Nuxt registers the handlers declared in `hooks` before running plugins, so this handler is ready when the module creates the QueryClient.
 
+### Query client
+
+`useOrpcQueryClient()` returns the QueryClient installed for the app, whether by the module or by your own plugin.
+Unlike Vue Query's `useQueryClient()`, it also works where Vue injection is unavailable, such as in an event handler or between tests:
+
+```ts
+const queryClient = useOrpcQueryClient()
+queryClient.clear()
+```
+
+It needs the Nuxt context, which the browser keeps available once the app has started.
+During server rendering, call it inside `nuxtApp.runWithContext()`.
+
 ### Existing Vue Query setup
 
 If your app already installs Vue Query and transfers its cache between server and browser, disable the module's QueryClient setup:
@@ -413,9 +430,82 @@ If you have multiple oRPC clients with the same procedure paths, give each a dif
 const orpc = createORPCNuxtClient(client, { prefix: "blog" })
 ```
 
+### Component tests
+
+Configure the Nuxt test environment and load a shared setup file:
+
+```ts
+// vitest.config.ts
+import { defineVitestConfig } from "@nuxt/test-utils/config"
+
+export default defineVitestConfig({
+  test: {
+    setupFiles: ["test/nuxt/setup.ts"],
+  },
+})
+```
+
+That configuration runs every test under `test/nuxt/` or `tests/nuxt/`, and every test named `*.nuxt.test.ts` or `*.nuxt.spec.ts`, against your application.
+Use `createTestORPCClient()` from `orpc-nuxt/testing` to replace `useOrpc()` with an isolated fake client.
+`client` includes the regular composables and oRPC utilities.
+Each procedure leaf in `procedures` has a `.handle()` method that registers a typed handler and returns a Vitest mock.
+
+```ts
+// 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,
+})
+
+// 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.
+})
+```
+
+`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.
+
+Register the required handlers before mounting; `mountSuspended()` waits for awaited queries before assertions:
+
+```ts
+// test/nuxt/post-list.spec.ts
+import { mountSuspended } from "@nuxt/test-utils/runtime"
+import { expect, test } from "vitest"
+
+import PostList from "~/components/post-list.vue"
+
+import { procedures } from "./setup"
+
+test("renders the posts", async () => {
+  const list = procedures.blog.posts.list.handle(() => [{ id: 1, title: "First post" }])
+  const component = await mountSuspended(PostList)
+
+  expect(component.text()).toContain("First post")
+  expect(list).toHaveBeenCalledOnce()
+})
+```
+
 ### Outside Vue components
 
-You can call `.useQuery()` and `.useMutation()` outside a component, for example in tests.
+You can call `.useQuery()` and `.useMutation()` outside a component, for example in a script or in a test that never mounts one.
 Create them inside `scope.run()` so Vue can track their reactive subscriptions, then call `scope.stop()` when you are done.
 When Vue injection is unavailable, pass a QueryClient explicitly:
 
@@ -444,9 +534,12 @@ try {
 
 Install dependencies with `bun install`, then run `bun run build`, `bun run types`, and `bun run test`.
 
+Run `bun run test:component` to check the documented component-test recipe in the fixture application; it uses the built package, so build first.
+
 To try the package in a Nuxt app, build it and run `bunx nuxt dev tests/fixtures/nuxt`.
 The example app uses the built package, so rebuild after changing its source.
 
-Run `bunx playwright install chromium`, then `bun run test:nuxt` to check the packed npm archive with the oldest and newest supported Nuxt 3 and Nuxt 4 releases.
-Each version is checked with both module-managed and app-managed QueryClients, including types, SSR, and hydration in development and production.
-To check one version, use `bun run test:nuxt 3.14.1592`.
+Run `bunx playwright install chromium-headless-shell`, then `bun run test:nuxt` to check the packed npm archive with the Nuxt version installed in the workspace.
+It is checked with both module-managed and app-managed QueryClients, including types, SSR, and hydration in development and production.
+
+To check other Nuxt versions by hand, pass them explicitly: `bun run test:nuxt 3.14.1592 4.0.1`.

package/dist/module.json

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

package/dist/module.mjs

@@ -14,10 +14,11 @@ const module$1 = defineNuxtModule({
     const optimizeDeps = nuxt.options.vite.optimizeDeps ??= {};
     optimizeDeps.exclude ??= [];
     optimizeDeps.exclude.push("orpc-nuxt/client", "@tanstack/vue-query");
-    addImports({
-      name: "useOrpc",
-      from: resolver.resolve("./runtime/composables")
-    });
+    const composables = resolver.resolve("./runtime/composables");
+    addImports([
+      { name: "useOrpc", from: composables },
+      { name: "useOrpcQueryClient", from: composables }
+    ]);
     if (options.queryClient) {
       const config = options.queryClient === true ? {} : options.queryClient;
       addPluginTemplate({

package/dist/runtime/client/create.js

@@ -1,29 +1,26 @@
 import { createTanstackQueryUtils } from "@orpc/tanstack-query";
-import {
-  useQueryClient,
-  VUE_QUERY_CLIENT
-} from "@tanstack/vue-query";
-import { hasInjectionContext, inject } from "vue";
+import { useQueryClient } from "@tanstack/vue-query";
 import { useORPCMutation } from "../vue-query/mutation.js";
 import { useORPCQuery } from "../vue-query/query.js";
+import { resolveQueryClient } from "../vue-query/query-client.js";
 import { decorateClient } from "./decorate.js";
 export function createORPCNuxtClient(client, options = {}) {
   const utils = createTanstackQueryUtils(client, { prefix: options.prefix });
-  let queryClient = options.queryClient ?? (hasInjectionContext() ? inject(VUE_QUERY_CLIENT, void 0) : void 0);
-  function resolveQueryClient() {
+  let queryClient = options.queryClient ?? resolveQueryClient();
+  function getQueryClient() {
     return queryClient ??= useQueryClient();
   }
   function createMethods(target) {
     return {
       useQuery(input, queryOptions) {
-        return useORPCQuery(target, input, queryOptions, resolveQueryClient());
+        return useORPCQuery(target, input, queryOptions, getQueryClient());
       },
       useMutation(mutationOptions) {
-        return useORPCMutation(target, mutationOptions, resolveQueryClient());
+        return useORPCMutation(target, mutationOptions, getQueryClient());
       },
       invalidate() {
         const utils2 = target;
-        return resolveQueryClient().invalidateQueries({ queryKey: utils2.key() });
+        return getQueryClient().invalidateQueries({ queryKey: utils2.key() });
       }
     };
   }

package/dist/runtime/composables.d.ts

@@ -1 +1 @@
-export { useOrpc } from "./nuxt/composables.js";
+export { useOrpc, useOrpcQueryClient } from "./nuxt/composables.js";

package/dist/runtime/composables.js

@@ -1 +1 @@
-export { useOrpc } from "./nuxt/composables.js";
+export { useOrpc, useOrpcQueryClient } from "./nuxt/composables.js";

package/dist/runtime/nuxt/composables.d.ts

@@ -1,3 +1,4 @@
+import type { QueryClient } from "@tanstack/vue-query";
 import { type NuxtApp } from "nuxt/app";
 type InjectedORPCClient = NuxtApp extends {
     $orpc: infer TClient;
@@ -8,4 +9,13 @@ type InjectedORPCClient = NuxtApp extends {
  * The router type is inferred from that plugin's return value.
  */
 export declare function useOrpc(): InjectedORPCClient;
+/**
+ * Read the QueryClient installed for this Nuxt app, by the module or by your own plugin.
+ * Unlike Vue Query's own accessor, this ignores component-level providers and works outside
+ * a component, for example in an event handler or when clearing the cache between tests.
+ * The browser keeps the Nuxt context available after startup; during server rendering,
+ * call this inside nuxtApp.runWithContext().
+ * Throws when no QueryClient is installed, as with queryClient: false and no Vue Query plugin.
+ */
+export declare function useOrpcQueryClient(): QueryClient;
 export {};

package/dist/runtime/nuxt/composables.js

@@ -1,4 +1,5 @@
 import { useNuxtApp } from "nuxt/app";
+import { resolveQueryClient } from "../vue-query/query-client.js";
 export function useOrpc() {
   const client = useNuxtApp().$orpc;
   if (!client) {
@@ -6,3 +7,12 @@ export function useOrpc() {
   }
   return client;
 }
+export function useOrpcQueryClient() {
+  const queryClient = resolveQueryClient(useNuxtApp().vueApp);
+  if (!queryClient) {
+    throw new Error(
+      "Install Vue Query before calling useOrpcQueryClient(). Enable the module's queryClient option, or install Vue Query from a Nuxt plugin."
+    );
+  }
+  return queryClient;
+}

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

@@ -1,17 +1,16 @@
 import { createORPCClient } from "@orpc/client";
 import { RPCLink } from "@orpc/client/fetch";
-import { VUE_QUERY_CLIENT } from "@tanstack/vue-query";
 import {
   defineNuxtPlugin as createNuxtPlugin,
   useRequestHeaders,
   useRequestURL
 } from "nuxt/app";
-import { inject } from "vue";
 import { createORPCNuxtClient } from "../client/create.js";
+import { resolveQueryClient } from "../vue-query/query-client.js";
 export function defineNuxtPlugin(setup) {
   return createNuxtPlugin((nuxtApp) => {
     const options = setup(nuxtApp);
-    const queryClient = options.queryClient ?? inject(VUE_QUERY_CLIENT, void 0);
+    const queryClient = options.queryClient ?? resolveQueryClient(nuxtApp.vueApp);
     if (!queryClient) {
       throw new Error(
         "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."

package/dist/runtime/testing.d.ts

@@ -0,0 +1,34 @@
+import type { AnyNestedClient, Client } from "@orpc/client";
+import type { Mock } from "vitest";
+import type { ORPCNuxtClient, ORPCNuxtClientOptions } from "./types.js";
+type MaybePromise<T> = T | Promise<T>;
+/** A procedure implementation registered for a test client. */
+export type TestORPCHandler<TProcedure> = TProcedure extends Client<infer _Context, infer Input, infer Output, infer _Error> ? (input: Input) => MaybePromise<Awaited<Output>> : never;
+/** Registration methods for one procedure in a test client. */
+export interface TestORPCProcedure<TProcedure> {
+    /** Register the implementation used by subsequent calls and return its Vitest mock. */
+    handle(handler: TestORPCHandler<TProcedure>): Mock<TestORPCHandler<TProcedure>>;
+}
+/** A router-shaped tree whose procedure leaves register test implementations. */
+export type TestORPCProcedures<T extends AnyNestedClient> = T extends Client<infer Context, infer Input, infer Output, infer Error> ? TestORPCProcedure<Client<Context, Input, Output, Error>> : {
+    [Key in keyof T]: T[Key] extends AnyNestedClient ? TestORPCProcedures<T[Key]> : never;
+};
+/** The isolated client, procedure registry and cleanup function created for a test suite. */
+export interface TestORPCClient<T extends AnyNestedClient> {
+    /** The decorated client to return from a mocked `useOrpc()`. */
+    client: ORPCNuxtClient<T>;
+    /** Register typed implementations and receive Vitest mocks for call assertions. */
+    procedures: TestORPCProcedures<T>;
+    /** Remove every registered procedure implementation. */
+    reset: () => void;
+}
+/**
+ * Create an isolated fake oRPC client for Nuxt component tests.
+ * 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.
+ */
+export declare function createTestORPCClient<T extends AnyNestedClient>(options?: ORPCNuxtClientOptions): TestORPCClient<T>;
+export {};

package/dist/runtime/testing.js

@@ -0,0 +1,60 @@
+import { createORPCClient } from "@orpc/client";
+import { vi } from "vitest";
+import { createORPCNuxtClient } from "./client/create.js";
+export function createTestORPCClient(options = {}) {
+  const registrations = /* @__PURE__ */ new Map();
+  function registerHandler(path, handler) {
+    const mock = vi.fn(handler);
+    registrations.set(path, mock);
+    return mock;
+  }
+  async function callHandler(path, input) {
+    const handler = registrations.get(path);
+    if (!handler) {
+      throw new Error(`No test handler is registered for oRPC procedure "${path}"`);
+    }
+    return await handler(input);
+  }
+  const link = {
+    async call(path, input) {
+      return await callHandler(path.join("."), input);
+    }
+  };
+  const client = createORPCNuxtClient(createORPCClient(link), options);
+  const procedures = createRecursiveProxy([], (path, args) => {
+    if (path.at(-1) !== "handle") {
+      throw new Error(`Unknown test procedure call: ${path.join(".")}`);
+    }
+    const handler = args[0];
+    if (typeof handler !== "function") {
+      throw new TypeError(
+        `A test handler must be a function for oRPC procedure "${path.slice(0, -1).join(".")}"`
+      );
+    }
+    return registerHandler(path.slice(0, -1).join("."), handler);
+  });
+  return {
+    client,
+    procedures,
+    reset: () => registrations.clear()
+  };
+}
+function createRecursiveProxy(path, call) {
+  const target = () => {
+  };
+  const children = /* @__PURE__ */ new Map();
+  return new Proxy(target, {
+    get(_, property, receiver) {
+      if (typeof property !== "string" || property === "then") {
+        return Reflect.get(target, property, receiver);
+      }
+      if (children.has(property)) return children.get(property);
+      const child = createRecursiveProxy([...path, property], call);
+      children.set(property, child);
+      return child;
+    },
+    apply(_, __, args) {
+      return call(path, args);
+    }
+  });
+}

package/dist/runtime/vue-query/query-client.d.ts

@@ -0,0 +1,12 @@
+import { type QueryClient } from "@tanstack/vue-query";
+import { type App } from "vue";
+/**
+ * Find the QueryClient installed by Vue Query, with or without an active injection context.
+ * An application is read directly, so a component providing its own cache cannot shadow the one
+ * a plugin captured for the whole application.
+ * Without an application, the active injection context is the only source.
+ *
+ * @param app - The application to read, whatever context the call happens in.
+ * @returns The installed QueryClient, or undefined when Vue Query is unavailable.
+ */
+export declare function resolveQueryClient(app?: App): QueryClient | undefined;

package/dist/runtime/vue-query/query-client.js

@@ -0,0 +1,9 @@
+import { VUE_QUERY_CLIENT } from "@tanstack/vue-query";
+import { hasInjectionContext, inject } from "vue";
+export function resolveQueryClient(app) {
+  if (app) return app.runWithContext(injectQueryClient);
+  return hasInjectionContext() ? injectQueryClient() : void 0;
+}
+function injectQueryClient() {
+  return inject(VUE_QUERY_CLIENT, void 0);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "orpc-nuxt",
-  "version": "0.1.1",
+  "version": "0.3.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",
@@ -33,6 +33,10 @@
       "types": "./dist/runtime/plugin.d.ts",
       "import": "./dist/runtime/plugin.js"
     },
+    "./testing": {
+      "types": "./dist/runtime/testing.d.ts",
+      "import": "./dist/runtime/testing.js"
+    },
     "./package.json": "./package.json"
   },
   "publishConfig": {
@@ -46,6 +50,7 @@
     "prepare": "lefthook install",
     "prepublishOnly": "bun run build",
     "test": "bun test src tests/runtime",
+    "test:component": "vitest run --root tests/fixtures/nuxt",
     "test:nuxt": "bun tests/nuxt/run.ts",
     "types": "tsc --noEmit && tsc --noEmit -p tests/tsconfig.json && nuxt typecheck tests/fixtures/nuxt"
   },
@@ -58,25 +63,35 @@
     "@changesets/cli": "^2.31.1",
     "@nuxt/cli": "^3.37.0",
     "@nuxt/module-builder": "^1.0.3",
+    "@nuxt/test-utils": "^4.3.2",
     "@orpc/server": "2.0.0-beta.35",
     "@playwright/test": "1.58.2",
     "@tsconfig/bun": "^1.0.10",
     "@types/bun": "^1.3.14",
     "@vue/server-renderer": "^3.5.0",
+    "@vue/test-utils": "^2.5.0",
+    "happy-dom": "^20.14.3",
     "nuxt": "^4.5.2",
     "oxfmt": "^0.67.0",
     "oxlint": "^1.82.0",
     "publint": "^0.3.22",
     "typescript": "^5.9.3",
+    "vitest": "^5.0.0",
     "vue-tsc": "^3.3.11",
     "zod": "^4.3.6"
   },
   "peerDependencies": {
-    "@orpc/client": "2.0.0-beta.35",
-    "@orpc/tanstack-query": "2.0.0-beta.35",
+    "@orpc/client": "^2.0.0-beta.35",
+    "@orpc/tanstack-query": "^2.0.0-beta.35",
     "@tanstack/vue-query": "^5.102.8",
     "nuxt": "^3.14.1592 || ^4.0.1",
+    "vitest": "^4.0.0 || ^5.0.0",
     "vue": "^3.5.0"
   },
+  "peerDependenciesMeta": {
+    "vitest": {
+      "optional": true
+    }
+  },
   "packageManager": "bun@1.3.14"
 }