orpc-nuxt 0.1.1 → 0.2.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,71 @@ If you have multiple oRPC clients with the same procedure paths, give each a dif
 const orpc = createORPCNuxtClient(client, { prefix: "blog" })
 ```
 
+### Component tests
+
+Component tests need the Nuxt environment of `@nuxt/test-utils`:
+
+```ts
+// vitest.config.ts
+import { defineVitestConfig } from "@nuxt/test-utils/config"
+
+export default defineVitestConfig({})
+```
+
+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.
+Replace `useOrpc()` with a client that returns fixed data, then mount the component with `mountSuspended()` so its awaited queries resolve before the assertions.
+The replacement can be any nested object of async functions; only the procedures the component calls have to exist.
+
+```ts
+// test/nuxt/post-list.spec.ts
+import { mockNuxtImport, mountSuspended } from "@nuxt/test-utils/runtime"
+import { QueryClient } from "@tanstack/vue-query"
+import { createORPCNuxtClient } from "orpc-nuxt/client"
+import { afterEach, expect, test } from "vitest"
+
+import PostList from "~/components/post-list.vue"
+
+const queryClient = new QueryClient({
+  // Report a failing procedure instead of retrying it until the test times out.
+  defaultOptions: { queries: { retry: false } },
+})
+
+const orpc = createORPCNuxtClient(
+  {
+    blog: {
+      posts: {
+        list: async () => [{ id: 1, title: "First post" }],
+      },
+    },
+  },
+  { queryClient },
+)
+
+// Vitest runs this factory before the file body, so it must return the composable without calling it.
+mockNuxtImport("useOrpc", () => () => orpc)
+
+afterEach(() => {
+  // Start every test from an empty cache, so an earlier response cannot satisfy a later query.
+  queryClient.clear()
+})
+
+test("renders the posts", async () => {
+  const component = await mountSuspended(PostList)
+  expect(component.text()).toContain("First post")
+})
+```
+
+Passing an explicit `queryClient` gives the tests their own cache:
+
+- The application's cache never carries data from one test into the next.
+- Test defaults such as `retry: false` stay in the test file instead of the module options.
+
+Omit it to test against the cache the module installs.
+Read that one with `useOrpcQueryClient()`, and set its defaults through the `orpc.queryClient` module options.
+
 ### 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 +523,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.2.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/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.2.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",
@@ -46,6 +46,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,22 +59,26 @@
     "@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",
     "vue": "^3.5.0"