@arpabet/vrpc-nuxt 0.2.0

package/README.md

@@ -0,0 +1,42 @@
+# @arpabet/vrpc-nuxt
+
+Nuxt 3/4 module for [value-rpc](https://github.com/arpabet/value-rpc).
+
+```ts
+// nuxt.config.ts
+export default defineNuxtConfig({
+  modules: ["@arpabet/vrpc-nuxt"],
+  vrpc: {
+    url: "/rpc",        // same-origin wss in production
+    timeoutMs: 5000,
+  },
+});
+```
+
+- Registers a **client-only** plugin: SSR renders the pending state; the
+  browser connects after hydration (no WebSocket per SSR render).
+- Auto-imports `useVrpc`, `useVrpcCall`, `useVrpcStream`, `useVrpcConnection`.
+- Runtime-config driven: override per deployment with `NUXT_PUBLIC_VRPC_URL`
+  (and `NUXT_PUBLIC_VRPC_TIMEOUT_MS`, …).
+- A relative `url` like `/rpc` is resolved against the page origin with the
+  matching `ws:`/`wss:` scheme.
+
+### Dev connectivity
+
+In production, serve the app and a same-origin `/rpc` endpoint from one host so
+`url: "/rpc"` connects same-origin (no CORS, no origin patterns). In **dev**,
+the browser and the Go server are on different ports, so either:
+
+- **connect directly** to the server with an absolute dev URL and allow the
+  origin server-side (`valueserver.WithWebSocketOrigins(...)`) — the reliable
+  option, since Nitro's `devProxy` forwards HTTP but does **not** upgrade
+  WebSockets; or
+- use Vite/`@arpabet/vrpc-vue` (whose dev proxy does handle WS) for a same-origin
+  dev experience.
+
+The `devProxy` option still wires a Nitro `devProxy` entry (useful for any HTTP
+routes), but do not rely on it for the WebSocket itself.
+
+For SSR-critical data, query the same Go server from Nitro server routes and
+pass results through `useAsyncData`; a shared Nitro-side vrpc client is the
+phase-2 plan (WEB.md §6.6).

package/dist/module.d.ts

@@ -0,0 +1,36 @@
+import * as _nuxt_schema from '@nuxt/schema';
+
+interface VrpcModuleOptions {
+    /**
+     * WebSocket endpoint. Overridable at runtime via
+     * NUXT_PUBLIC_VRPC_URL (runtimeConfig.public.vrpc.url). In dev, prefer a
+     * relative "/rpc" together with the devProxy option.
+     */
+    url: string;
+    /** "msgpack" (default, works with every server) or "json". */
+    codec?: "msgpack" | "json";
+    /** Default unary timeout / request SLA in ms. */
+    timeoutMs?: number;
+    /** Open the connection at app start instead of on first call. */
+    eager?: boolean;
+    /**
+     * Dev-server proxy target for the WebSocket endpoint, e.g.
+     * "http://localhost:9000". Adds a Nitro devProxy for `url` (same-origin in
+     * dev: no CORS, no origin patterns, no mixed content).
+     */
+    devProxy?: string;
+}
+declare const _default: _nuxt_schema.NuxtModule<VrpcModuleOptions, VrpcModuleOptions, false>;
+
+declare module "@nuxt/schema" {
+    interface PublicRuntimeConfig {
+        vrpc: {
+            url: string;
+            codec?: "msgpack" | "json" | undefined;
+            timeoutMs?: number | undefined;
+            eager?: boolean | undefined;
+        };
+    }
+}
+
+export { type VrpcModuleOptions, _default as default };

package/dist/module.js

@@ -0,0 +1,42 @@
+// src/module.ts
+import { addImports, addPlugin, createResolver, defineNuxtModule } from "@nuxt/kit";
+import { defu } from "defu";
+var module_default = defineNuxtModule({
+  meta: {
+    name: "@arpabet/vrpc-nuxt",
+    configKey: "vrpc",
+    compatibility: { nuxt: ">=3.13.0" }
+  },
+  defaults: {
+    url: "/rpc",
+    codec: "msgpack",
+    timeoutMs: 5e3,
+    eager: false
+  },
+  setup(options, nuxt) {
+    const resolver = createResolver(import.meta.url);
+    const existing = nuxt.options.runtimeConfig.public.vrpc ?? {};
+    nuxt.options.runtimeConfig.public.vrpc = {
+      url: existing.url ?? options.url,
+      codec: existing.codec ?? options.codec ?? "msgpack",
+      timeoutMs: existing.timeoutMs ?? options.timeoutMs ?? 5e3,
+      eager: existing.eager ?? options.eager ?? false
+    };
+    addPlugin(resolver.resolve("./runtime/plugin.client"));
+    for (const name of ["useVrpc", "useVrpcCall", "useVrpcStream", "useVrpcConnection"]) {
+      addImports({ name, from: "@arpabet/vrpc-vue" });
+    }
+    if (options.devProxy && nuxt.options.dev) {
+      const opts = nuxt.options;
+      opts.nitro = opts.nitro ?? {};
+      opts.nitro.devProxy = defu(opts.nitro.devProxy, {
+        [options.url]: { target: options.devProxy + options.url, ws: true }
+      });
+    }
+    nuxt.options.build.transpile.push("@arpabet/vrpc", "@arpabet/vrpc-vue");
+  }
+});
+export {
+  module_default as default
+};
+//# sourceMappingURL=module.js.map

package/dist/module.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/module.ts"],"sourcesContent":["/*\n * Copyright (c) 2026 Karagatan LLC.\n * SPDX-License-Identifier: Apache-2.0\n */\n\nimport { addImports, addPlugin, createResolver, defineNuxtModule } from \"@nuxt/kit\";\nimport { defu } from \"defu\";\n\nexport interface VrpcModuleOptions {\n  /**\n   * WebSocket endpoint. Overridable at runtime via\n   * NUXT_PUBLIC_VRPC_URL (runtimeConfig.public.vrpc.url). In dev, prefer a\n   * relative \"/rpc\" together with the devProxy option.\n   */\n  url: string;\n  /** \"msgpack\" (default, works with every server) or \"json\". */\n  codec?: \"msgpack\" | \"json\";\n  /** Default unary timeout / request SLA in ms. */\n  timeoutMs?: number;\n  /** Open the connection at app start instead of on first call. */\n  eager?: boolean;\n  /**\n   * Dev-server proxy target for the WebSocket endpoint, e.g.\n   * \"http://localhost:9000\". Adds a Nitro devProxy for `url` (same-origin in\n   * dev: no CORS, no origin patterns, no mixed content).\n   */\n  devProxy?: string;\n}\n\nexport default defineNuxtModule<VrpcModuleOptions>({\n  meta: {\n    name: \"@arpabet/vrpc-nuxt\",\n    configKey: \"vrpc\",\n    compatibility: { nuxt: \">=3.13.0\" },\n  },\n  defaults: {\n    url: \"/rpc\",\n    codec: \"msgpack\",\n    timeoutMs: 5000,\n    eager: false,\n  },\n  setup(options, nuxt) {\n    const resolver = createResolver(import.meta.url);\n\n    // Expose the client options via runtime config so NUXT_PUBLIC_VRPC_* env\n    // vars can override them per deployment.\n    const existing = (nuxt.options.runtimeConfig.public.vrpc ?? {}) as Partial<VrpcModuleOptions>;\n    nuxt.options.runtimeConfig.public.vrpc = {\n      url: existing.url ?? options.url,\n      codec: existing.codec ?? options.codec ?? \"msgpack\",\n      timeoutMs: existing.timeoutMs ?? options.timeoutMs ?? 5000,\n      eager: existing.eager ?? options.eager ?? false,\n    };\n\n    // SSR policy (WEB.md §6.6): the plugin is client-only. Server-side\n    // rendering shows the pending state; the browser connects and fills.\n    addPlugin(resolver.resolve(\"./runtime/plugin.client\"));\n\n    // Auto-import the composables.\n    for (const name of [\"useVrpc\", \"useVrpcCall\", \"useVrpcStream\", \"useVrpcConnection\"]) {\n      addImports({ name, from: \"@arpabet/vrpc-vue\" });\n    }\n\n    // Same-origin dev proxy for the WS endpoint. (Typed loosely: NuxtOptions\n    // only carries the nitro key when nitropack's types are installed.)\n    if (options.devProxy && nuxt.options.dev) {\n      const opts = nuxt.options as unknown as {\n        nitro?: { devProxy?: Record<string, unknown> };\n      };\n      opts.nitro = opts.nitro ?? {};\n      opts.nitro.devProxy = defu(opts.nitro.devProxy, {\n        [options.url]: { target: options.devProxy + options.url, ws: true },\n      });\n    }\n\n    // The runtime plugin imports these; make sure Vite pre-bundles them.\n    nuxt.options.build.transpile.push(\"@arpabet/vrpc\", \"@arpabet/vrpc-vue\");\n  },\n});\n\ndeclare module \"@nuxt/schema\" {\n  interface PublicRuntimeConfig {\n    vrpc: {\n      url: string;\n      codec?: \"msgpack\" | \"json\" | undefined;\n      timeoutMs?: number | undefined;\n      eager?: boolean | undefined;\n    };\n  }\n}\n"],"mappings":";AAKA,SAAS,YAAY,WAAW,gBAAgB,wBAAwB;AACxE,SAAS,YAAY;AAuBrB,IAAO,iBAAQ,iBAAoC;AAAA,EACjD,MAAM;AAAA,IACJ,MAAM;AAAA,IACN,WAAW;AAAA,IACX,eAAe,EAAE,MAAM,WAAW;AAAA,EACpC;AAAA,EACA,UAAU;AAAA,IACR,KAAK;AAAA,IACL,OAAO;AAAA,IACP,WAAW;AAAA,IACX,OAAO;AAAA,EACT;AAAA,EACA,MAAM,SAAS,MAAM;AACnB,UAAM,WAAW,eAAe,YAAY,GAAG;AAI/C,UAAM,WAAY,KAAK,QAAQ,cAAc,OAAO,QAAQ,CAAC;AAC7D,SAAK,QAAQ,cAAc,OAAO,OAAO;AAAA,MACvC,KAAK,SAAS,OAAO,QAAQ;AAAA,MAC7B,OAAO,SAAS,SAAS,QAAQ,SAAS;AAAA,MAC1C,WAAW,SAAS,aAAa,QAAQ,aAAa;AAAA,MACtD,OAAO,SAAS,SAAS,QAAQ,SAAS;AAAA,IAC5C;AAIA,cAAU,SAAS,QAAQ,yBAAyB,CAAC;AAGrD,eAAW,QAAQ,CAAC,WAAW,eAAe,iBAAiB,mBAAmB,GAAG;AACnF,iBAAW,EAAE,MAAM,MAAM,oBAAoB,CAAC;AAAA,IAChD;AAIA,QAAI,QAAQ,YAAY,KAAK,QAAQ,KAAK;AACxC,YAAM,OAAO,KAAK;AAGlB,WAAK,QAAQ,KAAK,SAAS,CAAC;AAC5B,WAAK,MAAM,WAAW,KAAK,KAAK,MAAM,UAAU;AAAA,QAC9C,CAAC,QAAQ,GAAG,GAAG,EAAE,QAAQ,QAAQ,WAAW,QAAQ,KAAK,IAAI,KAAK;AAAA,MACpE,CAAC;AAAA,IACH;AAGA,SAAK,QAAQ,MAAM,UAAU,KAAK,iBAAiB,mBAAmB;AAAA,EACxE;AACF,CAAC;","names":[]}

