@lewebsimple/nuxt-graphql 0.2.1 → 0.2.2

package/README.md

@@ -5,80 +5,110 @@
 [![License][license-src]][license-href]
 [![Nuxt][nuxt-src]][nuxt-href]
 
-Opinionated Nuxt module for using GraphQL Yoga with graphql-request / graphql-sse.
+Opinionated Nuxt module that ships a stitched GraphQL Yoga server, typed GraphQL Codegen, and client/server composables powered by graphql-request and graphql-sse.
 
 - ✨ [Release Notes](/CHANGELOG.md)
 - 🏀 [Online playground](https://stackblitz.com/github/lewebsimple/nuxt-graphql?file=playground%2Fapp.vue)
 
 ## Features
-- 🧘‍♂️ GraphQL Yoga server handler with user-provided schema / context
-- 📄 Auto-import GraphQL documents from `**/*.gql` (configurable)
-- 🧩 Type-safe composables to call operations by name, i.e. `useGraphQLQuery("Hello")`
-- 🧵 Optional stitching of local schema with remote schemas (custom headers), with stitched SDL emitted to `server/graphql/schema.graphql`
 
-## Quick Setup
+- 🧘‍♂️ 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.
+
+## Quick start
 
 Install the module to your Nuxt application with one command:
 
 ```bash
-npx nuxi module add @lewebsimple/nuxt-graphql
+pnpx nuxi module add @lewebsimple/nuxt-graphql
 ```
 
-Optionnally adjust options in your Nuxt config. The defaults shown below:
+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:
 
 ```ts
 // nuxt.config.ts
 export default defineNuxtConfig({
   modules: ["@lewebsimple/nuxt-graphql"],
   graphql: {
-    // Codegen controls document scanning and outputs
+    // Optional: path to your GraphQL context factory
+    // Defaults to src/runtime/server/lib/default-context.ts if omitted
+    context: "server/graphql/context.ts",
+    schemas: {
+      local: { type: "local", path: "server/graphql/schema.ts" },
+      swapi: {
+        type: "remote",
+        url: "https://swapi-graphql.netlify.app/.netlify/functions/index",
+        middleware: "server/graphql/swapi-middleware.ts",
+      },
+    },
     codegen: {
-      enabled: true,
-      pattern: "**/*.gql", // scan .gql files across layers
-      schemaOutput: "server/graphql/schema.graphql", // saved SDL
+      documents: "**/*.gql", // only named operations allowed
+      saveSchema: "server/graphql/schema.graphql",
     },
-  },
-});
-```
-
-Define your GraphQL schema in `server/graphql/schema.ts`:
-
-```ts
-import { createSchema } from "graphql-yoga";
-import type { GraphQLContext } from "./context";
-
-export const schema = createSchema<GraphQLContext>({
-  typeDefs: /* GraphQL */ `
-      type Query {
-        hello: String!
-      }
-    `,
-  resolvers: {
-    Query: {
-      hello: () => "Hello world!",
+    client: {
+      cache: { enabled: true, ttl: 60_000, storage: "memory" },
+      headers: {},
     },
   },
 });
 ```
 
-Optionnally define your GraphQL context in `server/graphql/context.ts`:
+Define context (optional) in `server/graphql/context.ts`:
 
 ```ts
 import type { H3Event } from "h3";
 
-export async function createContext(_event: H3Event) {
-  return {
-    foo: "bar",
-  };
+export async function createContext(event: H3Event) {
+  return { event, user: event.context.user };
 }
+```
+
+Write named operations in `.gql` files and use the auto-generated composables by operation name:
 
-export type GraphQLContext = Awaited<ReturnType<typeof createContext>>;
+```ts
+const { data, pending, error } = useGraphQLQuery("Hello", { name: "world" });
+const { mutate } = useGraphQLMutation("Ping");
+const { data: time } = useGraphQLSubscription("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.
 
+Optional: add a remote middleware at `server/graphql/swapi-middleware.ts` to adjust headers or log activity for stitched sources:
+
+```ts
+export default {
+  async onRequest({ fetchOptions }) {
+    return {
+      ...fetchOptions,
+      headers: {
+        ...fetchOptions.headers,
+        "x-swapi-api-key": process.env.SWAPI_TOKEN ?? "",
+      },
+    };
+  },
+  async onResponse({ operationName }) {
+    console.log(`[SWAPI] completed ${operationName ?? "unknown"}`);
+  },
+} satisfies RemoteMiddleware
+```
+
+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.
+
+## Development notes
+
+- 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
 
 <details>

package/dist/module.d.mts

@@ -9,6 +9,7 @@ type RemoteSchema = {
     type: "remote";
     url: string;
     headers?: Record<string, string>;
+    middleware?: string;
 };
 type SchemaDefinition = LocalSchema | RemoteSchema;
 

package/dist/module.json

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

package/dist/module.mjs

@@ -185,7 +185,7 @@ function formatDefinitions(defs) {
   };
   return defs.map((def) => `${colorOf(def)}${def.name}${reset}`).join(`${dim} / ${reset}`);
 }
-function writeRegistryModule(registryPath, { operationsByType }) {
+function writeRegistryModule({ registryPath, operationsByType }) {
   const queries = operationsByType.query.map((o) => o.name);
   const mutations = operationsByType.mutation.map((o) => o.name);
   const subscriptions = operationsByType.subscription.map((o) => o.name);
@@ -250,10 +250,7 @@ function writeRegistryModule(registryPath, { operationsByType }) {
   return writeFileIfChanged(registryPath, content.join("\n") + "\n");
 }
 
-const schemaHeader = "/* GraphQL */";
-const escapeSDL = (sdl) => sdl.replace(/`/g, "\\`");
-const serializeSDL = (sdl) => `${schemaHeader} \`${escapeSDL(sdl)}\``;
-function writeLocalSchemaModule(localPath, modulePath) {
+function writeLocalSchemaModule({ localPath, modulePath }) {
   if (!existsSync(localPath)) {
     throw new Error(`Local schema file not found at path: ${localPath}`);
   }
@@ -262,7 +259,7 @@ function writeLocalSchemaModule(localPath, modulePath) {
   ].join("\n");
   return writeFileIfChanged(modulePath, content);
 }
-async function writeRemoteSchemaSdl({ url, headers }, sdlPath) {
+async function writeRemoteSchemaSdl({ schemaDef: { url, headers }, sdlPath }) {
   const response = await fetch(url, {
     method: "POST",
     headers: { "Content-Type": "application/json", ...headers },
@@ -274,28 +271,42 @@ async function writeRemoteSchemaSdl({ url, headers }, sdlPath) {
   }
   const schema = buildClientSchema(json.data);
   const sdl = printSchema(schema);
-  const content = [`export const sdl = ${serializeSDL(sdl)};`, ""].join("\n");
+  const content = `export const sdl = /* GraphQL */ \`${sdl.replace(/`/g, "\\`")}\`;`;
   return writeFileIfChanged(sdlPath, content);
 }
-function writeRemoteSchemaModule({ url, headers }, remoteSdlPath, modulePath) {
+function writeRemoteSchemaModule({ name, schemaDef: { url, headers }, sdlPath, modulePath, middlewarePath }) {
   const headerSource = headers && Object.keys(headers).length > 0 ? JSON.stringify(headers, null, 2) : "{}";
+  const middlewareImport = middlewarePath ? `import middleware from ${JSON.stringify(toImportPath(modulePath, middlewarePath))};` : "";
   const content = [
     `import { buildSchema, print } from "graphql";`,
     `import type { Executor } from "@graphql-tools/utils";`,
     `import type { SubschemaConfig } from "@graphql-tools/delegate";`,
-    `import { sdl } from ${JSON.stringify(toImportPath(modulePath, remoteSdlPath))};`,
+    `import { sdl } from ${JSON.stringify(toImportPath(modulePath, sdlPath))};`,
+    middlewareImport,
     ``,
     `const endpoint = ${JSON.stringify(url)};`,
     `const headers = ${headerSource} as Record<string, string>;`,
+    `const remoteName = ${JSON.stringify(name)};`,
+    `const mw = (typeof middleware === 'object' && middleware) || {};`,
     ``,
-    `const executor: Executor = async ({ document, variables }) => {`,
+    `const executor: Executor = async ({ document, variables, context, operationName }) => {`,
     `  const query = typeof document === "string" ? document : print(document);`,
-    `  const response = await fetch(endpoint, {`,
+    `  let fetchOptions = {`,
     `    method: "POST",`,
     `    headers: { "Content-Type": "application/json", ...headers },`,
     `    body: JSON.stringify({ query, variables }),`,
-    `  });`,
-    ``,
+    `  };`,
+    `  const mwContext = { remoteName, operationName, context, fetchOptions };`,
+    `  if (typeof mw.onRequest === "function") {`,
+    `    const maybeOverride = await mw.onRequest(mwContext);`,
+    `    if (maybeOverride && typeof maybeOverride === "object") {`,
+    `      fetchOptions = maybeOverride;`,
+    `    }`,
+    `  }`,
+    `  const response = await fetch(endpoint, fetchOptions);`,
+    `  if (typeof mw.onResponse === "function") {`,
+    `    await mw.onResponse({ ...mwContext, response });`,
+    `  }`,
     `  return response.json();`,
     `};`,
     ``,
@@ -307,7 +318,7 @@ function writeRemoteSchemaModule({ url, headers }, remoteSdlPath, modulePath) {
   ].join("\n");
   return writeFileIfChanged(modulePath, content);
 }
-function writeStitchedSchemaModule(schemaNames, modulePath) {
+function writeStitchedSchemaModule({ schemaNames, modulePath }) {
   const schemas = schemaNames.map((name) => ({
     path: `./schemas/${name}`,
     ref: `${name}Schema`
@@ -351,44 +362,50 @@ const module$1 = defineNuxtModule({
   async setup(options, nuxt) {
     const { resolve } = createResolver(import.meta.url);
     const layerRootDirs = getLayerDirectories(nuxt).map(({ root }) => root);
+    const middlewarePath = resolve("./runtime/server/utils/remote-middleware");
     const stitchedPath = join(nuxt.options.buildDir, "graphql/schema.ts");
     const sdlPath = join(nuxt.options.rootDir, options.codegen?.saveSchema || ".nuxt/graphql/schema.graphql");
     nuxt.options.alias ||= {};
-    if (!Object.keys(options.schemas || {}).length) {
-      throw new Error("No GraphQL schemas configured. Please set 'graphql.schemas' with at least one local or remote schema.");
-    }
     async function setupContextSchemas() {
       let contextPath;
       if (options.context) {
         contextPath = await findSingleFile(layerRootDirs, options.context, true);
         logger.info(`Using GraphQL context from ${cyan}${relative(nuxt.options.rootDir, contextPath)}${reset}`);
       } else {
-        contextPath = resolve("./runtime/server/graphql/context");
+        contextPath = resolve("./runtime/server/lib/default-context.ts");
         logger.info(`Using default GraphQL context`);
       }
       const schemasPath = {};
+      const middlewaresPath = {};
       for (const [name, schemaDef] of Object.entries(options.schemas)) {
         schemasPath[name] = join(nuxt.options.buildDir, `graphql/schemas/${name}.ts`);
         if (schemaDef.type === "local") {
           const localPath = await findSingleFile(layerRootDirs, schemaDef.path, true);
-          writeLocalSchemaModule(localPath, schemasPath[name]);
+          writeLocalSchemaModule({ localPath, modulePath: schemasPath[name] });
           logger.info(`Local GraphQL schema "${blue}${name}${reset}" loaded from ${cyan}${relative(nuxt.options.rootDir, localPath)}${reset}`);
         } else if (schemaDef.type === "remote") {
-          const remoteSdlPath = join(nuxt.options.buildDir, `graphql/schemas/${name}-sdl.ts`);
-          await writeRemoteSchemaSdl(schemaDef, remoteSdlPath);
-          writeRemoteSchemaModule(schemaDef, remoteSdlPath, schemasPath[name]);
+          const sdlPath2 = join(nuxt.options.buildDir, `graphql/schemas/${name}-sdl.ts`);
+          if (schemaDef.middleware) {
+            middlewaresPath[name] = await findSingleFile(layerRootDirs, schemaDef.middleware, true);
+          }
+          await writeRemoteSchemaSdl({ schemaDef, sdlPath: sdlPath2 });
+          writeRemoteSchemaModule({ name, schemaDef, sdlPath: sdlPath2, modulePath: schemasPath[name], middlewarePath: middlewaresPath[name] });
           logger.info(`Remote GraphQL schema "${magenta}${name}${reset}" loaded from ${cyan}${schemaDef.url}${reset}`);
         } else {
           throw new Error(`Unknown schema type for schema '${name}'`);
         }
       }
-      writeStitchedSchemaModule(Object.keys(options.schemas), stitchedPath);
+      writeStitchedSchemaModule({ schemaNames: Object.keys(options.schemas), modulePath: stitchedPath });
       nuxt.hook("nitro:config", (config) => {
         config.alias ||= {};
         config.alias["#graphql/context"] = contextPath;
+        config.alias["#graphql/middleware"] = middlewarePath;
         for (const name of Object.keys(options.schemas)) {
           config.alias[`#graphql/schemas/${name}`] = schemasPath[name];
         }
+        for (const name of Object.keys(middlewaresPath)) {
+          config.alias[`#graphql/middlewares/${name}`] = middlewaresPath[name];
+        }
         config.alias["#graphql/schema"] = stitchedPath;
       });
     }
@@ -404,12 +421,12 @@ const module$1 = defineNuxtModule({
           const documentsPattern = options.codegen?.documents ?? "**/*.gql";
           const documents = await findMultipleFiles(layerRootDirs, documentsPattern);
           await runCodegen({ schema: sdlPath, documents, operationsPath, zodPath, scalars: options.codegen?.scalars });
-          const analysis = analyzeDocuments(documents);
-          analysis.byFile.forEach((defs, path) => {
+          const { byFile, operationsByType } = analyzeDocuments(documents);
+          byFile.forEach((defs, path) => {
             const relativePath = relative(nuxt.options.rootDir, path);
             logger.info(`${cyan}${relativePath}${reset} [${formatDefinitions(defs)}]`);
           });
-          writeRegistryModule(registryPath, analysis);
+          writeRegistryModule({ registryPath, operationsByType });
           const config = {
             schema: relative(nuxt.options.rootDir, sdlPath),
             documents: documentsPattern

package/dist/runtime/server/api/graphql-handler.js

@@ -1,9 +1,10 @@
 import { defineEventHandler, toWebRequest, sendWebResponse, createError } from "h3";
 import { getYoga } from "../lib/create-yoga.js";
+import { createContext } from "#graphql/context";
 export default defineEventHandler(async (event) => {
   try {
     const request = toWebRequest(event);
-    const context = {};
+    const context = await createContext(event);
     const response = await getYoga().handleRequest(request, context);
     return sendWebResponse(event, response);
   } catch (error) {

package/dist/runtime/server/utils/remote-middleware.d.ts

@@ -0,0 +1,18 @@
+import type { GraphQLContext } from "#graphql/context";
+type Awaitable<T> = T | Promise<T>;
+export type RemoteMiddlewareContext = {
+    remoteName: string;
+    operationName?: string | null;
+    context: GraphQLContext;
+};
+export type RemoteMiddlewareRequestContext = RemoteMiddlewareContext & {
+    fetchOptions: RequestInit;
+};
+export type RemoteMiddlewareResponseContext = RemoteMiddlewareRequestContext & {
+    response: Response;
+};
+export type RemoteMiddleware = {
+    onRequest?: (context: RemoteMiddlewareRequestContext) => Awaitable<RequestInit | undefined>;
+    onResponse?: (context: RemoteMiddlewareResponseContext) => Awaitable<void>;
+};
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lewebsimple/nuxt-graphql",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "Opinionated Nuxt module for using GraphQL",
   "repository": "lewebsimple/nuxt-graphql",
   "license": "MIT",