@lewebsimple/nuxt-graphql 0.1.6 → 0.1.8

package/README.md

@@ -12,6 +12,8 @@ Opinionated Nuxt module for using GraphQL Yoga with graphql-request / graphql-ss
 
 ## 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
 
@@ -21,6 +23,25 @@ Install the module to your Nuxt application with one command:
 npx nuxi module add @lewebsimple/nuxt-graphql
 ```
 
+Optionnally adjust options in your Nuxt config. The defaults shown below:
+
+```ts
+// nuxt.config.ts
+export default defineNuxtConfig({
+  modules: ["@lewebsimple/nuxt-graphql"],
+  graphql: {
+    // GraphQL HTTP endpoint served by Yoga
+    endpoint: "/api/graphql",
+    // Codegen controls document scanning and outputs
+    codegen: {
+      enabled: true,
+      pattern: "**/*.gql", // scan .gql files across layers
+      schemaOutput: "server/graphql/schema.graphql", // saved SDL
+    },
+  },
+});
+```
+
 Define your GraphQL schema in `server/graphql/schema.ts`:
 
 ```ts
@@ -41,7 +62,7 @@ export const schema = createSchema<GraphQLContext>({
 });
 ```
 
-Define your GraphQL context in `server/graphql/context.ts`:
+Optionnally define your GraphQL context in `server/graphql/context.ts`:
 
 ```ts
 import type { H3Event } from "h3";
@@ -57,6 +78,7 @@ export type GraphQLContext = Awaited<ReturnType<typeof createContext>>;
 
 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.
 
 ## Contribution
 

package/dist/module.d.mts

@@ -1,12 +1,14 @@
 import * as _nuxt_schema from '@nuxt/schema';
 
-interface GraphQLYogaConfig {
-    endpoint?: string;
-}
 interface ModuleOptions {
-    yoga?: GraphQLYogaConfig;
+    endpoint?: string;
+    codegen?: {
+        enabled?: boolean;
+        pattern?: string;
+        schemaOutput?: string;
+    };
 }
 declare const _default: _nuxt_schema.NuxtModule<ModuleOptions, ModuleOptions, false>;
 
 export { _default as default };
-export type { GraphQLYogaConfig, ModuleOptions };
+export type { ModuleOptions };

package/dist/module.json

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

package/dist/module.mjs

@@ -1,23 +1,213 @@
 import { useLogger, defineNuxtModule, createResolver, getLayerDirectories, addServerTemplate, addServerHandler, addImportsDir, addPlugin, addTypeTemplate } from '@nuxt/kit';
-import { existsSync, readFileSync } from 'node:fs';
-import { join } 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';
 
 const logger = useLogger("@lewebsimple/nuxt-graphql");
+const blue = "\x1B[34m";
 const cyan = "\x1B[36m";
+const dim = "\x1B[2m";
+const green = "\x1B[32m";
+const magenta = "\x1B[35m";
 const reset = "\x1B[0m";
+const yellow = "\x1B[33m";
 
