@lewebsimple/nuxt-graphql 0.2.0 → 0.2.2

package/README.md

@@ -5,79 +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")`
 
-## 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

@@ -1,18 +1,32 @@
 import * as _nuxt_schema from '@nuxt/schema';
 import { GraphQLCacheConfig } from '../dist/runtime/app/utils/graphql-cache.js';
-import { CodegenConfig } from '@graphql-codegen/cli';
 
-interface ModuleOptions {
+type LocalSchema = {
+    type: "local";
+    path: string;
+};
+type RemoteSchema = {
+    type: "remote";
+    url: string;
     headers?: Record<string, string>;
-    cache?: Partial<GraphQLCacheConfig>;
+    middleware?: string;
+};
+type SchemaDefinition = LocalSchema | RemoteSchema;
+
+interface ModuleOptions {
+    context?: string;
+    schemas: Record<string, SchemaDefinition>;
     codegen?: {
-        pattern?: string;
-        schemaOutput?: string;
+        documents?: string;
+        saveSchema?: string;
         scalars?: Record<string, string | {
             input: string;
             output: string;
         }>;
-        generates?: CodegenConfig["generates"];
+    };
+    client?: {
+        cache?: Partial<GraphQLCacheConfig>;
+        headers?: Record<string, string>;
     };
 }
 declare const _default: _nuxt_schema.NuxtModule<ModuleOptions, ModuleOptions, false>;

package/dist/module.json

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

package/dist/module.mjs

@@ -1,9 +1,9 @@
-import { useLogger, defineNuxtModule, createResolver, getLayerDirectories, addServerHandler, addImportsDir, addServerImportsDir, addPlugin } from '@nuxt/kit';
+import { useLogger, defineNuxtModule, createResolver, getLayerDirectories, addServerHandler, addPlugin, addImportsDir, addServerImportsDir } from '@nuxt/kit';
+import { join, parse, relative, dirname } from 'node:path';
 import { existsSync, readFileSync, mkdirSync, writeFileSync } from 'node:fs';
-import { join, dirname, relative } from 'node:path';
 import { glob } from 'tinyglobby';
 import { generate } from '@graphql-codegen/cli';
-import { parse, Kind } from 'graphql';
+import { parse as parse$1, Kind, getIntrospectionQuery, buildClientSchema, printSchema } from 'graphql';
 import { GRAPHQL_ENDPOINT } from '../dist/runtime/server/lib/constants.js';
 
 const logger = useLogger("@lewebsimple/nuxt-graphql");
@@ -44,8 +44,16 @@ function writeFileIfChanged(path, content) {
   writeFileSync(path, content, "utf-8");
   return true;
 }
+function toImportPath(from, to) {
+  const { dir, name } = parse(to);
+  let importPath = relative(dirname(from), join(dir, name));
+  if (!importPath.startsWith(".")) {
+    importPath = "./" + importPath;
+  }
+  return importPath;
+}
 
-async function loadGraphQLSchema(schemaPath) {
+async function loadSchemaSdl(schemaPath) {
   const { createJiti } = await import('jiti');
   const jiti = createJiti(import.meta.url, { interopDefault: true });
   const module = await jiti.import(schemaPath);
@@ -55,7 +63,67 @@ async function loadGraphQLSchema(schemaPath) {
   const { printSchema, lexicographicSortSchema } = await import('graphql');
   return printSchema(lexicographicSortSchema(module.schema));
 }
-function analyzeGraphQLDocuments(docs) {
+async function runCodegen({ schema, documents, operationsPath, zodPath, scalars }) {
+  const generates = {
+    [operationsPath]: {
+      schema,
+      documents,
+      plugins: ["typescript", "typescript-operations", "typed-document-node"],
+      config: {
+        useTypeImports: true,
+        enumsAsTypes: true,
+        skipTypename: true,
+        documentVariableSuffix: "Document",
+        documentMode: "documentNode",
+        strictScalars: true,
+        defaultScalarType: "never",
+        scalars
+      }
+    }
+  };
+  if (zodPath) {
+    const zodScalars = {};
+    if (scalars) {
+      for (const [name, config] of Object.entries(scalars)) {
+        const inputType = typeof config === "string" ? config : config.input;
+        switch (inputType) {
+          case "Date":
+            zodScalars[name] = "z.coerce.date()";
+            break;
+          case "number":
+            zodScalars[name] = "z.coerce.number()";
+            break;
+          case "boolean":
+            zodScalars[name] = "z.coerce.boolean()";
+            break;
+          default:
+            zodScalars[name] = "z.string()";
+        }
+      }
+    }
+    generates[zodPath] = {
+      schema,
+      documents,
+      plugins: ["typescript-validation-schema"],
+      config: {
+        schema: "zodv4",
+        importFrom: "#graphql/operations",
+        useTypeImports: true,
+        directives: {
+          constraint: {
+            minLength: "min",
+            maxLength: "max",
+            pattern: "regex"
+          }
+        },
+        scalarSchemas: zodScalars
+      }
+    };
+  }
+  await generate({ generates, silent: true, errorsOnly: true }, true);
+}
+function analyzeDocuments(documents) {
+  const docs = documents.map((path) => ({ path, content: readFileSync(path, "utf-8") }));
   const byFile = /* @__PURE__ */ new Map();
   const operationsByType = {
     query: [],
@@ -65,7 +133,7 @@ function analyzeGraphQLDocuments(docs) {
   const operationNameToFile = /* @__PURE__ */ new Map();
   const fragmentNameToFile = /* @__PURE__ */ new Map();
   for (const doc of docs) {
-    const ast = parse(doc.content);
+    const ast = parse$1(doc.content);
     const defs = [];
     for (const def of ast.definitions) {
       if (def.kind === Kind.FRAGMENT_DEFINITION) {
@@ -102,11 +170,26 @@ function analyzeGraphQLDocuments(docs) {
   }
   return { byFile, operationsByType };
 }
-function generateRegistryByTypeSource(analysis) {
-  const queries = analysis.query.map((o) => o.name);
-  const mutations = analysis.mutation.map((o) => o.name);
-  const subscriptions = analysis.subscription.map((o) => o.name);
-  const lines = [
+function formatDefinitions(defs) {
+  if (defs.length === 0) return "";
+  const colorOf = (def) => {
+    if (def.kind === "fragment") return green;
+    switch (def.type) {
+      case "query":
+        return blue;
+      case "mutation":
+        return magenta;
+      case "subscription":
+        return yellow;
+    }
+  };
+  return defs.map((def) => `${colorOf(def)}${def.name}${reset}`).join(`${dim} / ${reset}`);
+}
+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);
+  const content = [
     `import type { TypedDocumentNode } from "@graphql-typed-document-node/core";`,
     `import * as ops from "#graphql/operations";`,
     ``,
@@ -114,138 +197,146 @@ function generateRegistryByTypeSource(analysis) {
     `type VariablesOf<T> = T extends { __apiType?: (variables: infer V) => infer _ } ? V : never;`
   ];
   if (queries.length > 0) {
-    lines.push(
+    content.push(
       ``,
+      `// Queries`,
       `export const queries = {`,
       ...queries.map((name) => `  ${name}: ops.${name}Document,`),
       `} as const;`
     );
   } else {
-    lines.push(``, `export const queries = {} as const;`);
+    content.push(``, `export const queries = {} as const;`);
   }
-  lines.push(
+  content.push(
+    ``,
     `export type QueryName = keyof typeof queries;`,
     `export type QueryResult<N extends QueryName> = ResultOf<(typeof queries)[N]>;`,
     `export type QueryVariables<N extends QueryName> = VariablesOf<(typeof queries)[N]>;`
   );
   if (mutations.length > 0) {
-    lines.push(
+    content.push(
       ``,
+      `// Mutations`,
       `export const mutations = {`,
       ...mutations.map((name) => `  ${name}: ops.${name}Document,`),
       `} as const;`
     );
   } else {
-    lines.push(``, `export const mutations = {} as const;`);
+    content.push(``, `export const mutations = {} as const;`);
   }
-  lines.push(
+  content.push(
+    ``,
     `export type MutationName = keyof typeof mutations;`,
     `export type MutationResult<N extends MutationName> = ResultOf<(typeof mutations)[N]>;`,
     `export type MutationVariables<N extends MutationName> = VariablesOf<(typeof mutations)[N]>;`
   );
   if (subscriptions.length > 0) {
-    lines.push(
+    content.push(
       ``,
+      `// Subscriptions`,
       `export const subscriptions = {`,
       ...subscriptions.map((name) => `  ${name}: ops.${name}Document,`),
       `} as const;`
     );
   } else {
-    lines.push(``, `export const subscriptions = {} as const;`);
+    content.push(``, `export const subscriptions = {} as const;`);
   }
-  lines.push(
+  content.push(
+    ``,
     `export type SubscriptionName = keyof typeof subscriptions;`,
     `export type SubscriptionResult<N extends SubscriptionName> = ResultOf<(typeof subscriptions)[N]>;`,
     `export type SubscriptionVariables<N extends SubscriptionName> = VariablesOf<(typeof subscriptions)[N]>;`
   );
-  return lines.join("\n") + "\n";
+  return writeFileIfChanged(registryPath, content.join("\n") + "\n");
 }
-function formatDefinitions(defs) {
-  if (defs.length === 0) return "";
-  const colorOf = (def) => {
-    if (def.kind === "fragment") return green;
-    switch (def.type) {
-      case "query":
-        return blue;
-      case "mutation":
-        return magenta;
-      case "subscription":
-        return yellow;
-    }
-  };
-  return defs.map((def) => `${colorOf(def)}${def.name}${reset}`).join(`${dim} / ${reset}`);
-}
-async function runCodegen(options) {
-  const { schema, documents, operationsFile, schemasFile, scalars, generates: customGenerates } = options;
-  if (documents.length === 0) {
-    logger.warn("No GraphQL documents found");
-    return;
-  }
-  const zodScalars = {};
-  if (scalars) {
-    for (const [name, config] of Object.entries(scalars)) {
-      const inputType = typeof config === "string" ? config : config.input;
-      switch (inputType) {
-        case "Date":
-          zodScalars[name] = "z.coerce.date()";
-          break;
-        case "number":
-          zodScalars[name] = "z.coerce.number()";
-          break;
-        case "boolean":
-          zodScalars[name] = "z.coerce.boolean()";
-          break;
-        default:
-          zodScalars[name] = "z.string()";
-      }
-    }
+
+function writeLocalSchemaModule({ localPath, modulePath }) {
+  if (!existsSync(localPath)) {
+    throw new Error(`Local schema file not found at path: ${localPath}`);
   }
-  try {
-    const generates = {
-      [operationsFile]: {
-        schema,
-        documents,
-        plugins: ["typescript", "typescript-operations", "typed-document-node"],
-        config: {
-          useTypeImports: true,
-          enumsAsTypes: true,
-          skipTypename: true,
-          documentVariableSuffix: "Document",
-          documentMode: "documentNode",
-          strictScalars: true,
-          defaultScalarType: "never",
-          scalars
-        }
-      }
-    };
-    if (schemasFile) {
-      generates[schemasFile] = {
-        schema,
-        documents,
-        plugins: ["typescript-validation-schema"],
-        config: {
-          schema: "zodv4",
-          importFrom: "#graphql/operations",
-          useTypeImports: true,
-          directives: {
-            constraint: {
-              minLength: "min",
-              maxLength: "max",
-              pattern: "regex"
-            }
-          },
-          scalarSchemas: zodScalars
-        }
-      };
-      if (customGenerates) {
-        Object.assign(generates, customGenerates);
-      }
-    }
-    await generate({ generates, silent: true, errorsOnly: true }, true);
-    logger.success(`Generated types for ${documents.length} document(s)`);
-  } catch (error) {
-    logger.error("GraphQL codegen failed:", error instanceof Error ? error.message : error);
+  const content = [
+    `export { schema } from ${JSON.stringify(toImportPath(modulePath, localPath))};`
+  ].join("\n");
+  return writeFileIfChanged(modulePath, content);
+}
+async function writeRemoteSchemaSdl({ schemaDef: { url, headers }, sdlPath }) {
+  const response = await fetch(url, {
+    method: "POST",
+    headers: { "Content-Type": "application/json", ...headers },
+    body: JSON.stringify({ query: getIntrospectionQuery() })
+  });
+  const json = await response.json();
+  if (json.errors) {
+    throw new Error(`Failed to fetch remote schema from ${url}: ${JSON.stringify(json.errors)}`);
   }
+  const schema = buildClientSchema(json.data);
+  const sdl = printSchema(schema);
+  const content = `export const sdl = /* GraphQL */ \`${sdl.replace(/`/g, "\\`")}\`;`;
+  return writeFileIfChanged(sdlPath, content);
+}
+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, 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, context, operationName }) => {`,
+    `  const query = typeof document === "string" ? document : print(document);`,
+    `  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();`,
+    `};`,
+    ``,
+    `export const schema: SubschemaConfig = {`,
+    `  schema: buildSchema(sdl),`,
+    `  executor,`,
+    `};`,
+    ``
+  ].join("\n");
+  return writeFileIfChanged(modulePath, content);
+}
+function writeStitchedSchemaModule({ schemaNames, modulePath }) {
+  const schemas = schemaNames.map((name) => ({
+    path: `./schemas/${name}`,
+    ref: `${name}Schema`
+  }));
+  const content = [
+    `import { stitchSchemas } from "@graphql-tools/stitch";`,
+    `import type { GraphQLSchema } from "graphql";`,
+    `import type { SubschemaConfig } from "@graphql-tools/delegate";`,
+    ...schemas.map(({ path, ref }) => `import { schema as ${ref} } from ${JSON.stringify(path)};`),
+    ``,
+    `const subschemas: Array<GraphQLSchema | SubschemaConfig> = [`,
+    ...schemas.map(({ ref }) => `  ${ref},`),
+    `];`,
+    ``,
+    `export const schema = stitchSchemas({ subschemas });`,
+    ``
+  ].join("\n");
+  return writeFileIfChanged(modulePath, content);
 }
 
 const module$1 = defineNuxtModule({
@@ -254,102 +345,102 @@ const module$1 = defineNuxtModule({
     configKey: "graphql"
   },
   defaults: {
+    schemas: {},
     codegen: {
-      pattern: "**/*.gql",
-      schemaOutput: "server/graphql/schema.graphql"
+      documents: "**/*.gql",
+      saveSchema: "server/graphql/schema.graphql"
+    },
+    client: {
+      headers: {},
+      cache: {
+        enabled: false,
+        ttl: 6e4,
+        storage: "memory"
+      }
     }
   },
   async setup(options, nuxt) {
     const { resolve } = createResolver(import.meta.url);
-    const { rootDir, serverDir } = nuxt.options;
-    const layerDirs = [
-      ...getLayerDirectories(nuxt),
-      { root: rootDir, server: serverDir.replace(rootDir, `${rootDir}/playground`) }
-    ];
-    const layerServerDirs = layerDirs.map(({ server }) => server);
-    const layerRootDirs = layerDirs.map(({ root }) => root);
-    const schemaPath = await findSingleFile(layerServerDirs, "graphql/schema.{ts,mjs}", true);
-    const contextPath = await findSingleFile(layerServerDirs, "graphql/context.{ts,mjs}") || resolve("./runtime/server/graphql/default-context.ts");
-    const codegenPattern = options.codegen?.pattern ?? "**/*.gql";
-    const graphqlrcFile = join(rootDir, ".graphqlrc");
-    const operationsFile = join(nuxt.options.buildDir, "graphql/operations.ts");
-    const registryFile = join(nuxt.options.buildDir, "graphql/registry.ts");
-    const zodSchemasFile = join(nuxt.options.buildDir, "graphql/zod.ts");
-    const schemaOutput = options.codegen?.schemaOutput ?? "server/graphql/schema.graphql";
-    if (schemaOutput && !schemaOutput.endsWith(".graphql")) {
-      logger.warn(`Schema output '${schemaOutput}' should have .graphql extension.`);
-    }
-    const schemaFile = join(rootDir, schemaOutput);
-    const setupAliases = () => {
+    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 ||= {};
+    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/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, 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 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({ schemaNames: Object.keys(options.schemas), modulePath: stitchedPath });
       nuxt.hook("nitro:config", (config) => {
         config.alias ||= {};
-        config.alias["#graphql/schema"] = schemaPath;
         config.alias["#graphql/context"] = contextPath;
-      });
-      nuxt.options.alias["#graphql/operations"] = operationsFile;
-      nuxt.options.alias["#graphql/registry"] = registryFile;
-      nuxt.options.alias["#graphql/zod"] = zodSchemasFile;
-    };
-    const setupHandler = () => {
-      addServerHandler({ route: GRAPHQL_ENDPOINT, handler: resolve("./runtime/server/api/graphql-handler") });
-      nuxt.hook("listen", (_, { url }) => {
-        logger.success(`GraphQL Yoga ready at ${cyan}${url.replace(/\/$/, "")}${GRAPHQL_ENDPOINT}${reset}`);
-      });
-    };
-    const setupRuntimeConfig = () => {
-      nuxt.options.runtimeConfig.public.graphql = {
-        endpoint: GRAPHQL_ENDPOINT,
-        headers: options.headers || {},
-        cache: {
-          enabled: options.cache?.enabled ?? false,
-          ttl: options.cache?.ttl ?? 6e4,
-          storage: options.cache?.storage ?? "memory"
+        config.alias["#graphql/middleware"] = middlewarePath;
+        for (const name of Object.keys(options.schemas)) {
+          config.alias[`#graphql/schemas/${name}`] = schemasPath[name];
         }
-      };
-    };
-    const setupCodegen = () => {
-      const generate = async () => {
-        const [schema, documents] = await Promise.all([
-          loadGraphQLSchema(schemaPath),
-          findMultipleFiles(layerRootDirs, codegenPattern)
-        ]);
-        const docs = documents.map((document) => ({ path: document, content: readFileSync(document, "utf-8") }));
-        const analysis = analyzeGraphQLDocuments(docs);
-        for (const doc of docs) {
-          const relativePath = doc.path.startsWith(rootDir) ? doc.path.slice(rootDir.length + 1) : doc.path;
-          const defs = analysis.byFile.get(doc.path) ?? [];
-          logger.info(`${cyan}${relativePath}${reset} [${formatDefinitions(defs)}]`);
-        }
-        await runCodegen({
-          schema,
-          documents,
-          operationsFile,
-          schemasFile: zodSchemasFile,
-          scalars: options.codegen?.scalars,
-          generates: options.codegen?.generates
-        });
-        if (writeFileIfChanged(schemaFile, schema)) {
-          logger.info(`GraphQL schema saved to ${cyan}${schemaOutput}${reset}`);
+        for (const name of Object.keys(middlewaresPath)) {
+          config.alias[`#graphql/middlewares/${name}`] = middlewaresPath[name];
         }
-        const graphqlrc = {
-          schema: relative(rootDir, schemaFile),
-          documents: codegenPattern
-        };
-        if (options.codegen?.scalars) {
-          graphqlrc.scalars = options.codegen.scalars;
-        }
-        if (writeFileIfChanged(graphqlrcFile, JSON.stringify(graphqlrc, null, 2))) {
-          logger.info(`GraphQL config saved to ${cyan}.graphqlrc${reset}`);
-        }
-        if (writeFileIfChanged(registryFile, generateRegistryByTypeSource(analysis.operationsByType))) {
-          logger.info(`GraphQL registry saved to ${cyan}${relative(rootDir, registryFile)}${reset}`);
+        config.alias["#graphql/schema"] = stitchedPath;
+      });
+    }
+    async function setupCodegen() {
+      const configPath = join(nuxt.options.rootDir, ".graphqlrc");
+      const operationsPath = nuxt.options.alias["#graphql/operations"] = join(nuxt.options.buildDir, "graphql/operations.ts");
+      const registryPath = nuxt.options.alias["#graphql/registry"] = join(nuxt.options.buildDir, "graphql/registry.ts");
+      const zodPath = nuxt.options.alias["#graphql/zod"] = join(nuxt.options.buildDir, "graphql/zod.ts");
+      async function generate() {
+        try {
+          const sdlContent = await loadSchemaSdl(stitchedPath);
+          writeFileIfChanged(sdlPath, sdlContent);
+          const documentsPattern = options.codegen?.documents ?? "**/*.gql";
+          const documents = await findMultipleFiles(layerRootDirs, documentsPattern);
+          await runCodegen({ schema: sdlPath, documents, operationsPath, zodPath, scalars: options.codegen?.scalars });
+          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, operationsByType });
+          const config = {
+            schema: relative(nuxt.options.rootDir, sdlPath),
+            documents: documentsPattern
+          };
+          writeFileIfChanged(configPath, JSON.stringify(config, null, 2));
+        } catch (error) {
+          logger.warn(`GraphQL codegen failed: ${error.message}`);
         }
-      };
+      }
       nuxt.hook("prepare:types", async ({ references }) => {
         await generate();
-        if (existsSync(operationsFile)) references.push({ path: operationsFile });
-        if (existsSync(registryFile)) references.push({ path: registryFile });
-        if (existsSync(zodSchemasFile)) references.push({ path: zodSchemasFile });
+        references.push({ path: operationsPath });
+        references.push({ path: registryPath });
+        references.push({ path: zodPath });
       });
       if (nuxt.options.dev) {
         nuxt.hook("builder:watch", async (event, path) => {
@@ -358,17 +449,31 @@ const module$1 = defineNuxtModule({
           }
         });
       }
-    };
-    const setupAppRuntime = () => {
+    }
+    function setupYogaHandler() {
+      addServerHandler({ route: GRAPHQL_ENDPOINT, handler: resolve("./runtime/server/api/graphql-handler") });
+      nuxt.hook("listen", (_, { url }) => {
+        logger.success(`GraphQL Yoga ready at ${cyan}${url.replace(/\/$/, "")}${GRAPHQL_ENDPOINT}${reset}`);
+      });
+    }
+    function setupClient() {
+      nuxt.options.runtimeConfig.public.graphql = {
+        endpoint: GRAPHQL_ENDPOINT,
+        headers: options.client?.headers || {},
+        cache: {
+          enabled: options.client?.cache?.enabled ?? false,
+          ttl: options.client?.cache?.ttl ?? 6e4,
+          storage: options.client?.cache?.storage ?? "memory"
+        }
+      };
+      addPlugin(resolve("./runtime/app/plugins/graphql"));
       addImportsDir(resolve("./runtime/app/composables"));
       addServerImportsDir(resolve("./runtime/server/utils"));
-      addPlugin(resolve("./runtime/app/plugins/graphql"));
-    };
-    setupAliases();
-    setupHandler();
-    setupRuntimeConfig();
-    setupCodegen();
-    setupAppRuntime();
+    }
+    await setupContextSchemas();
+    await setupCodegen();
+    setupYogaHandler();
+    setupClient();
   }
 });
 

package/dist/runtime/app/composables/useGraphQLMutation.d.ts

@@ -1,5 +1,4 @@
-import { type MutationName, type MutationResult, type MutationVariables } from "#graphql/registry";
-import type { IsEmptyObject } from "../../../helpers/is-empty-object.js";
+import { type MutationName, type MutationResult } from "#graphql/registry";
 /**
  * Client-side GraphQL mutation composable
  *
@@ -7,7 +6,7 @@ import type { IsEmptyObject } from "../../../helpers/is-empty-object.js";
  * @returns Object with mutate function and pending state
  */
 export declare function useGraphQLMutation<N extends MutationName>(operationName: N): {
-    mutate: (...args: IsEmptyObject<MutationVariables<N>> extends true ? [variables?: MutationVariables<N>, headers?: HeadersInit] : [variables: MutationVariables<N>, headers?: HeadersInit]) => Promise<{
+    mutate: (variables: MutationVariables<N>, headers?: HeadersInit | undefined) => Promise<{
         data: MutationResult<N> | null;
         error: Error | null;
     }>;

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

@@ -1,5 +1,4 @@
 import { defineEventHandler, toWebRequest, sendWebResponse, createError } from "h3";
-import { logger } from "../lib/logger.js";
 import { getYoga } from "../lib/create-yoga.js";
 import { createContext } from "#graphql/context";
 export default defineEventHandler(async (event) => {
@@ -10,7 +9,7 @@ export default defineEventHandler(async (event) => {
     return sendWebResponse(event, response);
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
-    logger.error("GraphQL Server Error:", message);
+    console.error("GraphQL Server Error:", message);
     throw createError({ statusCode: 500, message: "GraphQL server 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/dist/runtime/server/utils/useServerGraphQLMutation.d.ts

@@ -1,6 +1,5 @@
 import type { H3Event } from "h3";
-import { type MutationName, type MutationResult, type MutationVariables } from "#graphql/registry";
-import type { IsEmptyObject } from "../../../helpers/is-empty-object.js";
+import { type MutationName, type MutationResult } from "#graphql/registry";
 /**
  * Server-side GraphQL mutation composable
  *
@@ -9,7 +8,7 @@ import type { IsEmptyObject } from "../../../helpers/is-empty-object.js";
  * @returns Object with mutate function
  */
 export declare function useServerGraphQLMutation<N extends MutationName>(event: H3Event, operationName: N): Promise<{
-    mutate: (...args: IsEmptyObject<MutationVariables<N>> extends true ? [variables?: MutationVariables<N>, headers?: HeadersInit] : [variables: MutationVariables<N>, headers?: HeadersInit]) => Promise<{
+    mutate: (variables: MutationVariables<N>, headers?: HeadersInit | undefined) => Promise<{
         data: MutationResult<N> | null;
         error: Error | null;
     }>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lewebsimple/nuxt-graphql",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Opinionated Nuxt module for using GraphQL",
   "repository": "lewebsimple/nuxt-graphql",
   "license": "MIT",
@@ -39,6 +39,10 @@
     "@graphql-codegen/typed-document-node": "^6.1.5",
     "@graphql-codegen/typescript": "^5.0.7",
     "@graphql-codegen/typescript-operations": "^5.0.7",
+    "@graphql-tools/delegate": "^12.0.2",
+    "@graphql-tools/stitch": "^10.1.6",
+    "@graphql-tools/utils": "^10.11.0",
+    "@graphql-tools/wrap": "^11.1.2",
     "@graphql-typed-document-node/core": "^3.2.0",
     "@nuxt/kit": "^4.2.2",
     "graphql": "^16.12.0",
@@ -59,13 +63,13 @@
     "@nuxt/schema": "^4.2.2",
     "@nuxt/test-utils": "^3.22.0",
     "@types/node": "latest",
-    "@vitest/coverage-v8": "^4.0.16",
+    "@vitest/coverage-v8": "^3.2.4",
     "changelogen": "^0.6.2",
     "eslint": "^9.39.2",
     "nuxt": "^4.2.2",
     "typescript": "~5.9.3",
-    "vitest": "^4.0.16",
-    "vue-tsc": "^3.2.1"
+    "vitest": "^3.2.4",
+    "vue-tsc": "^3.2.2"
   },
   "publishConfig": {
     "access": "public"

package/dist/runtime/server/lib/logger.d.ts

@@ -1,2 +0,0 @@
-import { consola } from "consola";
-export declare const logger: consola.ConsolaInstance;

package/dist/runtime/server/lib/logger.js

@@ -1,2 +0,0 @@
-import { consola } from "consola";
-export const logger = consola.withTag("graphql");

package/dist/runtime/server/yoga-handler.d.ts

@@ -1 +0,0 @@
-export { default } from "./api/graphql-handler.js";

package/dist/runtime/server/yoga-handler.js

@@ -1 +0,0 @@
-export { default } from "./api/graphql-handler.js";