@zachacious/protoc-gen-connect-vue 1.0.20 → 1.0.22

package/README.md

@@ -1,177 +1,262 @@
-# **protoc-gen-connect-vue**
+# protoc-gen-connect-vue
 
-protoc-gen-connect-vue is a code generation plugin for [ConnectRPC](https://connectrpc.com/) tailored specifically for **Vue.js**. It generates a type-safe SDK that combines the power of **ConnectRPC** with the reactivity of the Vue Composition API and the caching capabilities of **TanStack Query (Vue-Query)**.
+[![npm version](https://img.shields.io/npm/v/@zachacious/protoc-gen-connect-vue?style=flat-square&color=cb3837&logo=npm)](https://www.npmjs.com/package/@zachacious/protoc-gen-connect-vue)
+[![license](https://img.shields.io/npm/l/@zachacious/protoc-gen-connect-vue?style=flat-square&color=blue)](LICENSE)
+![Vue 3](https://img.shields.io/badge/Vue-3-42b883?style=flat-square&logo=vuedotjs&logoColor=white)
 
-Unlike the official @connectrpc/connect-query which is architected for React, this plugin is built from the ground up for Vue developers, providing first-class support for ref, computed, and manual resource invalidation.
+A [ConnectRPC](https://connectrpc.com/) codegen plugin that emits a Vue client SDK: a reactive transport, async wrappers for every RPC, and TanStack Query (vue-query) hooks on top of them.
 
-Protoc-gen-connect-vue attempts to create the full SDK - The client and API Wrappers(standard and Vue-Query). If you are building a Vue.js project with a ConnectRPC(web) backend. This aims to be an all in one solution so you are ready to go client-side.
+The official `@connectrpc/connect-query` targets React. This covers the same ground for Vue — `ref`, `computed`, and cache invalidation that behaves the way a Vue app expects.
 
-> Note: I made this for use in personal and internal work projects. If you find it useful, let me know.
+> I built this for my own projects and internal work. If it's useful to you, let me know.
 
-## **Features**
+## What gets generated
 
-- **Reactive Client:** Automatically re-initializes the transport when your base URL or auth tokens change.
-- **TanStack Query Integration:** Generates useQuery, useMutation, and useInfiniteQuery hooks for every RPC.
-- **Manual Wrappers:** Provides standard async wrappers for actions that don't fit the "query" pattern.
-- **Message Initializers:** A createEmpty utility to generate default objects for any Protobuf message type.
-- **Query Key Factory:** Centralized query keys to simplify manual cache invalidation.
+Three files, into whatever directory you point the plugin at:
 
-## **Installation**
+| File | Contents |
+| --- | --- |
+| `client.ts` | Reactive transport, auth resolver, error callback, credentials mode, `globalQueryConfig` |
+| `api.ts` | `useApi()` with a wrapper + hook per RPC, plus `queryKeys` and `createEmpty` |
+| `index.ts` | Re-exports both |
 
-```bash
-# install plugin either globally or locally
+Every RPC gets an async wrapper (`getUser(req)`) and a hook (`useGetUser`). Paginated RPCs get a third: `useGetUserInfinite`.
+
+## Compatibility
+
+| Dependency | Supported versions |
+| --- | --- |
+| `@connectrpc/connect` / `@connectrpc/connect-web` | v1.6+ and v2 |
+| `@bufbuild/protobuf` / `protoc-gen-es` codegen | v2 |
+| `@tanstack/vue-query` | v5 |
+| Vue | 3 |
+
+Credentials are applied through a `fetch` override rather than the version-specific `credentials` transport option, so the generated code type-checks against both connect-web v1.6+ and v2.
 
+## Install
+
+The plugin itself:
+
+```bash
 npm install -g @zachacious/protoc-gen-connect-vue
 ```
 
-```Bash
-# install dependencies
+Runtime dependencies in your Vue app:
 
-npm install protoc-gen-connect-vue @tanstack/vue-query @connectrpc/connect @connectrpc/connect-web @bufbuild/protobuf
+```bash
+npm install @tanstack/vue-query @connectrpc/connect @connectrpc/connect-web @bufbuild/protobuf
 ```
 
-## **Generation**
+If you'd rather not install globally, add it as a dev dependency and point buf at the binary path (`local: ./node_modules/.bin/protoc-gen-connect-vue`).
 
-Add the plugin to your buf.gen.yaml:
+## Generate
 
-```YAML
+```yaml
 plugins:
-# ...
+  # ...
   - remote: buf.build/bufbuild/es
     out: web/src/api/gen
     opt:
       - target=ts
 
-  # Make sure this plugin goes after protoc-gen-es
-  # It should probably go last
-
-  # npm install -g @zachacious/protoc-gen-connect-vue
-  # https://www.npmjs.com/package/@zachacious/protoc-gen-connect-vue
+  # Must run after protoc-gen-es. Last is a safe place for it.
   - local: protoc-gen-connect-vue
     out: web/src/api
     opt: target=ts
 ```
 
-## **Setup**
+The two `out` paths are load-bearing. The generated client imports message types from `./gen/<proto>_pb` relative to its own directory, so the protoc-gen-es output has to sit in a `gen/` folder directly inside this plugin's output directory. The pairing above (`web/src/api/gen` and `web/src/api`) satisfies that.
+
+## How your RPCs are classified
+
+The generator infers intent from method names and message shapes. Knowing the rules saves you from wondering why a method got the hook it did.
+
+**Query vs. mutation.** A unary method whose name starts with `Create`, `Update`, `Delete`, `Remove`, `Patch`, `Post`, `Set`, or `Add` becomes a mutation. Every other unary method becomes a query. Name a mutating RPC `ArchiveUser` and you'll get a query hook that auto-fetches.
+
+**Cache resource.** The leading verb (`Get`, `List`, `ListAll`, `Search`, or any mutation verb) is stripped from the method name and what's left becomes the resource key. `GetUser`, `ListUsers`, and `UpdateUser` land on `User`, `Users`, and `User` respectively — note that `ListUsers` does *not* share a bucket with `GetUser`. If you want list queries invalidated by a single-item mutation, name them consistently.
 
-### **1. Configure the Provider**
+**Pagination.** A query gets an infinite hook when both its request and response carry pagination fields. The request is searched for `page_token`, `page_number`, `next_page_token`, `offset`, or `cursor`; the response for `next_page_token`, `next_page`, or `next_cursor`. Fields nested one to three levels deep inside a message named `page`/`paging`/`meta` count too.
 
-In your main.ts, provide the QueryClient to your Vue application.
+**Streaming.** Only unary methods are supported. Streaming methods are classified as mutations and the generated hook will not work on them.
 
-```TypeScript
+**Services.** Only the first service found in the schema is generated. A multi-service proto needs a separate buf plugin invocation per service.
 
-import { createApp } from 'vue';
-import { QueryClient, VueQueryPlugin } from '@tanstack/vue-query';
-import { globalQueryConfig } from './api/generated/client';
-import App from './App.vue';
+## Setup
+
+### 1. Register the query client
+
+```ts
+// main.ts
+import { createApp } from "vue";
+import { QueryClient, VueQueryPlugin } from "@tanstack/vue-query";
+import { globalQueryConfig } from "@/api";
+import App from "./App.vue";
 
 const app = createApp(App);
 const queryClient = new QueryClient(globalQueryConfig);
 
 app.use(VueQueryPlugin, { queryClient });
-app.mount('#app');
+app.mount("#app");
 ```
 
-### **2. Runtime Configuration**
+`globalQueryConfig` sets a 5-minute `staleTime`, a 30-minute `gcTime`, and `networkMode: "offlineFirst"`. Drop it and pass your own config if those don't suit you.
 
-Set up your authentication and base URL, typically in an identity store or main entry point.
+### 2. Runtime configuration
 
-```TypeScript
+The base URL defaults to `http://localhost:3000`, so set it before your first request — in an auth store, or at the top of `main.ts`.
 
-import { setBaseUrl, setAuthResolver, setSDKErrorCallback } from '@/api/generated';
+```ts
+import { setBaseUrl, setAuthResolver, setSDKErrorCallback } from "@/api";
 
-setBaseUrl('https://api.example.com');
+setBaseUrl("https://api.example.com");
 
-// Supports async token resolution
-setAuthResolver(async () => {
- const token = localStorage.getItem('token');
- return token ? token : null;
-});
+// Called on every request. Sync or async.
+setAuthResolver(async () => localStorage.getItem("token"));
 
 setSDKErrorCallback((err, url) => {
- console.error(`API Error at ${url}: ${err.message}`);
+  console.error(`API error at ${url}: ${err.message}`);
 });
 ```
 
-## **Usage**
+A non-null token is sent as the **`x-api-key`** header, not `Authorization: Bearer`. Your backend needs to read that header, or you need to edit the generated interceptor.
+
+Changing the base URL rebuilds the transport, and any component holding a client picks it up through `computed`. The auth resolver is different — it's called fresh on every request, so a token change needs no rebuild and no re-render.
+
+### 3. Cookies and credentials
+
+The transport sends cookies cross-origin by default (`credentials: "include"`). If your backend's CORS setup doesn't allow credentials, change the mode at startup:
+
+```ts
+import { setFetchCredentials } from "@/api";
+
+// "include" (default) | "same-origin" | "omit"
+setFetchCredentials("same-origin");
+```
+
+It takes effect on the next request; no transport rebuild.
+
+> **Upgrading from 1.0.20 or earlier:** those releases passed a `fetchOptions` key that connect-web ignored, so the `"include"` default never reached the wire and your app ran on the browser default of `"same-origin"`. From 1.0.21 it takes effect. Cross-origin backends serving `Access-Control-Allow-Origin: *`, or without `Access-Control-Allow-Credentials: true`, will start failing CORS after you regenerate — fix the backend or call `setFetchCredentials("same-origin")`. Full notes in the [CHANGELOG](CHANGELOG.md).
+
+## Usage
+
+`useApi()` calls `useQueryClient()` internally, so it has to run inside `setup()` with `VueQueryPlugin` installed.
 
-### **Using Hooks and Manual Wrappers**
+### Queries
 
-The generated SDK provides both automated hooks and manual async functions.
+Hooks take the full request message, not a bare id. Wrap it in `computed` to make it reactive — vue-query unwraps refs in both the key and the request.
 
-```html
+```vue
 <script setup lang="ts">
-  import { ref } from "vue";
-  import { useApi } from "@/api/generated";
-
-  const { getUser, useGetUser } = useApi();
-
-  // 1. Reactive Hook (Auto-fetches)
-  const userId = ref("123");
-  const { data, isLoading, error } = useGetUser(userId);
-
-  // 2. Manual Action
-  const handleUpdate = async () => {
-    const { data, error } = await updateUser({ id: "123", name: "New Name" });
-    if (!error) {
-      // Note: The SDK automatically invalidates related queries on success
-      console.log("Update successful");
-    }
-  };
+import { computed, ref } from "vue";
+import { useApi } from "@/api";
+
+const { useGetUser } = useApi();
+
+const userId = ref("123");
+const { data, isLoading, error } = useGetUser(
+  computed(() => ({ id: userId.value })),
+);
 </script>
 
 <template>
-  <div v-if="isLoading">Loading...</div>
+  <div v-if="isLoading">Loading…</div>
   <div v-else-if="error">{{ error }}</div>
-  <div v-else>
-    <h1>{{ data?.name }}</h1>
-    <button @click="handleUpdate">Update Profile</button>
-  </div>
+  <h1 v-else>{{ data?.name }}</h1>
 </template>
 ```
 
-### **Initializing New Data (createEmpty)**
+A second argument is spread into the underlying `useQuery` options, so `enabled`, `select`, `retry` and friends all work.
+
+### Mutations
+
+Mutation hooks take options only; the request goes to `mutate`. On success they invalidate the whole resource bucket.
+
+```vue
+<script setup lang="ts">
+import { useApi } from "@/api";
+
+const { useUpdateUser } = useApi();
+const { mutate, isPending } = useUpdateUser();
+
+const save = () => mutate({ id: "123", name: "New Name" });
+</script>
+```
+
+Passing your own `onSuccess` replaces the generated one and skips the invalidation. Invalidate yourself in that callback, or use `onSettled` instead.
+
+### Async wrappers
+
+Every RPC also gets a plain async function for cases that don't fit a hook — a submit handler, a store action, anything imperative. It returns `{ data, error }` instead of throwing, where `error` is the `ConnectError` message string.
+
+```ts
+const { updateUser } = useApi();
+
+const { data, error } = await updateUser({ id: "123", name: "New Name" });
+if (error) {
+  // handle it
+}
+```
+
+Wrappers invalidate their resource on success — including the wrappers for read methods. Calling `getUser()` imperatively invalidates `["User"]` and will refetch any mounted `useGetUser`. Use the hook for reads unless you specifically want that.
 
-Protobuf messages often require specific default values (e.g., empty strings instead of undefined). The createEmpty utility ensures your local state matches the expected Protobuf structure.
+### Infinite queries
+
+```ts
+const { useListUsersInfinite } = useApi();
+
+const { data, fetchNextPage, hasNextPage } = useListUsersInfinite({ limit: 20 });
+```
 
-```TypeScript
+The page token is written into the request at the path the generator discovered, and read back off the response the same way. `initialPageParam` defaults to `""` and can be overridden through the options argument.
 
-import { useApi } from '@/api/generated';
+### createEmpty
+
+Protobuf messages want concrete defaults — empty strings rather than `undefined`. `createEmpty` builds one for any message type in the service graph, with optional overrides.
+
+```ts
+import { useApi } from "@/api";
 
 const { createEmpty } = useApi();
 
-// Create an empty Customer object with all Protobuf defaults
-// Useful when you need to create and empty instance instead of using a nullable object
 const newCustomer = ref(createEmpty.Customer({ name: "Initial Name" }));
 ```
 
-### **Manual Cache Invalidation (queryKeys)**
-
-If you need to manually refresh or invalidate a specific query, use the queryKeys factory to ensure the key matches the one used by the generated hooks.
+### Manual invalidation
 
-```TypeScript
+`queryKeys` produces `[resource, functionName, input]`. Since TanStack matches on key prefixes, invalidating a resource is the reliable move:
 
-import { useQueryClient } from '@tanstack/vue-query';
-import { queryKeys } from '@/api/generated';
+```ts
+import { useQueryClient } from "@tanstack/vue-query";
+import { queryKeys } from "@/api";
 
 const queryClient = useQueryClient();
 
-const refreshUser = (id: string) => {
- queryClient.invalidateQueries({
- queryKey: queryKeys.getUser(id)
- });
-};
+// Everything derived from the User resource
+queryClient.invalidateQueries({ queryKey: ["User"] });
+
+// A single query — the input must deep-equal what the hook was called with
+queryClient.invalidateQueries({ queryKey: queryKeys.getUser({ id: "123" }) });
 ```
 
-## **Global Loading State**
+`queryKeys` and `createEmpty` are exported at module scope as well as from `useApi()`, so you can use them outside components.
 
-The SDK exports a reactive isGlobalLoading computed property that tracks if any RPC (query or mutation) is currently in flight.
+### Global loading state
 
-```TypeScript
+`isGlobalLoading` is a computed that's true while any query or mutation is in flight. Handy for a top-level progress bar.
 
+```ts
 const { isGlobalLoading } = useApi();
 ```
 
----
+## Known limitations
+
+- One service per invocation.
+- Unary methods only.
+- Hook inputs and options are typed `any`. Request and response types are checked on the async wrappers, not on the hooks.
+- Method naming drives both the mutation classification and the cache buckets. Unconventional names produce surprising hooks.
+- A user-supplied `onSuccess` on a mutation hook overrides the automatic invalidation rather than running after it.
+- `BigInt.prototype.toJSON` is patched globally by the generated client so 64-bit fields survive serialization.
+
+## License
 
-License MIT
+MIT

package/dist/generator.js

@@ -77276,7 +77276,7 @@ ${lanes.join(`
             if (!links2.hasReportedStatementInAmbientContext) {
               return links2.hasReportedStatementInAmbientContext = grammarErrorOnFirstToken(node, Diagnostics.Statements_are_not_allowed_in_ambient_contexts);
             }
-          } else {}
+          }
         }
         return false;
       }
@@ -86926,7 +86926,7 @@ ${lanes.join(`
               ], 2));
               setParentRecursive(requireStatement, false);
               statements = insertStatementAfterCustomPrologue(statements.slice(), requireStatement);
-            } else {}
+            }
           }
         }
         if (statements !== visited.statements) {
@@ -246201,7 +246201,7 @@ ${lanes.join(`
             if (!links2.hasReportedStatementInAmbientContext) {
               return links2.hasReportedStatementInAmbientContext = grammarErrorOnFirstToken(node, Diagnostics.Statements_are_not_allowed_in_ambient_contexts);
             }
-          } else {}
+          }
         }
         return false;
       }
@@ -255665,7 +255665,7 @@ ${lanes.join(`
               ], 2));
               setParentRecursive(requireStatement, false);
               statements = insertStatementAfterCustomPrologue(statements.slice(), requireStatement);
-            } else {}
+            }
           }
         }
         if (statements !== visited.statements) {
@@ -336813,6 +336813,7 @@ var KNOWN_WKT = [
 ];
 var currentDir = new URL(".", import.meta.url).pathname;
 var templateDir = path.join(currentDir, "..", "templates");
+var pkg = JSON.parse(fs.readFileSync(path.join(currentDir, "..", "package.json"), "utf-8"));
 var templates = {
   client: fs.readFileSync(path.join(templateDir, "client.ts.mustache"), "utf-8"),
   api: fs.readFileSync(path.join(templateDir, "api.ts.mustache"), "utf-8"),
@@ -336922,7 +336923,7 @@ function processService(service) {
 }
 var plugin = createEcmaScriptPlugin({
   name: "protoc-gen-connect-vue",
-  version: "v1.10.0",
+  version: `v${pkg.version}`,
   generateTs: (schema) => {
     const service = schema.files.flatMap((f) => f.services)[0];
     if (!service)

package/package.json

@@ -1,7 +1,24 @@
 {
   "name": "@zachacious/protoc-gen-connect-vue",
-  "version": "1.0.20",
-  "description": "Smart TanStack Query & ConnectRPC SDK generator for Vue.js",
+  "version": "1.0.22",
+  "description": "Type-safe Vue 3 SDK generator for ConnectRPC with TanStack Query hooks",
+  "keywords": [
+    "protoc",
+    "protoc-plugin",
+    "protobuf",
+    "connectrpc",
+    "connect-rpc",
+    "grpc",
+    "grpc-web",
+    "vue",
+    "vue3",
+    "vue-query",
+    "tanstack-query",
+    "codegen",
+    "sdk-generator",
+    "typescript",
+    "buf"
+  ],
   "type": "module",
   "license": "MIT",
   "author": "Zachacious",

package/templates/client.ts.mustache

@@ -32,6 +32,23 @@ export type ErrorCallback = (error: ConnectError, url: string) => void;
 let onError: ErrorCallback = () => {};
 export const setSDKErrorCallback = (cb: ErrorCallback) => { onError = cb; };
 
+// --- FETCH CREDENTIALS ---
+// connect-web v1 exposed a `credentials` option on the transport; v2 removed it
+// in favor of overriding `fetch`. Wrapping fetch works on both major versions.
+const credentialsMode = ref<RequestCredentials>("include");
+
+/**
+ * Set the fetch credentials mode ("include" | "same-origin" | "omit").
+ * Defaults to "include" so cookie-based auth works cross-origin.
+ * Takes effect on the next request; no transport rebuild required.
+ */
+export const setFetchCredentials = (mode: RequestCredentials) => {
+  credentialsMode.value = mode;
+};
+
+const fetchWithCredentials: typeof globalThis.fetch = (input, init) =>
+  globalThis.fetch(input, { ...init, credentials: credentialsMode.value });
+
 const transportInterceptor: Interceptor = (next) => async (req) => {
   const token = await resolveToken();
   if (token) req.header.set("x-api-key", token);
@@ -54,7 +71,7 @@ export const useGrpcClient = () => {
   const transport = computed(() => createConnectTransport({
     baseUrl: baseUrl.value,
     interceptors: [transportInterceptor],
-    fetchOptions: { credentials: "include" },
+    fetch: fetchWithCredentials,
   }));
 
   const client = computed(() => createClient({{serviceName}}, transport.value));
@@ -103,6 +120,11 @@ async function handleUpdate() {
   <p>{{ manualResult }}</p>
 </template>
 
+// Cookies are sent cross-origin by default (credentials: "include").
+// If your backend's CORS config doesn't allow credentials, opt out with:
+// import { setFetchCredentials } from '@/api';
+// setFetchCredentials("same-origin");
+
 // use this to set the error interceptor - for instance to log to sentry or something
 import { setAuthResolver, setSDKErrorCallback } from '@/api';
 import { useAuthStore } from '@/stores/auth';