orpc-nuxt 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ilya Semenov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,447 @@
+# orpc-nuxt
+
+oRPC v2 integration for Nuxt 3 and 4, built on TanStack Vue Query.
+Add `useQuery` and `useMutation` to your oRPC procedures, with types inferred from your router.
+
+```ts
+const orpc = useOrpc()
+const { data } = await orpc.blog.posts.get.useQuery({ id: 1 })
+```
+
+Inspired by [trpc-nuxt](https://github.com/wobsoriano/trpc-nuxt).
+
+## Install
+
+```sh
+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.
+
+## Setup
+
+Register the module:
+
+```ts
+// nuxt.config.ts
+export default defineNuxtConfig({
+  modules: ["orpc-nuxt"],
+})
+```
+
+Add a plugin for browser and SSR requests:
+
+```ts
+// app/plugins/orpc.ts
+import type { RouterClient } from "@orpc/server"
+import { defineNuxtPlugin } from "orpc-nuxt/plugin"
+import type { router } from "~~/server/rpc/router"
+
+export default defineNuxtPlugin<RouterClient<typeof router>>(() => {
+  return {
+    url: "/rpc",
+    forwardHeaders: ["cookie"], // Forward the visitor's cookies during SSR.
+  }
+})
+```
+
+This assumes you have a router exported from `server/rpc/router.ts` and an RPC handler at `/rpc`; see the [oRPC Nuxt adapter](https://orpc.dev/docs/adapters/nuxt) to set them up.
+
+The helper sends both browser and SSR requests over HTTP.
+For direct router calls during SSR with your own `context`, use [manual client setup](#manual-client-setup).
+
+## Queries
+
+Call `useQuery` in `<script setup>` or a Vue component's `setup()` function.
+Use your router's procedure paths; the examples below use posts from a blog router.
+
+```ts
+const orpc = useOrpc()
+const query = await orpc.blog.posts.get.useQuery({ id: 1 })
+```
+
+`query` exposes reactive state and methods, including:
+
+- `query.data.value` contains the query result, or `undefined` before data is available.
+- `query.isPending.value` is `true` before the first success or error, even when disabled.
+- `query.error.value` contains the query error, or `null` when there is no error.
+- `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.
+The query follows the current input and uses its cached result when available.
+
+The second argument accepts both TanStack Vue Query options (such as `select`, `enabled`, and `staleTime`) and orpc-nuxt options (such as `clone` and `server`).
+
+```ts
+const route = useRoute()
+const panelOpen = ref(true)
+
+const query = orpc.blog.posts.get.useQuery(() => ({ id: Number(route.params.id) }), {
+  enabled: panelOpen,
+  staleTime: 30_000,
+})
+```
+
+Here, changing the route ID switches to that post's query, and closing the panel disables automatic fetching.
+
+Vue Query options such as `enabled` and `staleTime` can be reactive too.
+You can also pass the entire options object as a ref or getter.
+
+### Waiting for input
+
+Use TanStack Query's `skipToken` when you don't have valid input yet.
+This query starts once a post is selected:
+
+```ts
+import { skipToken } from "@tanstack/vue-query"
+
+const selectedId = ref<number>()
+const query = orpc.blog.posts.get.useQuery(() =>
+  selectedId.value === undefined ? skipToken : { id: selectedId.value },
+)
+```
+
+### Awaiting queries and server rendering
+
+You can use `useQuery` with or without `await`.
+Without it, you get the query refs immediately and can show a loading state.
+With it, you wait for the initial fetch.
+During SSR, the page waits for active queries either way.
+
+Set `server: false` in the query options to fetch only after the component mounts in the browser.
+The query refs are still available during SSR.
+
+`await` returns the current state immediately when no fetch is running.
+This includes disabled queries, `skipToken`, queries waiting for the component to mount, and requests paused because the browser is offline.
+It does not wait for these queries to become enabled or resume fetching.
+
+Failed queries expose the error in `query.error.value`.
+Set `throwOnError: true` if you also want `await` to throw and Vue to handle the error through its error hooks or boundaries.
+
+## Mutations
+
+Use `useMutation` for actions such as creating or updating a post.
+
+```ts
+const orpc = useOrpc()
+const mutation = orpc.blog.posts.create.useMutation({
+  onSuccess: () => orpc.blog.posts.invalidate(),
+})
+
+await mutation.mutateAsync({ title: "New post" })
+```
+
+`mutation` exposes reactive state and methods, including:
+
+- `mutation.mutate(input)` starts the request and returns `void`; read the result from `mutation.data.value` or handle it in `onSuccess`.
+- `mutation.mutateAsync(input)` starts the request and returns a `Promise` that resolves with the response or rejects with the error, so you can use `await` and `try/catch`.
+- `mutation.data.value` contains the mutation result, or `undefined` before data is available.
+- `mutation.isPending.value` is `true` while the mutation is running.
+- `mutation.error.value` contains the mutation error, or `null` when there is no error.
+
+The `onSuccess` callback above refreshes active post queries after creating a post.
+
+### Invalidation
+
+Choose how much of the cache to invalidate:
+
+```ts
+// Every cached input of this procedure.
+await orpc.blog.posts.get.invalidate()
+
+// Every query under this router branch.
+await orpc.blog.posts.invalidate()
+
+// Only this query's current input.
+await query.invalidate()
+```
+
+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
+
+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.
+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({
+  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
+
+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:
+
+- Edit a nested property to change only your local copy.
+- Assign a whole response to `data.value` to update the shared cache and reset the local copy.
+
+```ts
+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({
+    id,
+    title: data.value.title,
+  })
+}
+```
+
+After assigning a response, you can keep editing `data.value.title`; those edits still affect only the new local copy.
+
+A successful refetch or cache update replaces the local copy and discards its edits, even if the returned data has not changed.
+Changing the query input also switches the copy to that input's data.
+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
+
+If your API runs in a separate service, configure the base URLs in `nuxt.config.ts`, without the `/rpc` path:
+
+```ts
+// nuxt.config.ts
+export default defineNuxtConfig({
+  modules: ["orpc-nuxt"],
+  runtimeConfig: {
+    orpc: {
+      apiOrigin: "", // Optional SSR address; empty means use public.orpc.apiOrigin.
+    },
+    public: {
+      orpc: {
+        apiOrigin: "https://api.example.com",
+      },
+    },
+  },
+})
+```
+
+Set `NUXT_PUBLIC_ORPC_API_ORIGIN` to the browser-facing API origin.
+Use `NUXT_ORPC_API_ORIGIN` if SSR should use an internal address such as `http://api:3000`.
+
+Use these settings in `app/plugins/orpc.ts`:
+
+```ts
+// app/plugins/orpc.ts
+import type { router } from "@my-app/api"
+import type { RouterClient } from "@orpc/server"
+import { defineNuxtPlugin } from "orpc-nuxt/plugin"
+
+export default defineNuxtPlugin<RouterClient<typeof router>>(() => {
+  const config = useRuntimeConfig()
+  const serverOrigin = import.meta.server ? config.orpc.apiOrigin : ""
+
+  return {
+    url: `${config.public.orpc.apiOrigin}/rpc`,
+    serverUrl: serverOrigin ? `${serverOrigin}/rpc` : undefined,
+    credentials: "include",
+    forwardHeaders: ["cookie"],
+  }
+})
+```
+
+`serverUrl` overrides `url` during SSR; an empty or omitted value falls back to `url`.
+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.
+
+### Manual client setup
+
+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.
+
+The browser plugin sends requests to `/rpc` over HTTP:
+
+```ts
+// app/plugins/orpc.client.ts
+import { createORPCClient } from "@orpc/client"
+import { RPCLink } from "@orpc/client/fetch"
+import type { RouterClient } from "@orpc/server"
+import { createORPCNuxtClient } from "orpc-nuxt/client"
+import type { router } from "~~/server/rpc/router"
+
+export default defineNuxtPlugin(() => {
+  const client = createORPCClient<RouterClient<typeof router>>(new RPCLink({ url: "/rpc" }))
+  const orpc = createORPCNuxtClient(client)
+  return {
+    provide: { orpc },
+  }
+})
+```
+
+The server plugin calls the router directly, without an HTTP request.
+This example passes the current Nuxt request event as `context.event`; adjust it to match your router:
+
+```ts
+// app/plugins/orpc.server.ts
+import { createRouterClient } from "@orpc/server"
+import { createORPCNuxtClient } from "orpc-nuxt/client"
+import { router } from "~~/server/rpc/router"
+
+export default defineNuxtPlugin(() => {
+  const event = useRequestEvent()!
+  const client = createRouterClient(router, {
+    context: { event },
+  })
+  const orpc = createORPCNuxtClient(client)
+  return {
+    provide: { orpc },
+  }
+})
+```
+
+### SSR and cache configuration
+
+The module gives each server request its own QueryClient, which manages the query cache.
+It sends cached results to the browser in the Nuxt payload, so the browser can reuse data fetched during SSR.
+Queries stay fresh for 5 seconds by default to avoid immediately fetching that data again.
+
+Set static QueryClient defaults in `nuxt.config.ts`.
+This example keeps results fresh for 30 seconds and disables retries:
+
+```ts
+// nuxt.config.ts
+export default defineNuxtConfig({
+  modules: ["orpc-nuxt"],
+  orpc: {
+    queryClient: {
+      defaultOptions: {
+        queries: {
+          staleTime: 30_000,
+          retry: false,
+        },
+      },
+    },
+  },
+})
+```
+
+Query inputs can include oRPC types such as `bigint` and `Date`; the module supports them in cache keys.
+For custom classes in query results, register a Nuxt payload serializer or use TanStack dehydration options to exclude those queries from the payload.
+
+### Runtime configuration
+
+For callbacks, custom cache instances, or settings that depend on the current request, add an `orpc:query-client` hook in a Nuxt plugin.
+The module calls it with the configuration after applying static defaults and before creating the QueryClient.
+This example logs failed queries:
+
+```ts
+// app/plugins/query-config.ts
+import { QueryCache } from "@tanstack/vue-query"
+
+export default defineNuxtPlugin({
+  hooks: {
+    "orpc:query-client"(config) {
+      config.queryCache = new QueryCache({
+        onError(error) {
+          console.error("Query failed:", error)
+        },
+      })
+    },
+  },
+})
+```
+
+Nuxt registers the handlers declared in `hooks` before running plugins, so this handler is ready when the module creates the QueryClient.
+
+### 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:
+
+```ts
+// nuxt.config.ts
+export default defineNuxtConfig({
+  modules: ["orpc-nuxt"],
+  orpc: { queryClient: false },
+})
+```
+
+Your Vue Query plugin must install QueryClient before the oRPC plugin runs.
+Use `enforce: "pre"` and omit `parallel: true`.
+
+### Multiple clients
+
+If you have multiple oRPC clients with the same procedure paths, give each a different `prefix` so they don't share cached results:
+
+```ts
+const orpc = createORPCNuxtClient(client, { prefix: "blog" })
+```
+
+### Outside Vue components
+
+You can call `.useQuery()` and `.useMutation()` outside a component, for example in tests.
+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:
+
+```ts
+import { QueryClient } from "@tanstack/vue-query"
+import { createORPCNuxtClient } from "orpc-nuxt/client"
+import { effectScope } from "vue"
+
+const queryClient = new QueryClient()
+const orpc = createORPCNuxtClient(client, { queryClient })
+const scope = effectScope()
+
+try {
+  const { data } = await scope.run(() => {
+    return orpc.blog.posts.get.useQuery({ id: 1 })
+  })!
+
+  console.log(data.value)
+} finally {
+  scope.stop()
+  queryClient.clear()
+}
+```
+
+## Development
+
+Install dependencies with `bun install`, then run `bun run build`, `bun run types`, and `bun run test`.
+
+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`.

package/dist/module.d.mts

@@ -0,0 +1,14 @@
+import * as _nuxt_schema from '@nuxt/schema';
+import { StaticQueryClientConfig } from '../dist/runtime/nuxt/query-config.js';
+export { StaticQueryClientConfig } from '../dist/runtime/nuxt/query-config.js';
+export { ORPCRuntimeHooks as ModuleRuntimeHooks } from '../dist/runtime/nuxt/hooks.js';
+
+/** Configure the integration through the `orpc` section of nuxt.config. */
+interface ModuleOptions {
+    /** Set static query defaults, or use false when another plugin owns Vue Query and hydration. */
+    queryClient?: boolean | StaticQueryClientConfig;
+}
+declare const _default: _nuxt_schema.NuxtModule<ModuleOptions, ModuleOptions, false>;
+
+export { _default as default };
+export type { ModuleOptions };

package/dist/module.json

@@ -0,0 +1,12 @@
+{
+  "name": "orpc-nuxt",
+  "configKey": "orpc",
+  "compatibility": {
+    "nuxt": "^3.17.5 || ^4.0.0"
+  },
+  "version": "0.1.0",
+  "builder": {
+    "@nuxt/module-builder": "1.0.3",
+    "unbuild": "3.6.1"
+  }
+}

package/dist/module.mjs

@@ -0,0 +1,42 @@
+import { defineNuxtModule, createResolver, addImports, addPluginTemplate } from '@nuxt/kit';
+import { uneval } from 'devalue';
+
+const module$1 = defineNuxtModule({
+  meta: {
+    name: "orpc-nuxt",
+    configKey: "orpc",
+    compatibility: { nuxt: "^3.17.5 || ^4.0.0" }
+  },
+  defaults: { queryClient: true },
+  setup(options, nuxt) {
+    const resolver = createResolver(import.meta.url);
+    nuxt.options.build.transpile.push("orpc-nuxt");
+    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")
+    });
+    if (options.queryClient) {
+      const config = options.queryClient === true ? {} : options.queryClient;
+      addPluginTemplate({
+        filename: "orpc-nuxt/query-client.mjs",
+        // Emit static defaults into both bundles; uneval preserves values such as Infinity.
+        // Functions must use the runtime hook, where their closures are available.
+        // Keep enforce in the generated object so Nuxt can read its order without executing it.
+        getContents: () => [
+          `import { defineNuxtPlugin } from "nuxt/app"`,
+          `import createQueryClientSetup from ${JSON.stringify(resolver.resolve("./runtime/nuxt/plugin"))}`,
+          `export default defineNuxtPlugin({`,
+          `  name: "orpc-nuxt:query-client",`,
+          `  enforce: "pre",`,
+          `  setup: createQueryClientSetup(${uneval(config)}),`,
+          `})`
+        ].join("\n")
+      });
+    }
+  }
+});
+
+export { module$1 as default };

package/dist/runtime/client/create.d.ts

@@ -0,0 +1,12 @@
+import type { AnyNestedClient } from "@orpc/client";
+import type { ORPCNuxtClient, ORPCNuxtClientOptions } from "../types.js";
+/**
+ * Add reactive query and mutation composables while preserving oRPC's TanStack utilities.
+ * Accepts either an HTTP client or a server client bound to the current request context.
+ * Creating the wrapper does not start requests or require a Vue effect scope;
+ * calling its composables does require an active scope.
+ *
+ * @param client - The application-owned oRPC client whose router types are preserved.
+ * @param options - Cache key prefix and an optional QueryClient for standalone usage.
+ */
+export declare function createORPCNuxtClient<T extends AnyNestedClient>(client: T, options?: ORPCNuxtClientOptions): ORPCNuxtClient<T>;

package/dist/runtime/client/create.js

@@ -0,0 +1,31 @@
+import { createTanstackQueryUtils } from "@orpc/tanstack-query";
+import {
+  useQueryClient,
+  VUE_QUERY_CLIENT
+} from "@tanstack/vue-query";
+import { hasInjectionContext, inject } from "vue";
+import { useORPCMutation } from "../vue-query/mutation.js";
+import { useORPCQuery } from "../vue-query/query.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() {
+    return queryClient ??= useQueryClient();
+  }
+  function createMethods(target) {
+    return {
+      useQuery(input, queryOptions) {
+        return useORPCQuery(target, input, queryOptions, resolveQueryClient());
+      },
+      useMutation(mutationOptions) {
+        return useORPCMutation(target, mutationOptions, resolveQueryClient());
+      },
+      invalidate() {
+        const utils2 = target;
+        return resolveQueryClient().invalidateQueries({ queryKey: utils2.key() });
+      }
+    };
+  }
+  return decorateClient(utils, createMethods);
+}

package/dist/runtime/client/decorate.d.ts

@@ -0,0 +1,14 @@
+type Methods = Record<string, (...args: never[]) => unknown>;
+/**
+ * Lazily extend an oRPC utility tree with a factory's methods at each visited node.
+ * HTTP clients synthesize paths, so traversal cannot depend on enumerating a router.
+ * Property results are cached to keep node and method identities stable.
+ * When a method name also identifies a router path, calls invoke the method and
+ * property access continues through the corresponding child node.
+ *
+ * @param target - An upstream utility object or callable utility at the current path.
+ * @param createMethods - Called once per decorated node; must bind methods without invoking them.
+ * @returns A proxy preserving upstream utility calls and exposing the additional methods.
+ */
+export declare function decorateClient(target: object, createMethods: (target: object) => Methods): object;
+export {};

package/dist/runtime/client/decorate.js

@@ -0,0 +1,25 @@
+import { RECURSIVE_CLIENT_UNWRAP_KEYS } from "@orpc/client";
+export function decorateClient(target, createMethods) {
+  const methods = createMethods(target);
+  const children = /* @__PURE__ */ new Map();
+  return new Proxy(typeof target === "function" ? target : methods, {
+    get(_target, property, receiver) {
+      if (typeof property !== "string" || RECURSIVE_CLIENT_UNWRAP_KEYS.has(property)) {
+        return Reflect.get(target, property, receiver);
+      }
+      if (children.has(property)) return children.get(property);
+      const value = Reflect.get(target, property, receiver);
+      const method = Object.hasOwn(methods, property) ? methods[property] : void 0;
+      let result = method ?? value;
+      if (isObject(value)) {
+        const child = decorateClient(value, createMethods);
+        result = method ? new Proxy(method, { get: (_method, key) => Reflect.get(child, key) }) : child;
+      }
+      children.set(property, result);
+      return result;
+    }
+  });
+}
+function isObject(value) {
+  return typeof value === "object" && value !== null || typeof value === "function";
+}

package/dist/runtime/client.d.ts

@@ -0,0 +1,2 @@
+export { createORPCNuxtClient } from "./client/create.js";
+export type { AwaitableQuery, ORPCMutationOptions, ORPCNuxtClient, ORPCNuxtClientOptions, ORPCQueryOptions, ORPCQueryResult, ORPCSelectedQueryResult, } from "./types.js";

package/dist/runtime/client.js

@@ -0,0 +1 @@
+export { createORPCNuxtClient } from "./client/create.js";

package/dist/runtime/composables.d.ts

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

package/dist/runtime/composables.js

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

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

@@ -0,0 +1,11 @@
+import { type NuxtApp } from "nuxt/app";
+type InjectedORPCClient = NuxtApp extends {
+    $orpc: infer TClient;
+} ? TClient : never;
+/**
+ * Read the typed client provided by your application's oRPC plugin.
+ * Requires an active Nuxt context and a plugin that provides `orpc`.
+ * The router type is inferred from that plugin's return value.
+ */
+export declare function useOrpc(): InjectedORPCClient;
+export {};

package/dist/runtime/nuxt/composables.js

@@ -0,0 +1,8 @@
+import { useNuxtApp } from "nuxt/app";
+export function useOrpc() {
+  const client = useNuxtApp().$orpc;
+  if (!client) {
+    throw new Error("Provide an oRPC client from a Nuxt plugin before calling useOrpc().");
+  }
+  return client;
+}

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

@@ -0,0 +1,23 @@
+import { type AnyNestedClient } 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 {
+    /** 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. */
+    serverUrl?: string;
+    /** Fetch credentials policy, for example include for cross-origin browser cookies. */
+    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.
+ * The setup callback runs once per SSR request and once when the browser app starts.
+ * 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<{
+    orpc: ORPCNuxtClient<T>;
+}>;

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

@@ -0,0 +1,48 @@
+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";
+export function defineNuxtPlugin(setup) {
+  return createNuxtPlugin((nuxtApp) => {
+    const options = setup(nuxtApp);
+    const queryClient = options.queryClient ?? inject(VUE_QUERY_CLIENT, void 0);
+    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."
+      );
+    }
+    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 client = createORPCClient(link);
+    const orpc = createORPCNuxtClient(client, {
+      prefix: options.prefix,
+      queryClient
+    });
+    return {
+      provide: { orpc }
+    };
+  });
+}

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

@@ -0,0 +1,13 @@
+import type { QueryClientConfig } from "@tanstack/vue-query";
+/** Nuxt hooks available while the module initializes its QueryClient. */
+export interface ORPCRuntimeHooks {
+    /**
+     * Mutate the configuration before the per-app QueryClient is created and installed.
+     * Async handlers finish before initialization continues.
+     */
+    "orpc:query-client": (config: QueryClientConfig) => void | Promise<void>;
+}
+declare module "nuxt/app" {
+    interface RuntimeNuxtHooks extends ORPCRuntimeHooks {
+    }
+}

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

@@ -0,0 +1,4 @@
+import { type NuxtApp } from "nuxt/app";
+import { type StaticQueryClientConfig } from "./query-config.js";
+/** Install one Vue Query cache per Nuxt app and transfer server data through its payload. */
+export default function createQueryClientSetup(options?: StaticQueryClientConfig): (nuxtApp: NuxtApp) => Promise<void>;

package/dist/runtime/nuxt/plugin.js

@@ -0,0 +1,27 @@
+import {
+  dehydrate,
+  hydrate,
+  QueryClient,
+  VueQueryPlugin
+} from "@tanstack/vue-query";
+import { useState } from "nuxt/app";
+import { createQueryClientConfig } from "./query-config.js";
+export default function createQueryClientSetup(options = {}) {
+  return async function setup(nuxtApp) {
+    const state = useState("orpc-nuxt:query-cache");
+    const config = createQueryClientConfig(options);
+    await nuxtApp.callHook("orpc:query-client", config);
+    const queryClient = new QueryClient(config);
+    if (import.meta.server) {
+      nuxtApp.hook("app:rendered", () => {
+        state.value = dehydrate(queryClient);
+        queryClient.clear();
+      });
+      nuxtApp.hook("app:error", () => queryClient.clear());
+    } else {
+      if (state.value) hydrate(queryClient, state.value);
+      state.value = void 0;
+    }
+    nuxtApp.vueApp.use(VueQueryPlugin, { queryClient });
+  };
+}

package/dist/runtime/nuxt/query-config.d.ts

@@ -0,0 +1,10 @@
+import { type QueryClientConfig } from "@tanstack/vue-query";
+/** Remove callbacks from module options; their closures belong in the runtime hook. */
+type StaticValue<T> = T extends ((...args: never[]) => unknown) | symbol ? never : T extends readonly (infer Item)[] ? StaticValue<Item>[] : T extends object ? {
+    [K in keyof T]: StaticValue<T[K]>;
+} : T;
+/** QueryClient defaults that can be included in the Nuxt server and browser bundles. */
+export type StaticQueryClientConfig = StaticValue<Pick<QueryClientConfig, "defaultOptions">>;
+/** Merge module defaults without losing oRPC's support for typed values in query keys. */
+export declare function createQueryClientConfig(options?: StaticQueryClientConfig): QueryClientConfig;
+export {};

package/dist/runtime/nuxt/query-config.js

@@ -0,0 +1,19 @@
+import { RPCJsonSerializer } from "@orpc/client";
+import { hashKey } from "@tanstack/vue-query";
+export function createQueryClientConfig(options = {}) {
+  const serializer = new RPCJsonSerializer();
+  return {
+    defaultOptions: {
+      ...options.defaultOptions,
+      queries: {
+        // Reuse recently fetched SSR data instead of immediately requesting it in the browser.
+        staleTime: 5e3,
+        ...options.defaultOptions?.queries,
+        queryKeyHashFn(queryKey) {
+          const { json, meta } = serializer.serialize(queryKey);
+          return hashKey([json, meta?.map((entry) => JSON.stringify(entry)).sort()]);
+        }
+      }
+    }
+  };
+}

package/dist/runtime/plugin.d.ts

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

package/dist/runtime/plugin.js

@@ -0,0 +1 @@
+export { defineNuxtPlugin } from "./nuxt/define-plugin.js";

package/dist/runtime/types.d.ts

@@ -0,0 +1,89 @@
+import type { AnyNestedClient, Client, ClientContext } from "@orpc/client";
+import type { RouterUtils } from "@orpc/tanstack-query";
+import type { QueryClient, SkipToken, UseMutationOptions, UseMutationReturnType, UseQueryOptions, UseQueryReturnType } from "@tanstack/vue-query";
+import type { ComputedRef, DeepReadonly, MaybeRefOrGetter, Ref, WritableComputedRef } from "vue";
+/** Configure cache ownership and key namespacing when wrapping an application-owned client. */
+export interface ORPCNuxtClientOptions {
+    /** Separate the cache keys of clients whose procedure paths overlap. */
+    prefix?: string;
+    /** Use an explicit client when creating composables in an effect scope without Vue injection. */
+    queryClient?: QueryClient;
+}
+/**
+ * An oRPC client decorated with Vue composables and the official TanStack Query utilities.
+ * Router branches retain their names; finite procedures gain query and mutation composables.
+ * Procedures whose output includes an async iterable retain only the upstream utilities.
+ */
+export type ORPCNuxtClient<T extends AnyNestedClient> = RouterUtils<T> & {
+    /** Invalidate all inputs of this procedure, or every query under this router branch. */
+    invalidate: () => Promise<void>;
+} & (T extends Client<infer C, infer I, infer O, infer E> ? Extract<O, AsyncIterable<unknown>> extends never ? ProcedureHooks<C, I, O, E> : object : {
+    [K in keyof T]: T[K] extends AnyNestedClient ? ORPCNuxtClient<T[K]> : never;
+});
+/**
+ * Query state is available synchronously; awaiting it waits for the initial active fetch.
+ * Awaiting an inactive query returns its current state without waiting for it to become enabled.
+ */
+export type AwaitableQuery<T> = T & Promise<T>;
+/** Vue Query state with cache-writing data assignment and an optional mutable local clone. */
+export type ORPCQueryResult<TOutput, TError, TClone extends boolean = false> = Omit<UseQueryReturnType<TOutput, TError>, "data"> & {
+    /**
+     * Assign a whole response to update the shared cache for the current input.
+     * Nested edits require clone: true and remain local until a whole value is assigned.
+     * Successful cache updates replace that local clone and discard its edits.
+     */
+    data: WritableComputedRef<(TClone extends true ? TOutput : DeepReadonly<TOutput>) | undefined, TOutput>;
+    /** Invalidate this query's current input and refetch active observers. */
+    invalidate: () => Promise<void>;
+};
+/** Vue Query state projected through select while the cache retains the original response. */
+export type ORPCSelectedQueryResult<TSelected, TError> = Omit<UseQueryReturnType<TSelected, TError>, "data"> & {
+    /** The selected value and its nested properties are readonly. */
+    data: ComputedRef<DeepReadonly<TSelected> | undefined>;
+    /** Invalidate the underlying query for the current input and refetch active observers. */
+    invalidate: () => Promise<void>;
+};
+/** Extract the options object from Vue Query's ref/getter wrappers before replacing fields. */
+type ResolveOptions<T> = T extends Ref<infer U> ? U : T extends () => infer U ? ResolveOptions<U> : T;
+/** Keep context mandatory when the wrapped client requires fields the caller must supply. */
+type ContextOptions<C extends ClientContext> = object extends C ? {
+    context?: MaybeRefOrGetter<C>;
+} : {
+    context: MaybeRefOrGetter<C>;
+};
+/**
+ * Reactive Vue Query options with procedure-derived keys, query functions and oRPC client context.
+ * The useQuery overloads add mutually exclusive select and clone options.
+ */
+export type ORPCQueryOptions<C extends ClientContext, O, E, S = O> = Omit<ResolveOptions<UseQueryOptions<O, E, S>>, "queryKey" | "queryFn" | "select" | "shallow" | "enabled"> & ContextOptions<C> & {
+    /** Control automatic fetching reactively; disabled queries can still expose cached data. */
+    enabled?: MaybeRefOrGetter<boolean | undefined>;
+    /** Use false to start the query only after the component mounts in the browser. */
+    server?: boolean;
+};
+/** Vue Query mutation options with procedure-derived keys, mutation functions and client context. */
+export type ORPCMutationOptions<C extends ClientContext, I, O, E, M = unknown> = Omit<ResolveOptions<UseMutationOptions<O, E, I, M>>, "mutationKey" | "mutationFn" | "shallow"> & ContextOptions<C>;
+type QueryInput<I> = MaybeRefOrGetter<I | SkipToken>;
+/** Allow omitted input only when its type permits it, while preserving required client context. */
+type QueryArgs<C extends ClientContext, I, Options> = object extends C ? undefined extends I ? [input?: QueryInput<I>, options?: Options] : [input: QueryInput<I>, options?: Options] : [input: QueryInput<I>, options: Options];
+/** Carry each procedure's input, output, error and context types through the runtime decorator. */
+interface ProcedureHooks<C extends ClientContext, I, O, E> {
+    /** Observe a query with a mutable local clone; whole-value assignments update the shared cache. */
+    useQuery(input: QueryInput<I>, options: MaybeRefOrGetter<ORPCQueryOptions<C, O, E> & {
+        clone: true;
+        select?: never;
+    }>): AwaitableQuery<ORPCQueryResult<O, E, true>>;
+    /** Observe a readonly projection of cached data; select cannot be combined with clone: true. */
+    useQuery<S>(input: QueryInput<I>, options: MaybeRefOrGetter<ORPCQueryOptions<C, O, E, S> & {
+        select: (data: O) => S;
+        clone?: never;
+    }>): AwaitableQuery<ORPCSelectedQueryResult<S, E>>;
+    /** Observe a reactive query with readonly nested data and cache-writing whole-value assignment. */
+    useQuery(...args: QueryArgs<C, I, MaybeRefOrGetter<ORPCQueryOptions<C, O, E> & {
+        clone?: false;
+        select?: never;
+    }>>): AwaitableQuery<ORPCQueryResult<O, E>>;
+    /** Create a mutation observer; call mutate or mutateAsync to execute the procedure. */
+    useMutation<M = unknown>(...args: object extends C ? [options?: MaybeRefOrGetter<ORPCMutationOptions<C, I, O, E, M>>] : [options: MaybeRefOrGetter<ORPCMutationOptions<C, I, O, E, M>>]): UseMutationReturnType<O, E, I, M>;
+}
+export {};

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

@@ -0,0 +1,11 @@
+import { type QueryClient } from "@tanstack/vue-query";
+/**
+ * Create a Vue Query mutation observer for one oRPC procedure in the active effect scope.
+ * Reactive options and client context are resolved before building the official mutation options.
+ * Vue Query owns execution, callbacks and observer disposal.
+ *
+ * @param target - The procedure's upstream TanStack utilities, supplied by the client decorator.
+ * @param options - Mutation options, optionally wrapped in a ref or getter.
+ * @param queryClient - An explicit cache owner; otherwise Vue Query uses the injected client.
+ */
+export declare function useORPCMutation(target: object, options: unknown, queryClient?: QueryClient): import("@tanstack/vue-query").UseMutationReturnType<unknown, Error, unknown, unknown, Omit<import("@tanstack/query-core").MutationObserverIdleResult<unknown, Error, unknown, unknown>, "mutate" | "reset"> | Omit<import("@tanstack/query-core").MutationObserverLoadingResult<unknown, Error, unknown, unknown>, "mutate" | "reset"> | Omit<import("@tanstack/query-core").MutationObserverErrorResult<unknown, Error, unknown, unknown>, "mutate" | "reset"> | Omit<import("@tanstack/query-core").MutationObserverSuccessResult<unknown, Error, unknown, unknown>, "mutate" | "reset">>;

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

@@ -0,0 +1,18 @@
+import { useMutation } from "@tanstack/vue-query";
+import { computed, getCurrentScope, toValue } from "vue";
+export function useORPCMutation(target, options, queryClient) {
+  if (!getCurrentScope()) {
+    throw new Error("useMutation() requires a component setup or an active Vue effect scope.");
+  }
+  const procedure = target;
+  return useMutation(
+    computed(() => {
+      const { context, ...rest } = toValue(options) ?? {};
+      return procedure.mutationOptions({
+        ...rest,
+        context: toValue(context)
+      });
+    }),
+    queryClient
+  );
+}

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

@@ -0,0 +1,15 @@
+import { type QueryClient } from "@tanstack/vue-query";
+import type { AwaitableQuery, ORPCQueryResult } from "../types.js";
+/**
+ * Observe one oRPC procedure with reactive input, SSR prefetching and optional local cloning.
+ * Registers lifecycle hooks synchronously and returns query state that can also be awaited.
+ * Nested edits affect only the opt-in clone; whole-value assignments write through to the cache.
+ * Selected data cannot be assigned back because its shape may differ from the cached response.
+ *
+ * @param target - The procedure's upstream TanStack utilities, supplied by the client decorator.
+ * @param input - A value, ref or getter; skipToken suppresses automatic fetching.
+ * @param options - Query options, optionally wrapped in a ref or getter.
+ * @param client - An explicit cache owner; otherwise the injected QueryClient is used.
+ * @returns Live query refs plus a promise waiting for the initial active fetch.
+ */
+export declare function useORPCQuery(target: object, input: unknown, options: unknown, client?: QueryClient): AwaitableQuery<ORPCQueryResult<unknown, Error, true>>;

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

@@ -0,0 +1,90 @@
+import { skipToken, useQuery, useQueryClient } from "@tanstack/vue-query";
+import { cloneDeep } from "es-toolkit";
+import {
+  computed,
+  getCurrentInstance,
+  getCurrentScope,
+  onMounted,
+  onScopeDispose,
+  onServerPrefetch,
+  ref,
+  toRaw,
+  toValue,
+  watch
+} from "vue";
+export function useORPCQuery(target, input, options, client) {
+  if (!getCurrentScope()) {
+    throw new Error("useQuery() requires a component setup or an active Vue effect scope.");
+  }
+  const procedure = target;
+  const queryClient = client ?? useQueryClient();
+  const instance = getCurrentInstance();
+  const mounted = ref(typeof window !== "undefined" && !instance);
+  if (instance)
+    onMounted(() => {
+      mounted.value = true;
+    });
+  const settings = computed(
+    () => toValue(options) ?? {}
+  );
+  const queryOptions = computed(() => {
+    const { clone, server, context, enabled, ...rest } = settings.value;
+    if (clone && rest.select) {
+      throw new TypeError("clone: true cannot be combined with select.");
+    }
+    const snapshot = cloneDeep(toValue(input));
+    const isEnabled = toValue(enabled);
+    return {
+      ...procedure.queryOptions({
+        ...rest,
+        input: snapshot,
+        context: toValue(context)
+      }),
+      // Omit an unspecified enabled value so QueryClient defaults still apply.
+      ...snapshot === skipToken || server === false && !mounted.value ? { enabled: false } : isEnabled === void 0 ? {} : { enabled: isEnabled },
+      shallow: false
+    };
+  });
+  const query = useQuery(queryOptions, queryClient);
+  const queryHash = computed(() => queryClient.defaultQueryOptions(queryOptions.value).queryHash);
+  const localData = ref();
+  function resetClone() {
+    if (settings.value.clone) localData.value = cloneDeep(toRaw(query.data.value));
+  }
+  watch([query.data, queryHash, () => settings.value.clone], resetClone, {
+    immediate: true,
+    // A queued reset could overwrite local edits made immediately after a cache assignment.
+    flush: "sync"
+  });
+  const unsubscribe = queryClient.getQueryCache().subscribe((event) => {
+    if (event.type === "updated" && event.action.type === "success" && event.query.queryHash === queryHash.value) {
+      resetClone();
+    }
+  });
+  onScopeDispose(unsubscribe);
+  const data = computed({
+    get: () => settings.value.clone ? localData.value : query.data.value,
+    set(value) {
+      if (settings.value.select) throw new TypeError("Query data is readonly when select is used.");
+      queryClient.setQueryData(queryOptions.value.queryKey, value);
+      resetClone();
+    }
+  });
+  const result = {
+    ...query,
+    data,
+    invalidate: () => queryClient.invalidateQueries({
+      queryKey: queryOptions.value.queryKey,
+      exact: true
+    })
+  };
+  const loaded = query.fetchStatus.value === "fetching" ? query.suspense() : Promise.resolve();
+  if (instance) onServerPrefetch(() => loaded);
+  const awaitable = Object.assign(
+    loaded.then(() => result),
+    result
+  );
+  void awaitable.catch(() => {
+  });
+  return awaitable;
+}

package/dist/types.d.mts

@@ -0,0 +1,13 @@
+import type { ModuleRuntimeHooks } from './module.mjs'
+
+declare module '#app' {
+  interface RuntimeNuxtHooks extends ModuleRuntimeHooks {}
+}
+
+export { type StaticQueryClientConfig } from '../dist/runtime/nuxt/query-config.js'
+
+export { type ModuleRuntimeHooks } from '../dist/runtime/nuxt/hooks.js'
+
+export { default } from './module.mjs'
+
+export { type ModuleOptions } from './module.mjs'

package/package.json

@@ -0,0 +1,82 @@
+{
+  "name": "orpc-nuxt",
+  "version": "0.1.0",
+  "description": "oRPC integration for Nuxt.",
+  "homepage": "https://github.com/IlyaSemenov/orpc-nuxt#readme",
+  "bugs": "https://github.com/IlyaSemenov/orpc-nuxt/issues",
+  "license": "MIT",
+  "author": "Ilya Semenov",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/IlyaSemenov/orpc-nuxt.git"
+  },
+  "files": [
+    "README.md",
+    "dist"
+  ],
+  "type": "module",
+  "types": "./dist/types.d.mts",
+  "exports": {
+    ".": {
+      "types": "./dist/types.d.mts",
+      "import": "./dist/module.mjs"
+    },
+    "./client": {
+      "types": "./dist/runtime/client.d.ts",
+      "import": "./dist/runtime/client.js"
+    },
+    "./composables": {
+      "types": "./dist/runtime/composables.d.ts",
+      "import": "./dist/runtime/composables.js"
+    },
+    "./plugin": {
+      "types": "./dist/runtime/plugin.d.ts",
+      "import": "./dist/runtime/plugin.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "build": "nuxt-module-build build && publint",
+    "lint": "oxlint --fix && oxfmt",
+    "lint:check": "oxlint && oxfmt --check",
+    "prepare": "lefthook install",
+    "prepublishOnly": "bun run build",
+    "test": "bun test src tests/runtime",
+    "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",
+    "es-toolkit": "^1.52.0"
+  },
+  "devDependencies": {
+    "@changesets/cli": "^2.31.1",
+    "@nuxt/cli": "^3.37.0",
+    "@nuxt/module-builder": "^1.0.3",
+    "@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",
+    "nuxt": "^4.5.2",
+    "oxfmt": "^0.67.0",
+    "oxlint": "^1.82.0",
+    "publint": "^0.3.22",
+    "typescript": "^5.9.3",
+    "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",
+    "@tanstack/vue-query": "^5.102.8",
+    "nuxt": "^3.17.5 || ^4.0.0",
+    "vue": "^3.5.0"
+  },
+  "packageManager": "bun@1.3.14"
+}