@lewebsimple/nuxt-graphql 0.2.2 → 0.3.0

package/README.md

@@ -5,23 +5,23 @@
 [![License][license-src]][license-href]
 [![Nuxt][nuxt-src]][nuxt-href]
 
-Opinionated Nuxt module that ships a stitched GraphQL Yoga server, typed GraphQL Codegen, and client/server composables powered by graphql-request and graphql-sse.
+Opinionated Nuxt module that wires a typed GraphQL server + client into your app.
+
+[✨  Release Notes](/CHANGELOG.md)
 
-- ✨ [Release Notes](/CHANGELOG.md)
-- 🏀 [Online playground](https://stackblitz.com/github/lewebsimple/nuxt-graphql?file=playground%2Fapp.vue)
 
 ## Features
 
-- 🧘‍♂️ GraphQL Yoga handler at `/api/graphql` with GraphiQL in development.
-- 🪡 Schema stitching: mix local schemas and remote endpoints (with per-source headers). Stitched SDL is emitted to `server/graphql/schema.graphql` (configurable).
-- 🚦 Remote middleware hooks: per-remote `onRequest` / `onResponse` callbacks to tweak headers, log responses, or short-circuit requests before forwarding.
-- 🪄 Code generation: scans named operations in `**/*.gql` (across Nuxt layers), generates typed documents, operations, registry (`#graphql/registry`), and optional Zod validation.
-- 🧩 Typed composables: `useGraphQLQuery`, `useGraphQLMutation`, `useGraphQLSubscription` consume registry names (e.g. `useGraphQLQuery("Hello")`). Server equivalents mirror the API for Nitro handlers.
-- 🚀 Caching and dedupe: in-memory or localStorage TTL cache, in-flight request deduplication, and refresh callbacks driven by runtime config.
-- 📡 SSE subscriptions: client-only via graphql-sse, using the same registry documents.
-- 🛡️SSR-friendly clients: forward `cookie` and `authorization` headers automatically on the server.
+- 🧘 **GraphQL Yoga** server at `/api/graphql` (**GraphiQL** in dev) + **SSE subscriptions**
+- 🪡 **Stitched schema** from local and/or remote schemas (remote introspection at build time)
+- 🪄 Code generation from `.gql` documents → **typed documents nodes** + **Zod** input schemas output
+- 🧠 **Type-safe GraphQL helpers** for **queries, mutations, and subscriptions**, driven by **operation names** and shared across **client + server routes**
+- 🧊 **SSR-friendly** by default: request header/cookie forwarding + no-HTTP server execution helpers
+- 🚀 **Query caching** for `useGraphQLQuery` (cache policies + optional persistence in localStorage)
+- 🪝 **Optional hooks**: Yoga middleware + per-remote executor middleware + client error hook (`graphql:error`)
+
 
-## Quick start
+## Getting started
 
 Install the module to your Nuxt application with one command:
 
@@ -29,85 +29,391 @@ Install the module to your Nuxt application with one command:
 pnpx nuxi module add @lewebsimple/nuxt-graphql
 ```
 
-Configure at least one schema (local or remote) and optionnally your context (path to your context factory). Example with a local schema and remote stitched source:
+
+### Configuration
+
+Declare your schemas, context, documents glob and any optional middleware in `nuxt.config.ts`:
 
 ```ts
-// nuxt.config.ts
 export default defineNuxtConfig({
   modules: ["@lewebsimple/nuxt-graphql"],
   graphql: {
-    // Optional: path to your GraphQL context factory
-    // Defaults to src/runtime/server/lib/default-context.ts if omitted
-    context: "server/graphql/context.ts",
+    // Schemas to stitch together (local and/or remote)
     schemas: {
-      local: { type: "local", path: "server/graphql/schema.ts" },
+      local: {
+        type: "local",
+        path: "server/graphql/schema.ts",
+      },
+      // Remote schema example
       swapi: {
         type: "remote",
-        url: "https://swapi-graphql.netlify.app/.netlify/functions/index",
+        url: "https://swapi-graphql.netlify.app/graphql",
+        // Optional: static headers for this remote
+        headers: {
+          "X-Static-Header": "static-header-value",
+        },
+        // Optional: per-remote execution middleware (onRequest / onResponse / onError hooks)
         middleware: "server/graphql/swapi-middleware.ts",
       },
     },
-    codegen: {
-      documents: "**/*.gql", // only named operations allowed
-      saveSchema: "server/graphql/schema.graphql",
+    
+    // Optional: custom GraphQL context (defaults to {})
+    context: "server/graphql/context.ts",
+
+    // Optional: documents glob (defaults to **/*.gql)
+    documents: "**/*.gql",
+
+    // Optional: Yoga middleware (onRequest / onResponse hooks)
+    middleware: "server/graphql/yoga-middleware.ts",
+
+    // Optional: query caching (client-side only)
+    // - In-memory cache uses Nuxt `useAsyncData`/`useNuxtData`
+    // - Persistence in localStorage is enabled when `ttl` is set
+    // - Version / prefix allow cache invalidation accross deployments
+    cache: {
+      cachePolicy: "cache-first", // "no-cache" | "cache-first" | "network-first" | "swr"
+      cacheVersion: "1",
+      keyPrefix: "gql",
+      // Persist cache entries in localStorage with TTL in seconds
+      // - 0 = never expires
+      // - undefined = persistence disabled
+      ttl: 60,
+    },
+
+    // Optional: save path for the generated stitched SDL (defaults to .nuxt/graphql/schema.graphql)
+    sdl: "server/graphql/schema.graphql",
+  },
+});
+```
+
+
+### Define your schema(s) (local and/or remote)
+
+**Local schemas** must be located inside `server/` and export an executable `GraphQLSchema` using the tool of your choice (graphql-yoga, Pothos, etc).
+
+⚠️ Using auto-imported utilities or importing from aliases might break code generation.
+
+For the example configuration above, create `server/graphql/schema.ts`:
+
+```ts
+import { createSchema } from "graphql-yoga";
+import type { GraphQLContext } from "#graphql/context";
+
+export const schema = createSchema<GraphQLContext>({
+  typeDefs: /* GraphQL */ `
+    type Query {
+      hello: String!
+    }
+    type Mutation {
+      ping(message: String!): String!
+    }
+    type Subscription {
+      time: String!
+    }
+  `,
+  resolvers: {
+    Query: {
+      hello: () => "Hello from Nuxt GraphQL!",
+    },
+    Mutation: {
+      ping: (_parent, args) => `pong: ${args.message}`,
     },
-    client: {
-      cache: { enabled: true, ttl: 60_000, storage: "memory" },
-      headers: {},
+    Subscription: {
+      time: {
+        subscribe: async function* () {
+          while (true) {
+            yield { time: new Date().toISOString() };
+            await new Promise((r) => setTimeout(r, 1000));
+          }
+        },
+      },
     },
   },
 });
 ```
 
-Define context (optional) in `server/graphql/context.ts`:
+**Remote schemas** are introspected at build time from the required endpoint URL. Each remote can be configured with optional static headers and remote execution middleware (see configuration above).
+
+
+### Define a type-safe GraphQL context (optional)
+
+The GraphQL context can be user-defined with the provided `defineGraphQLContext` helper. This ensures proper server-side typing by inferring the type from the return value of the context creation function. The `GraphQLContext` type can be imported from the `#graphql/context` server alias.
+
+For example, providing the user from the `nuxt-auth-utils` session with the configuration above, create `server/graphql/context.ts`:
 
 ```ts
-import type { H3Event } from "h3";
+import { defineGraphQLContext } from "@lewebsimple/nuxt-graphql";
+import { getUserSession } from "nuxt-auth-utils";
+
+export default defineGraphQLContext(async (event) => {
+  const session = await getUserSession(event);
+  return {
+    user: session?.user ?? null,
+  };
+});
+```
 
-export async function createContext(event: H3Event) {
-  return { event, user: event.context.user };
+
+### Write GraphQL documents (`.gql`)
+
+Write operations in `.gql` document files; operation names become registry keys like `useGraphQLQuery("HelloWorld")`.
+
+⚠️ Operation names are required and must be unique.
+
+By default, the module scans `**/*.gql` and generates:
+
+- Typed documents in `#graphql/typed-documents`
+- Operation registry by name in `#graphql/registry` (used internally)
+- Zod schemas in `#graphql/zod`
+- A `graphql.config.json` at the project root (editor tooling)
+
+Example document files (filenaming convention can vary):
+```graphql
+# app/graphql/HelloWorld.query.gql
+query HelloWorld {
+  hello
 }
 ```
 
-Write named operations in `.gql` files and use the auto-generated composables by operation name:
+```graphql
+# app/graphql/Ping.mutation.gql
+mutation Ping($message: String!) {
+  ping(message: $message)
+}
+```
 
-```ts
-const { data, pending, error } = useGraphQLQuery("Hello", { name: "world" });
-const { mutate } = useGraphQLMutation("Ping");
-const { data: time } = useGraphQLSubscription("Time");
+```graphql
+# app/graphql/Time.subscription.gql
+subscription Time {
+  time
+}
 ```
 
 That's it! You can now use Nuxt GraphQL in your Nuxt app ✨
 
-Yoga GraphiQL is available at `http://localhost:3000/api/graphql` by default.
+### Fragments
+
+Fragments are fully supported and are the recommended way to share selection sets across operations.
+
+- Fragment names must be unique across all `.gql` files (duplicates throw during generation).
+- Fragments are generated into `#graphql/typed-documents` by GraphQL Codegen:
+  - a TypeScript type like `TheFilmFragment`
+  - and a document constant like `TheFilmFragmentDoc`
+- Fragments are **not executable by themselves** (GraphQL requires an operation), and they are **not part of the `#graphql/registry`**. The auto-imported composables and server utilities only accept operation names (`query` / `mutation` / `subscription`).
 
-Optional: add a remote middleware at `server/graphql/swapi-middleware.ts` to adjust headers or log activity for stitched sources:
+Example with a fragment:
+
+```graphql
+# app/graphql/SwapiFilms.query.gql
+fragment TheFilm on Film {
+  title
+  releaseDate
+}
+
+query SwapiFilms {
+  allFilms {
+    films {
+      ...TheFilm
+    }
+  }
+}
+```
+
+From TypeScript, you can also use fragment types explicitly when you need them:
 
 ```ts
-export default {
-  async onRequest({ fetchOptions }) {
-    return {
-      ...fetchOptions,
-      headers: {
-        ...fetchOptions.headers,
-        "x-swapi-api-key": process.env.SWAPI_TOKEN ?? "",
-      },
-    };
+import type { TheFilmFragment } from "#graphql/typed-documents";
+```
+
+
+### Use the auto-imported composables
+
+The auto-imported operation composables allow executing **queries**, **mutations** and **subscriptions** based on their registry name with full type-safety (variables and return value).
+
+```ts
+// Query (useAsyncData under the hood)
+const { data, pending, error, refresh } = await useGraphQLQuery(
+  "HelloWorld", // Registry name, i.e. "query HelloWorld { hello }"
+  undefined, // Type-safe variables
+  {
+    // Custom request headers
+    headers: {
+      "X-Request-Header": "request-header-value"
+    },
+    // Additional useAsyncData options
+    // lazy: true,
+  },
+);
+
+// Mutation
+const { mutate } = useGraphQLMutation("Ping", {
+  // Custom request headers
+  headers: {
+    "X-Request-Header": "request-header-value"
+  },
+});
+const { data, pending, error } = await mutate({ message: "Hello from ping mutation!" }, {
+  // Each `mutate` call may send additional headers
+  headers: {
+    "X-Mutate-Header": "mutate-header-value",
+  },
+});
+
+// Subscription (client-only, SSE)
+const { data, error, start, stop } = useGraphQLSubscription("Time");
+// data and error are shallowRef
+```
+
+### Use the auto-imported server-side utilities
+
+In server routes, you can execute **queries** and **mutations** directly against the stitched schema (no HTTP roundtrip):
+
+```ts
+export default defineEventHandler(async (event) => {
+  // Server-side GraphQL query example
+  const { hello } = await useServerGraphQLQuery(event, "HelloWorld", undefined, {
+    headers: {
+      "X-Server-Header": "server-header-value",
+    },
+  });
+
+  // Server-side GraphQL mutation example
+  const { mutate } = useServerGraphQLMutation(event, "Ping", {
+    headers: {
+      "X-Server-Header": "server-header-value",
+    },
+  });
+  const { ping } = await mutate({ message: hello }, {
+    headers: {
+      "X-Mutation-Header": "mutation-header-value",
+    },
+  });
+
+  return { ping };
+});
+```
+
+The function signature is almost identical to the auto-imported composables, except you need to pass `event` as the first argument (and of course queries don't rely on `useAsyncData`).
+
+Also, resulting data is returned directly from `useServerGraphQLQuery` and `mutate` (throws an error on failure).
+
+
+### Query caching (client-side only)
+
+`useGraphQLQuery` can cache **query results** based on the global cache configuration (see configuration above) and per-query overrides (see below).
+
+- In-flight requests are **deduplicated** (same operation + variables → one network call).
+- **In-memory** cache uses Nuxt `useAsyncData`/`useNuxtData`.
+- **Persisted** cache stores entries in `localStorage` for `ttl` seconds (`0` = never expires).
+
+#### Cache policies
+
+- `"no-cache"`: always fetches from the network (still dedupes in-flight).
+- `"cache-first"`: returns cached value when present, otherwise fetches.
+- `"network-first"`: tries the network first, falls back to cached value on error.
+- `"swr"` (stale-while-revalidate): returns cached value immediately (when present) and refreshes in the background.
+
+#### Per-query overrides
+
+Caching configuration can be overridden per-query:
+
+```ts
+const { data } = await useGraphQLQuery("HelloWorld", undefined, {
+  cache: {
+    cachePolicy: "network-first",
+    ttl: undefined, // disable persistence for this call
   },
-  async onResponse({ operationName }) {
-    console.log(`[SWAPI] completed ${operationName ?? "unknown"}`);
+});
+```
+
+#### Manual invalidation
+
+On the client, `useGraphQLCache()` is used to invalidate in-memory and/or persisted entries:
+
+```ts
+const { invalidateByKey, invalidateByOperation, invalidateAll } = useGraphQLCache();
+
+// Invalidate a single entry (operation + variables)
+await invalidateByKey("HelloWorld", {});
+
+// Invalidate all entries for an operation (all variables)
+await invalidateByOperation("HelloWorld");
+
+// Optional: target a specific layer
+await invalidateByOperation("HelloWorld", { layer: "persisted" });
+
+// Invalidate all entries
+await invalidateAll();
+```
+
+
+### Yoga middleware (optional)
+
+You can define custom logic around the Yoga event handler by using the provided `defineYogaMiddleware` helper with the following hooks:
+- `onRequest` runs before Yoga handles the request;
+- `onResponse` runs after and can replace the outgoing `Response` via `setResponse`.
+
+For the example configuration above, create `server/graphql/yoga-middleware.ts`:
+
+```ts
+import { defineYogaMiddleware } from "@lewebsimple/nuxt-graphql";
+import { getUserSession } from "nuxt-auth-utils";
+
+export default defineYogaMiddleware({
+  async onRequest({ event, context, request }) {
+    const session = await getUserSession(event);
+    if (!session?.user) {
+      throw createError({ statusCode: 401, message: "Unauthorized" });
+    }
   },
-} satisfies RemoteMiddleware
+  async onResponse({ event, context, request, response, setResponse }) {
+    setHeader(event, "X-Custom-Yoga-Middleware-Response-Header", "my-custom-value");
+  },
+});
 ```
 
-Both hooks are optional; return a new `RequestInit` from `onRequest` to override the outgoing fetch, or use `onResponse` for side-effects such as metrics and logging.
+### Remote executor middleware (optional, per remote)
+
+You can define custom logic around the remote executor (from `@graphql-tools/utils`) for each one of your remote schema by using the provided `defineRemoteExecMiddleware` helper with the following hooks:
+- `onRequest` runs before the fetch (headers are mutable);
+- `onResponse` runs after an OK response before JSON parsing (cloned response);
+- `onError` runs for non-2xx responses, GraphQL errors returned in the payload, JSON parse failures, or network errors (the `response` can be `undefined` in that last case).
+
+⚠️ Remote executor middlewares don't have access to the H3 `event` handled by Yoga since they are executed in the context of the delegated subschema resolution.
 
-## Development notes
+For the example configuration above, create `server/graphql/swapi-middleware.ts`:
+
+```ts
+import { defineRemoteExecMiddleware } from "@lewebsimple/nuxt-graphql";
+
+export default defineRemoteExecMiddleware({
+  onRequest({ remoteName, operationName, context, fetchOptions }) {
+    console.log(`SWAPI Request Middleware [${remoteName} - ${operationName}]`);
+    fetchOptions.headers.set("X-Remote-Exec-Request-Header", "custom-value");
+  },
+  onResponse({ remoteName, operationName, context, response }) {
+    console.log(`SWAPI Response Middleware [${remoteName} - ${operationName}]`);
+  },
+  onError({ remoteName, operationName, error }) {
+    console.error(`SWAPI Error Middleware [${remoteName} - ${operationName}]:`, error);
+  },
+});
+```
+
+### Client error hook (optional)
+
+Handle normalized GraphQL errors globally on the client (toast, logging, etc.).
+
+The client calls the `graphql:error` Nuxt hook when a `graphql-request` response contains errors:
+
+```ts
+export default defineNuxtPlugin((nuxtApp) => {
+  nuxtApp.hook("graphql:error", (error) => {
+    console.error("GraphQL error", error);
+  });
+});
+```
 
-- Generated artifacts live under `.nuxt/graphql` and `.graphqlrc`; they are rewritten only when contents change.
-- Operations must be **named and unique**; duplicates or unnamed operations fail codegen.
-- SSE subscriptions are client-only; do not call `$graphqlSSE` on the server.
-- Cache defaults come from `runtimeConfig.public.graphql.cache`; pass `cache: false` to per-call options to bypass.
 
 ## Contribution
 
@@ -151,5 +457,5 @@ Both hooks are optional; return a new `RequestInit` from `onRequest` to override
 [license-src]: https://img.shields.io/npm/l/@lewebsimple/nuxt-graphql.svg?style=flat&colorA=020420&colorB=00DC82
 [license-href]: https://npmjs.com/package/@lewebsimple/nuxt-graphql
 
-[nuxt-src]: https://img.shields.io/badge/Nuxt-020420?logo=nuxt.js
+[nuxt-src]: https://img.shields.io/badge/Nuxt-020420?logo=nuxt
 [nuxt-href]: https://nuxt.com

package/dist/module.d.mts

@@ -1,35 +1,47 @@
 import * as _nuxt_schema from '@nuxt/schema';
-import { GraphQLCacheConfig } from '../dist/runtime/app/utils/graphql-cache.js';
+export { defineGraphQLContext } from '../dist/runtime/server/lib/define-graphql-context.js';
+export { defineRemoteExecMiddleware } from '../dist/runtime/server/lib/define-remote-exec-middleware.js';
+export { defineYogaMiddleware } from '../dist/runtime/server/lib/define-yoga-middleware.js';
 
-type LocalSchema = {
+/**
+ * Find multiple files across directories
+ *
+ * @param dirs Directories to search in
+ * @param pattern Glob pattern relative to each directory
+ * @returns Array of found file paths
+ */
+type GlobPattern = string | string[];
+
+type CachePolicy = "no-cache" | "cache-first" | "network-first" | "swr";
+interface CacheConfig {
+    cachePolicy: CachePolicy;
+    cacheVersion: string;
+    keyPrefix: string;
+    ttl?: number;
+}
+
+type LocalSchemaDef = {
     type: "local";
     path: string;
 };
-type RemoteSchema = {
+type RemoteSchemaDef = {
     type: "remote";
     url: string;
-    headers?: Record<string, string>;
+    headers?: HeadersInit;
     middleware?: string;
 };
-type SchemaDefinition = LocalSchema | RemoteSchema;
+type SchemaDef = LocalSchemaDef | RemoteSchemaDef;
 
-interface ModuleOptions {
+interface NuxtGraphQLModuleOptions {
+    schemas: Record<string, SchemaDef>;
     context?: string;
-    schemas: Record<string, SchemaDefinition>;
-    codegen?: {
-        documents?: string;
-        saveSchema?: string;
-        scalars?: Record<string, string | {
-            input: string;
-            output: string;
-        }>;
-    };
-    client?: {
-        cache?: Partial<GraphQLCacheConfig>;
-        headers?: Record<string, string>;
-    };
+    documents?: GlobPattern;
+    saveConfig?: string;
+    saveSdl?: string;
+    middleware?: string;
+    cache?: Partial<CacheConfig>;
 }
-declare const _default: _nuxt_schema.NuxtModule<ModuleOptions, ModuleOptions, false>;
+declare const _default: _nuxt_schema.NuxtModule<NuxtGraphQLModuleOptions, NuxtGraphQLModuleOptions, false>;
 
 export { _default as default };
-export type { ModuleOptions };
+export type { NuxtGraphQLModuleOptions };

package/dist/module.json

@@ -1,7 +1,7 @@
 {
   "name": "@lewebsimple/nuxt-graphql",
   "configKey": "graphql",
-  "version": "0.2.2",
+  "version": "0.3.0",
   "builder": {
     "@nuxt/module-builder": "1.0.2",
     "unbuild": "3.6.1"