package/dist/runtime/plugin.client.mjs

@@ -0,0 +1,33 @@
+/*
+ * Copyright (c) 2026 Karagatan LLC.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+// Client-only plugin: creates the shared vrpc client from runtime config.
+// SSR never opens a WebSocket (WEB.md §6.6); pages render their pending
+// state on the server and the browser fills after hydration.
+
+import { defineNuxtPlugin, useRuntimeConfig } from "#app";
+import { createVrpc } from "@arpabet/vrpc-vue";
+
+export default defineNuxtPlugin((nuxtApp) => {
+  const cfg = useRuntimeConfig().public.vrpc ?? {};
+  const url = resolveUrl(cfg.url || "/rpc");
+  nuxtApp.vueApp.use(
+    createVrpc({
+      url,
+      codec: cfg.codec || "msgpack",
+      timeoutMs: cfg.timeoutMs ?? 5000,
+      eager: cfg.eager ?? false,
+    }),
+  );
+});
+
+// Accepts absolute ws(s):// URLs, or a path like "/rpc" resolved against the
+// page origin with the matching ws/wss scheme.
+function resolveUrl(url) {
+  if (/^wss?:\/\//.test(url)) return url;
+  if (/^https?:\/\//.test(url)) return url.replace(/^http/, "ws");
+  const scheme = location.protocol === "https:" ? "wss" : "ws";
+  return `${scheme}://${location.host}${url.startsWith("/") ? url : `/${url}`}`;
+}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@arpabet/vrpc-nuxt",
+  "version": "0.2.0",
+  "description": "Nuxt module for value-rpc: client plugin, auto-imported composables, runtime config",
+  "license": "Apache-2.0",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/module.d.ts",
+      "import": "./dist/module.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsup && rm -rf dist/runtime && cp -R src/runtime dist/runtime",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@arpabet/vrpc": "^0.2.0",
+    "@arpabet/vrpc-vue": "^0.2.0",
+    "@nuxt/kit": ">=3.13.0 <5",
+    "defu": "^6.1.4"
+  },
+  "devDependencies": {
+    "@nuxt/schema": ">=3.13.0 <5",
+    "tsup": "^8.3.0",
+    "typescript": "^5.6.0"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "keywords": [
+    "nuxt",
+    "nuxt-module",
+    "rpc",
+    "websocket",
+    "value-rpc"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/arpabet/value-rpc-js.git",
+    "directory": "packages/vrpc-nuxt"
+  }
+}