-function findServerFile(layerDirs, relativePath, isRequired = false) {
-  const extensions = ["ts", "mjs"];
-  for (const dir of layerDirs) {
-    const candidates = extensions.map((ext) => join(dir.server, `${relativePath}.${ext}`));
-    const fullPath = candidates.find(existsSync);
-    if (fullPath) {
-      return fullPath;
+async function findSingleFile(dirs, pattern, isRequired = false) {
+  for (const dir of dirs) {
+    const fullPattern = join(dir, pattern);
+    const files = await glob(fullPattern, { absolute: true });
+    if (files.length > 0) {
+      return files[0];
     }
   }
   if (isRequired) {
-    throw new Error(`Could not find required server file ${cyan}${relativePath}.{${extensions.join(",")}}${reset} in the following layers:
-${layerDirs.map(({ server }) => server).join("\n")}`);
+    throw new Error(`File not found: ${cyan}${pattern}${reset} in directories:
+${dirs.join("\n")}`);
+  }
+}
+async function findMultipleFiles(dirs, pattern) {
+  const files = [];
+  for (const dir of dirs) {
+    const foundFiles = await glob(pattern, { cwd: dir, absolute: true });
+    files.push(...foundFiles);
+  }
+  return Array.from(new Set(files));
+}
+function writeFileIfChanged(path, content) {
+  if (existsSync(path) && readFileSync(path, "utf-8") === content) {
+    return false;
+  }
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, content, "utf-8");
+  return true;
+}
+
+function analyzeGraphQLDocuments(docs) {
+  const byFile = /* @__PURE__ */ new Map();
+  const operationsByType = {
+    query: [],
+    mutation: [],
+    subscription: []
+  };
+  const operationNameToFile = /* @__PURE__ */ new Map();
+  const fragmentNameToFile = /* @__PURE__ */ new Map();
+  for (const doc of docs) {
+    const ast = parse(doc.content);
+    const defs = [];
+    for (const def of ast.definitions) {
+      if (def.kind === Kind.FRAGMENT_DEFINITION) {
+        const name2 = def.name.value;
+        const prev2 = fragmentNameToFile.get(name2);
+        if (prev2) {
+          throw new Error(`Duplicate fragment name '${name2}' in:
+- ${prev2}
+- ${doc.path}`);
+        }
+        fragmentNameToFile.set(name2, doc.path);
+        defs.push({ kind: "fragment", name: name2 });
+        continue;
+      }
+      if (def.kind !== Kind.OPERATION_DEFINITION) continue;
+      const type = def.operation;
+      if (!["query", "mutation", "subscription"].includes(type)) continue;
+      const name = def.name?.value;
+      if (!name) {
+        throw new Error(`Unnamed ${type} operation in ${doc.path}`);
+      }
+      const prev = operationNameToFile.get(name);
+      if (prev) {
+        throw new Error(`Duplicate ${type} operation name '${name}' in:
+- ${prev}
+- ${doc.path}`);
+      }
+      operationNameToFile.set(name, doc.path);
+      const op = { kind: "operation", type, name };
+      defs.push(op);
+      operationsByType[type].push(op);
+    }
+    byFile.set(doc.path, defs);
+  }
+  return { byFile, operationsByType };
+}
+function generateRegistryByTypeSource(analysis) {
+  const q = analysis.query.map((o) => o.name);
+  const m = analysis.mutation.map((o) => o.name);
+  const s = analysis.subscription.map((o) => o.name);
+  const lines = [
+    `import type { TypedDocumentNode } from "@graphql-typed-document-node/core";`,
+    `import * as ops from "#graphql/operations";`,
+    ``,
+    `type ResultOf<T> = T extends { __apiType?: (variables: infer _) => infer R } ? R : never;`,
+    `type VariablesOf<T> = T extends { __apiType?: (variables: infer V) => infer _ } ? V : never;`
+  ];
+  if (q.length > 0) {
+    lines.push(
+      ``,
+      `export const queries = {`,
+      ...q.map((name) => `  ${name}: ops.${name}Document,`),
+      `} as const;`
+    );
+  } else {
+    lines.push(``, `export const queries = {} as const;`);
+  }
+  lines.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 (m.length > 0) {
+    lines.push(
+      ``,
+      `export const mutations = {`,
+      ...m.map((name) => `  ${name}: ops.${name}Document,`),
+      `} as const;`
+    );
+  } else {
+    lines.push(``, `export const mutations = {} as const;`);
+  }
+  lines.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 (s.length > 0) {
+    lines.push(
+      ``,
+      `export const subscriptions = {`,
+      ...s.map((name) => `  ${name}: ops.${name}Document,`),
+      `} as const;`
+    );
+  } else {
+    lines.push(``, `export const subscriptions = {} as const;`);
+  }
+  lines.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";
+}
+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 loadGraphQLSchema(schemaPath) {
+  const { createJiti } = await import('jiti');
+  const jiti = createJiti(import.meta.url, { interopDefault: true });
+  const module = await jiti.import(schemaPath);
+  if (!module.schema) {
+    throw new Error(`${schemaPath} must export a 'schema' variable`);
+  }
+  const { printSchema, lexicographicSortSchema } = await import('graphql');
+  return printSchema(lexicographicSortSchema(module.schema));
+}
+async function runCodegen(options) {
+  const { sdl, documents, operationsFile } = options;
+  if (documents.length === 0) {
+    logger.warn("No GraphQL documents found");
+    return;
+  }
+  try {
+    await generate(
+      {
+        schema: sdl,
+        documents,
+        generates: {
+          [operationsFile]: {
+            plugins: ["typescript", "typescript-operations", "typed-document-node"],
+            config: {
+              useTypeImports: true,
+              enumsAsTypes: true,
+              skipTypename: true,
+              documentVariableSuffix: "Document",
+              documentMode: "documentNode",
+              strictScalars: true,
+              defaultScalarType: "never"
+              // TODO: Make codegen config customizable, e.g. for custom scalars
+            }
+          }
+        },
+        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);
   }
 }
 
@@ -27,29 +217,85 @@ const module$1 = defineNuxtModule({
     configKey: "graphql"
   },
   defaults: {
-    yoga: {
-      endpoint: "/api/graphql"
+    endpoint: "/api/graphql",
+    codegen: {
+      enabled: true,
+      pattern: "**/*.gql",
+      schemaOutput: "server/graphql/schema.graphql"
     }
   },
   async setup(options, nuxt) {
     const { resolve } = createResolver(import.meta.url);
     const { rootDir, serverDir } = nuxt.options;
-    const layerDirs = [...getLayerDirectories(nuxt), { server: serverDir.replace(rootDir, `${rootDir}/playground`) }];
-    nuxt.hook("nitro:config", (nitroConfig) => {
-      nitroConfig.alias ||= {};
-      nitroConfig.alias["#graphql/schema"] = findServerFile(layerDirs, "graphql/schema", true);
-      nitroConfig.alias["#graphql/context"] = findServerFile(layerDirs, "graphql/context") || resolve("./runtime/server/default-context.ts");
+    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/default-context.ts");
+    nuxt.hook("nitro:config", (config) => {
+      config.alias ||= {};
+      config.alias["#graphql/schema"] = schemaPath;
+      config.alias["#graphql/context"] = contextPath;
     });
-    const endpoint = options.yoga?.endpoint ?? "/api/graphql";
+    const endpoint = options.endpoint ?? "/api/graphql";
     addServerTemplate({
       filename: "graphql/yoga-handler",
       getContents: () => readFileSync(resolve("./templates/yoga-handler.mjs"), "utf-8").replace("{{endpoint}}", endpoint)
     });
     addServerHandler({ route: endpoint, handler: "graphql/yoga-handler" });
-    nuxt.hook("listen", (_server, { url }) => {
-      logger.success(`GraphQL Yoga available at ${cyan}${url.replace(/\/$/, "") + endpoint}${reset}`);
+    nuxt.hook("listen", (_, { url }) => {
+      logger.success(`GraphQL Yoga ready at ${cyan}${url.replace(/\/$/, "")}${endpoint}${reset}`);
     });
     nuxt.options.runtimeConfig.public.graphql = { endpoint };
+    if (options.codegen?.enabled !== false) {
+      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 schemaOutput = options.codegen?.schemaOutput ?? "server/graphql/schema.graphql";
+      const schemaFile = join(rootDir, schemaOutput);
+      const generate = async () => {
+        const [sdl, 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({ sdl, documents, operationsFile });
+        if (writeFileIfChanged(schemaFile, sdl)) {
+          logger.info(`GraphQL schema saved to ${cyan}${schemaOutput}${reset}`);
+        }
+        const config = JSON.stringify({ schema: relative(rootDir, schemaFile), documents: codegenPattern }, null, 2);
+        if (writeFileIfChanged(graphqlrcFile, config)) {
+          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}`);
+        }
+      };
+      nuxt.hook("prepare:types", async ({ references }) => {
+        await generate();
+        if (existsSync(operationsFile)) references.push({ path: operationsFile });
+        if (existsSync(registryFile)) references.push({ path: registryFile });
+      });
+      if (nuxt.options.dev) {
+        nuxt.hook("builder:watch", async (event, path) => {
+          if (path.endsWith(".gql")) {
+            await generate();
+          }
+        });
+      }
+      nuxt.options.alias["#graphql/operations"] = operationsFile;
+      nuxt.options.alias["#graphql/registry"] = registryFile;
+    }
     addImportsDir(resolve("./runtime/composables"));
     addPlugin(resolve("./runtime/plugins/graphql"));
     addTypeTemplate({

package/dist/runtime/composables/useGraphQL.d.ts

@@ -1,4 +1,4 @@
-import type { RequestDocument, Variables } from "graphql-request";
+import type { TypedDocumentNode } from "@graphql-typed-document-node/core";
 export declare function useGraphQL(): {
-    request: <T>(document: RequestDocument, variables?: Variables) => any;
+    request: <TResult, TVariables extends Record<string, unknown> | undefined>(document: TypedDocumentNode<TResult, TVariables>, variables?: TVariables) => Promise<TResult>;
 };

package/dist/runtime/composables/useGraphQL.js

@@ -1,7 +1,8 @@
 import { useNuxtApp } from "#imports";
 export function useGraphQL() {
   const { $graphql } = useNuxtApp();
-  return {
-    request: (document, variables) => $graphql.request(document, variables)
-  };
+  async function request(document, variables) {
+    return $graphql.request({ document, variables });
+  }
+  return { request };
 }

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

@@ -0,0 +1,10 @@
+import { type Ref } from "vue";
+import { type MutationName, type MutationResult, type MutationVariables } from "#graphql/registry";
+type IsEmptyObject<T> = T extends Record<string, never> ? true : keyof T extends never ? true : false;
+export declare function useGraphQLMutation<N extends MutationName>(operationName: N): {
+    mutate: (...args: IsEmptyObject<MutationVariables<N>> extends true ? [variables?: MutationVariables<N>] : [variables: MutationVariables<N>]) => Promise<MutationResult<N>>;
+    data: Ref<MutationResult<N> | null, MutationResult<N> | null>;
+    error: Ref<Error | null, Error | null>;
+    pending: Ref<boolean, boolean>;
+};
+export {};

package/dist/runtime/composables/useGraphQLMutation.js

@@ -0,0 +1,25 @@
+import { ref } from "vue";
+import { useGraphQL } from "./useGraphQL.js";
+import { mutations } from "#graphql/registry";
+export function useGraphQLMutation(operationName) {
+  const document = mutations[operationName];
+  const { request } = useGraphQL();
+  const data = ref(null);
+  const error = ref(null);
+  const pending = ref(false);
+  async function mutate(...args) {
+    pending.value = true;
+    error.value = null;
+    try {
+      const result = await request(document, args[0]);
+      data.value = result;
+      return result;
+    } catch (e) {
+      error.value = e instanceof Error ? e : new Error(String(e));
+      throw e;
+    } finally {
+      pending.value = false;
+    }
+  }
+  return { mutate, data, error, pending };
+}

package/dist/runtime/composables/useGraphQLQuery.d.ts

@@ -0,0 +1,5 @@
+import type { AsyncData, AsyncDataOptions } from "#app";
+import { type QueryName, type QueryResult, type QueryVariables } from "#graphql/registry";
+type IsEmptyObject<T> = T extends Record<string, never> ? true : keyof T extends never ? true : false;
+export declare function useGraphQLQuery<N extends QueryName>(operationName: N, ...args: IsEmptyObject<QueryVariables<N>> extends true ? [variables?: QueryVariables<N>, opts?: AsyncDataOptions<QueryResult<N>>] : [variables: QueryVariables<N>, opts?: AsyncDataOptions<QueryResult<N>>]): AsyncData<QueryResult<N>, Error | null>;
+export {};

package/dist/runtime/composables/useGraphQLQuery.js

@@ -0,0 +1,11 @@
+import { useAsyncData } from "#imports";
+import { hash } from "ohash";
+import { useGraphQL } from "./useGraphQL.js";
+import { queries } from "#graphql/registry";
+export function useGraphQLQuery(operationName, ...args) {
+  const document = queries[operationName];
+  const [variables, opts] = args;
+  const { request } = useGraphQL();
+  const key = `gql:q:${operationName}:${hash(variables ?? {})}`;
+  return useAsyncData(key, () => request(document, variables), opts);
+}

package/dist/types.d.mts

@@ -1,3 +1,3 @@
 export { default } from './module.mjs'
 
-export { type GraphQLYogaConfig, type ModuleOptions } from './module.mjs'
+export { type ModuleOptions } from './module.mjs'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lewebsimple/nuxt-graphql",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "description": "Opinionated Nuxt module for using GraphQL",
   "repository": "lewebsimple/nuxt-graphql",
   "license": "MIT",
@@ -27,17 +27,25 @@
     "dev": "npm run dev:prepare && nuxi dev playground",
     "dev:build": "nuxi build playground",
     "dev:prepare": "nuxt-module-build build --stub && nuxt-module-build prepare && nuxi prepare playground",
-    "release": "npm run lint && npm run test && npm run prepack && changelogen --release && npm publish && git push --follow-tags",
+    "release": "npm run lint && npm run test && npm run prepack && changelogen --release --push && npm publish",
     "lint": "eslint .",
     "test": "vitest run",
     "test:watch": "vitest watch",
     "test:types": "vue-tsc --noEmit && cd playground && vue-tsc --noEmit"
   },
   "dependencies": {
+    "@graphql-codegen/cli": "^5.0.7",
+    "@graphql-codegen/typed-document-node": "^5.1.2",
+    "@graphql-codegen/typescript": "^4.1.6",
+    "@graphql-codegen/typescript-operations": "^4.6.1",
+    "@graphql-typed-document-node/core": "^3.2.0",
     "@nuxt/kit": "^4.2.2",
     "graphql": "^16.12.0",
     "graphql-request": "^7.4.0",
-    "graphql-yoga": "^5.17.1"
+    "graphql-yoga": "^5.17.1",
+    "jiti": "^2.6.1",
+    "ohash": "^2.0.11",
+    "tinyglobby": "^0.2.15"
   },
   "devDependencies": {
     "@nuxt/devtools": "^3.1.1",
@@ -56,5 +64,10 @@
   },
   "publishConfig": {
     "access": "public"
+  },
+  "changlog": {
+    "types": {
+      "chore": false
+    }
   }
 }