orpc-nuxt 0.1.0 → 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.
@@ -165,7 +163,29 @@ Invalidation marks matching queries as stale and refetches active ones.
 Inactive queries can refresh when used again.
 Create the decorated client inside your app plugin so callbacks use that app's QueryClient.
 
-## Updating cached data
+## Direct calls and oRPC utilities
+
+Use `.call()` when you just need a procedure's response, without query state or caching:
+
+```ts
+const post = await orpc.blog.posts.get.call({ id: 1 })
+```
+
+The client also exposes oRPC's utilities:
+
+- `.key()` builds a cache key prefix for a procedure or router branch.
+- `.queryKey()` builds a query key for a specific input.
+- `.queryOptions()` builds options for Vue Query's `useQuery`.
+- `.mutationOptions()` builds options for Vue Query's `useMutation`.
+- `.infiniteOptions()` builds options for Vue Query's `useInfiniteQuery` for pagination.
+
+Subscription composables are not available yet.
+Procedures that return streams keep the oRPC utilities but do not get this package's `useQuery` or `useMutation` methods.
+The module does not automatically transfer streamed query results from server to browser.
+
+## Query data
+
+### Updating cached data
 
 Assigning a new response to `data.value` updates the shared cache for the query's current input.
 Other components reading the same query see the update too.
@@ -173,19 +193,19 @@ Nested properties are readonly unless you enable `clone: true`.
 
 ```ts
 const { data } = await orpc.blog.posts.get.useQuery({ id: 1 })
-const savePost = orpc.blog.posts.update.useMutation()
 
-const response = await savePost.mutateAsync({
+const response = await orpc.blog.posts.update.call({
   id: 1,
   title: "Updated title",
 })
+
 data.value = response
 ```
 
 Treat the original `response` as readonly after assigning it to `data.value`.
 The assignment passes it to the cache without a defensive copy, so changing `response.title` could modify cached data directly.
 
-## Editing drafts
+### Mutable data
 
 With `clone: true`, `data.value` contains a reactive local copy that you can edit, for example in a form.
 There are two ways to change it:
@@ -197,14 +217,12 @@ There are two ways to change it:
 const id = 1
 const { data } = await orpc.blog.posts.get.useQuery({ id }, { clone: true })
 
-const savePost = orpc.blog.posts.update.useMutation()
-
 if (data.value) {
   // Only this query's local copy changes.
   data.value.title = "Local draft"
 
   // Save the draft, then share the server's response with other components.
-  data.value = await savePost.mutateAsync({
+  data.value = await orpc.blog.posts.update.call({
     id,
     title: data.value.title,
   })
@@ -219,21 +237,6 @@ Keep a separate form draft if it must survive these updates.
 
 You cannot combine `clone: true` with `select`; selected results are readonly.
 
-## Direct calls and oRPC utilities
-
-Use `.call()` when you just need a procedure's response, without query state or caching:
-
-```ts
-const post = await orpc.blog.posts.get.call({ id: 1 })
-```
-
-The client also exposes oRPC's `.key()`, `.queryKey()`, `.queryOptions()`, `.mutationOptions()`, and `.infiniteOptions()` utilities.
-You can pass their options to Vue Query composables, for example `.infiniteOptions()` to `useInfiniteQuery` for pagination.
-
-Subscription composables are not available yet.
-Procedures that return streams keep the oRPC utilities but do not get this package's `useQuery` or `useMutation` methods.
-The module does not automatically transfer streamed query results from server to browser.
-
 ## Advanced
 
 ### Separate API service
@@ -291,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
@@ -331,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.
@@ -385,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:
@@ -408,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:
 
@@ -439,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 Nuxt 3.17.5 and Nuxt 4.5.2.
-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.17.5`.
+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

@@ -2,9 +2,9 @@
   "name": "orpc-nuxt",
   "configKey": "orpc",
   "compatibility": {
-    "nuxt": "^3.17.5 || ^4.0.0"
+    "nuxt": "^3.14.1592 || ^4.0.1"
   },
-  "version": "0.1.0",
+  "version": "0.2.0",
   "builder": {
     "@nuxt/module-builder": "1.0.3",
     "unbuild": "3.6.1"

package/dist/module.mjs

@@ -5,7 +5,7 @@ const module$1 = defineNuxtModule({
   meta: {
     name: "orpc-nuxt",
     configKey: "orpc",
-    compatibility: { nuxt: "^3.17.5 || ^4.0.0" }
+    compatibility: { nuxt: "^3.14.1592 || ^4.0.1" }
   },
   defaults: { queryClient: true },
   setup(options, nuxt) {
@@ -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,7 +1,7 @@
 {
   "name": "orpc-nuxt",
-  "version": "0.1.0",
-  "description": "oRPC integration for Nuxt.",
+  "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",
   "license": "MIT",
@@ -46,36 +46,41 @@
     "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"
   },
   "dependencies": {
-    "@nuxt/kit": "^4.5.2",
-    "devalue": "^5.9.2",
+    "@nuxt/kit": "^3.14.1592 || ^4.0.1",
+    "devalue": "^5.0.0",
     "es-toolkit": "^1.52.0"
   },
   "devDependencies": {
     "@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.17.5 || ^4.0.0",
+    "nuxt": "^3.14.1592 || ^4.0.1",
     "vue": "^3.5.0"
   },
   "packageManager": "bun@1.3.14"