@wpnuxt/core 2.2.2 → 2.3.0

package/dist/module.d.mts

@@ -127,6 +127,42 @@ interface WPNuxtConfig {
          */
         revalidateSecret?: string;
     };
+    /**
+     * Auto-generation of fragments + queries for Custom Post Types.
+     *
+     * WPNuxt parses the downloaded `schema.graphql` at build time, finds every
+     * object type implementing `ContentNode`, and emits a base fragment plus
+     * `Listing`, `ByUri`, and `BySlug` queries for each discovered CPT. Built-in
+     * types (Post, Page, MediaItem, Revision, Comment) are excluded because
+     * they already have default queries.
+     *
+     * Generated files land in `.queries/` and can be fully overridden by
+     * dropping a file with the same name in `extend/queries/fragments/`
+     * (for fragments) or `extend/queries/` (for queries).
+     */
+    cpt?: {
+        /**
+         * Enable CPT auto-generation.
+         *
+         * @default true
+         */
+        enabled?: boolean;
+        /**
+         * Type names to skip in addition to the built-in exclusions.
+         *
+         * @example ['DraftPost', 'InternalNote']
+         */
+        exclude?: string[];
+        /**
+         * If set, only these type names will be auto-generated.
+         *
+         * Useful when you want fine-grained control over which CPTs get
+         * auto-generated output. Built-in exclusions still apply.
+         *
+         * @example ['Event', 'Artist']
+         */
+        include?: string[];
+    };
 }
 
 declare const _default: _nuxt_schema.NuxtModule<WPNuxtConfig, WPNuxtConfig, false>;

package/dist/module.d.ts

@@ -127,6 +127,42 @@ interface WPNuxtConfig {
          */
         revalidateSecret?: string;
     };
+    /**
+     * Auto-generation of fragments + queries for Custom Post Types.
+     *
+     * WPNuxt parses the downloaded `schema.graphql` at build time, finds every
+     * object type implementing `ContentNode`, and emits a base fragment plus
+     * `Listing`, `ByUri`, and `BySlug` queries for each discovered CPT. Built-in
+     * types (Post, Page, MediaItem, Revision, Comment) are excluded because
+     * they already have default queries.
+     *
+     * Generated files land in `.queries/` and can be fully overridden by
+     * dropping a file with the same name in `extend/queries/fragments/`
+     * (for fragments) or `extend/queries/` (for queries).
+     */
+    cpt?: {
+        /**
+         * Enable CPT auto-generation.
+         *
+         * @default true
+         */
+        enabled?: boolean;
+        /**
+         * Type names to skip in addition to the built-in exclusions.
+         *
+         * @example ['DraftPost', 'InternalNote']
+         */
+        exclude?: string[];
+        /**
+         * If set, only these type names will be auto-generated.
+         *
+         * Useful when you want fine-grained control over which CPTs get
+         * auto-generated output. Built-in exclusions still apply.
+         *
+         * @example ['Event', 'Artist']
+         */
+        include?: string[];
+    };
 }
 
 declare const _default: _nuxt_schema.NuxtModule<WPNuxtConfig, WPNuxtConfig, false>;

package/dist/module.json

@@ -1,6 +1,6 @@
 {
   "name": "@wpnuxt/core",
-  "version": "2.2.2",
+  "version": "2.3.0",
   "configKey": "wpNuxt",
   "compatibility": {
     "nuxt": ">=4.0.0"

package/dist/module.mjs

@@ -1,14 +1,175 @@
 import { defu } from 'defu';
-import { promises, cpSync, existsSync, readdirSync, statSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
-import { writeFile, rename, readFile, mkdir } from 'node:fs/promises';
+import { existsSync, readFileSync, promises, cpSync, readdirSync, statSync, mkdirSync, writeFileSync } from 'node:fs';
+import { mkdir, writeFile, rename, readFile } from 'node:fs/promises';
 import { join, relative, dirname } from 'node:path';
 import { useLogger, createResolver, resolveFiles, defineNuxtModule, addPlugin, addServerHandler, addImports, addComponentsDir, addTemplate, addTypeTemplate, hasNuxtModule, installModule } from '@nuxt/kit';
 import { upperFirst } from 'scule';
 import { parse, GraphQLError, visit, print } from 'graphql';
+import ts from 'typescript';
 import { execSync } from 'node:child_process';
 import { consola } from 'consola';
 
-const version = "2.2.2";
+const version = "2.3.0";
+
+const DEFAULT_CPT_EXCLUSIONS = [
+  "Post",
+  "Page",
+  "MediaItem",
+  "Revision",
+  "Comment",
+  "ActionMonitorAction"
+];
+function discoverCpts(schemaPath, options = {}) {
+  if (!existsSync(schemaPath)) return [];
+  let ast;
+  try {
+    ast = parse(readFileSync(schemaPath, "utf8"), { noLocation: true });
+  } catch {
+    return [];
+  }
+  const typesByName = /* @__PURE__ */ new Map();
+  const enumsByName = /* @__PURE__ */ new Map();
+  for (const def of ast.definitions) {
+    if (def.kind === "ObjectTypeDefinition") typesByName.set(def.name.value, def);
+    else if (def.kind === "EnumTypeDefinition") enumsByName.set(def.name.value, def);
+  }
+  const rootQuery = typesByName.get("RootQuery");
+  if (!rootQuery?.fields) return [];
+  const fieldsByType = /* @__PURE__ */ new Map();
+  for (const field of rootQuery.fields) {
+    const returnType = unwrapNamedType(field.type);
+    if (!returnType) continue;
+    const hasIdType = field.arguments?.some((a) => a.name.value === "idType");
+    if (typesByName.has(returnType) && hasIdType) {
+      const idTypeArg = field.arguments?.find((a) => a.name.value === "idType");
+      const idTypeEnum = idTypeArg ? unwrapNamedType(idTypeArg.type) : void 0;
+      const entry = fieldsByType.get(returnType) ?? {};
+      entry.single = field.name.value;
+      entry.idTypeEnum = idTypeEnum;
+      fieldsByType.set(returnType, entry);
+      continue;
+    }
+    const connMatch = /^RootQueryTo(\w+)Connection$/.exec(returnType);
+    const hasCursorArgs = field.arguments?.some((a) => a.name.value === "first") && field.arguments?.some((a) => a.name.value === "after");
+    if (connMatch && hasCursorArgs) {
+      const typeName = connMatch[1];
+      const entry = fieldsByType.get(typeName) ?? {};
+      entry.connection = field.name.value;
+      fieldsByType.set(typeName, entry);
+    }
+  }
+  const excludeSet = /* @__PURE__ */ new Set([...DEFAULT_CPT_EXCLUSIONS, ...options.exclude ?? []]);
+  const includeSet = options.include?.length ? new Set(options.include) : void 0;
+  const result = [];
+  for (const [typeName, node] of typesByName) {
+    if (!typeImplements(node, "ContentNode")) continue;
+    if (excludeSet.has(typeName)) continue;
+    if (includeSet && !includeSet.has(typeName)) continue;
+    const queryFields = fieldsByType.get(typeName);
+    if (!queryFields?.single || !queryFields.connection) continue;
+    const supportedIdTypes = /* @__PURE__ */ new Set();
+    if (queryFields.idTypeEnum) {
+      const enumDef = enumsByName.get(queryFields.idTypeEnum);
+      enumDef?.values?.forEach((v) => supportedIdTypes.add(v.name.value));
+    }
+    result.push({
+      typeName,
+      singleField: queryFields.single,
+      connectionField: queryFields.connection,
+      idTypeEnum: queryFields.idTypeEnum,
+      supportedIdTypes,
+      interfaces: new Set((node.interfaces ?? []).map((i) => i.name.value)),
+      hasField: collectScalarFieldFlags(node, ["title", "slug", "uri", "date"])
+    });
+  }
+  return result.sort((a, b) => a.typeName.localeCompare(b.typeName));
+}
+function unwrapNamedType(type) {
+  let current = type;
+  while (current) {
+    if (current.kind === "NamedType") return current.name.value;
+    current = current.type;
+  }
+  return void 0;
+}
+function typeImplements(node, interfaceName) {
+  return node.interfaces?.some((i) => i.name.value === interfaceName) ?? false;
+}
+function collectScalarFieldFlags(node, fieldNames) {
+  const flags = {};
+  const declared = new Set((node.fields ?? []).map((f) => f.name.value));
+  for (const name of fieldNames) flags[name] = declared.has(name);
+  return flags;
+}
+
+async function writeCptArtifacts(cpt, outputPath) {
+  const fragmentsDir = join(outputPath, "fragments");
+  const fragmentPath = join(fragmentsDir, `${cpt.typeName}.fragment.gql`);
+  const queryPath = join(outputPath, `${upperFirst(cpt.connectionField)}.gql`);
+  const wroteFragment = !existsSync(fragmentPath);
+  const wroteQueries = !existsSync(queryPath);
+  if (wroteFragment) {
+    await mkdir(fragmentsDir, { recursive: true });
+    await writeFile(fragmentPath, buildCptFragment(cpt), "utf-8");
+  }
+  if (wroteQueries) {
+    await writeFile(queryPath, buildCptQueries(cpt), "utf-8");
+  }
+  return { cpt, wroteFragment, wroteQueries };
+}
+function buildCptFragment(cpt) {
+  const lines = [`fragment ${cpt.typeName} on ${cpt.typeName} {`];
+  lines.push("  ...ContentNode");
+  if (cpt.interfaces.has("NodeWithExcerpt")) lines.push("  ...NodeWithExcerpt");
+  if (cpt.interfaces.has("NodeWithContentEditor")) lines.push("  ...NodeWithContentEditor");
+  if (cpt.interfaces.has("NodeWithFeaturedImage")) lines.push("  ...NodeWithFeaturedImage");
+  if (cpt.hasField.title) lines.push("  title");
+  lines.push("}");
+  lines.push("");
+  return lines.join("\n");
+}
+function buildCptQueries(cpt) {
+  const { typeName, singleField, connectionField, supportedIdTypes } = cpt;
+  const listQueryName = upperFirst(connectionField);
+  const queries = [];
+  queries.push(
+    `query ${listQueryName}($first: Int = 20, $after: String) {`,
+    `  ${connectionField}(first: $first, after: $after) {`,
+    `    nodes {`,
+    `      ...${typeName}`,
+    `    }`,
+    `    pageInfo {`,
+    `      hasNextPage`,
+    `      hasPreviousPage`,
+    `      startCursor`,
+    `      endCursor`,
+    `    }`,
+    `  }`,
+    `}`,
+    ""
+  );
+  if (supportedIdTypes.has("URI")) {
+    queries.push(
+      `query ${typeName}ByUri($uri: ID!) {`,
+      `  ${singleField}(id: $uri, idType: URI) {`,
+      `    ...${typeName}`,
+      `  }`,
+      `}`,
+      ""
+    );
+  }
+  if (supportedIdTypes.has("SLUG")) {
+    queries.push(
+      `query ${typeName}BySlug($slug: ID!) {`,
+      `  ${singleField}(id: $slug, idType: SLUG) {`,
+      `    ...${typeName}`,
+      `  }`,
+      `}`,
+      ""
+    );
+  }
+  return queries.join("\n");
+}
 
 function createModuleError(module, message) {
   return new Error(formatErrorMessage(module, message));
@@ -51,7 +212,7 @@ const initLogger = (debug) => {
 function getLogger() {
   return loggerInstance;
 }
-async function mergeQueries(nuxt, wpNuxtConfig, resolver) {
+async function mergeQueries(nuxt, wpNuxtConfig, resolver, schemaPath) {
   const logger = getLogger();
   const baseDir = nuxt.options.srcDir || nuxt.options.rootDir;
   const { resolve } = createResolver(baseDir);
@@ -60,6 +221,20 @@ async function mergeQueries(nuxt, wpNuxtConfig, resolver) {
   const defaultQueriesPath = resolver.resolve("./runtime/queries");
   await promises.rm(queryOutputPath, { recursive: true, force: true });
   cpSync(defaultQueriesPath, queryOutputPath, { recursive: true });
+  const cptSpreads = [];
+  if (schemaPath && wpNuxtConfig.cpt?.enabled !== false) {
+    const cpts = discoverCpts(schemaPath, {
+      exclude: wpNuxtConfig.cpt?.exclude,
+      include: wpNuxtConfig.cpt?.include
+    });
+    for (const cpt of cpts) {
+      await writeCptArtifacts(cpt, queryOutputPath);
+      cptSpreads.push({ name: cpt.typeName, type: cpt.typeName });
+    }
+    if (cpts.length) {
+      logger.debug(`Auto-generated fragments + queries for CPTs: ${cpts.map((c) => c.typeName).join(", ")}`);
+    }
+  }
   const conflicts = findConflicts(userQueryPath, queryOutputPath);
   if (conflicts.length && wpNuxtConfig.queries.warnOnOverride) {
     logger.warn("The following user query files will override default queries:");
@@ -71,26 +246,29 @@ async function mergeQueries(nuxt, wpNuxtConfig, resolver) {
     logger.debug("Extending queries:", userQueryPath);
     copyGraphqlFiles(userQueryPath, queryOutputPath);
   }
-  await addCustomFragmentsToNodeQuery(queryOutputPath, userQueryPath, logger);
+  await addCustomFragmentsToNodeQuery(queryOutputPath, userQueryPath, logger, cptSpreads);
   logger.debug("Merged queries folder:", queryOutputPath);
   return queryOutputPath;
 }
 const FRAGMENT_DEF_PATTERN = /fragment\s+(\w+)\s+on\s+(\w+)/;
-async function addCustomFragmentsToNodeQuery(queryOutputPath, userQueryPath, logger) {
+async function addCustomFragmentsToNodeQuery(queryOutputPath, userQueryPath, logger, preDiscovered = []) {
+  const byType = /* @__PURE__ */ new Map();
+  for (const f of preDiscovered) byType.set(f.type, f);
   const userFragmentsDir = join(userQueryPath, "fragments");
-  if (!existsSync(userFragmentsDir)) return;
-  const customFragments = [];
-  for (const file of readdirSync(userFragmentsDir)) {
-    if (!file.endsWith(".gql") && !file.endsWith(".graphql")) continue;
-    const content = await promises.readFile(join(userFragmentsDir, file), "utf-8");
-    const match = content.match(FRAGMENT_DEF_PATTERN);
-    if (!match) continue;
-    const name = match[1];
-    const type = match[2];
-    if (name && type && name === type) {
-      customFragments.push({ name, type });
+  if (existsSync(userFragmentsDir)) {
+    for (const file of readdirSync(userFragmentsDir)) {
+      if (!file.endsWith(".gql") && !file.endsWith(".graphql")) continue;
+      const content = await promises.readFile(join(userFragmentsDir, file), "utf-8");
+      const match = content.match(FRAGMENT_DEF_PATTERN);
+      if (!match) continue;
+      const name = match[1];
+      const type = match[2];
+      if (name && type && name === type) {
+        byType.set(type, { name, type });
+      }
     }
   }
+  const customFragments = [...byType.values()];
   if (customFragments.length === 0) return;
   const nodeGqlPath = join(queryOutputPath, "Node.gql");
   if (!existsSync(nodeGqlPath)) return;
@@ -204,6 +382,46 @@ function processSelections(selections, level, query, canExtract = true) {
 }
 const parseDoc = _parseDoc;
 
+const { factory, SyntaxKind, NewLineKind, EmitHint, ScriptTarget } = ts;
+function typeRef(name, typeArguments) {
+  return factory.createTypeReferenceNode(name, typeArguments);
+}
+function nonNullable(node) {
+  return typeRef("NonNullable", [node]);
+}
+function withImagePath(node) {
+  return typeRef("WithImagePath", [node]);
+}
+function indexedAccess(target, key) {
+  return factory.createIndexedAccessTypeNode(
+    target,
+    // `isSingleQuote` preserves the single-quote style the generator used
+    // before this module was AST-based — keeps generated .d.ts text-stable.
+    factory.createLiteralTypeNode(factory.createStringLiteral(key, true))
+  );
+}
+function numberIndexedAccess(target) {
+  return factory.createIndexedAccessTypeNode(
+    target,
+    factory.createKeywordTypeNode(SyntaxKind.NumberKeyword)
+  );
+}
+function arrayOf(node) {
+  return factory.createArrayTypeNode(node);
+}
+function unionOrSingle(nodes) {
+  if (nodes.length === 0) {
+    throw new Error("unionOrSingle: empty type list");
+  }
+  if (nodes.length === 1) return nodes[0];
+  return factory.createUnionTypeNode(nodes);
+}
+const printer = ts.createPrinter({ newLine: NewLineKind.LineFeed, removeComments: false });
+const syntheticFile = ts.createSourceFile("__synthetic.ts", "", ScriptTarget.Latest);
+function printType(node) {
+  return printer.printNode(EmitHint.Unspecified, node, syntheticFile);
+}
+
 const SCHEMA_PATTERN = /schema\.(?:gql|graphql)$/i;
 const COMPLEXITY_THRESHOLDS = {
   /** Maximum recommended extraction depth */
@@ -257,37 +475,40 @@ async function prepareContext(ctx) {
   const fnName = (fn) => ctx.composablesPrefix + upperFirst(fn);
   const mutationFnName = (fn) => `useMutation${upperFirst(fn)}`;
   const formatNodes = (nodes) => nodes?.map((n) => `'${n}'`).join(",") ?? "";
-  const getFragmentType = (q) => {
+  const buildFragmentTypeNode = (q) => {
     if (q.hasPageInfo) {
       if (q.hasInlineFields || !q.fragments?.length) {
         if (q.nodes?.length) {
-          let typePath = `${q.name}RootQuery`;
-          for (const node of q.nodes) {
-            typePath = `NonNullable<${typePath}>['${node}']`;
+          let node = typeRef(`${q.name}RootQuery`);
+          for (const segment of q.nodes) {
+            node = indexedAccess(nonNullable(node), segment);
           }
-          typePath = `NonNullable<${typePath}>['nodes'][number]`;
-          return typePath;
+          return numberIndexedAccess(indexedAccess(nonNullable(node), "nodes"));
         }
-        return `${q.name}RootQuery`;
+        return typeRef(`${q.name}RootQuery`);
       }
-      return q.fragments.map((f) => `WithImagePath<${f}Fragment>`).join(" | ");
+      return unionOrSingle(q.fragments.map((f) => withImagePath(typeRef(`${f}Fragment`))));
     }
     if (q.hasInlineFields || !q.fragments?.length) {
       if (q.nodes?.length) {
-        let typePath = `${q.name}RootQuery`;
-        for (const node of q.nodes) {
-          typePath = `NonNullable<${typePath}>['${node}']`;
+        let node = typeRef(`${q.name}RootQuery`);
+        for (const segment of q.nodes) {
+          node = indexedAccess(nonNullable(node), segment);
         }
         if (q.nodes.includes("nodes")) {
-          typePath = `${typePath}[number]`;
+          node = numberIndexedAccess(node);
         }
-        return typePath;
+        return node;
       }
-      return `${q.name}RootQuery`;
+      return typeRef(`${q.name}RootQuery`);
+    }
+    const fragmentTypes = q.fragments.map((f) => withImagePath(typeRef(`${f}Fragment`)));
+    if (q.nodes?.includes("nodes")) {
+      return unionOrSingle(fragmentTypes.map(arrayOf));
     }
-    const fragmentSuffix = q.nodes?.includes("nodes") ? "[]" : "";
-    return q.fragments.map((f) => `WithImagePath<${f}Fragment>${fragmentSuffix}`).join(" | ");
+    return unionOrSingle(fragmentTypes);
   };
+  const getFragmentType = (q) => printType(buildFragmentTypeNode(q));
   const queryFnExp = (q, typed = false) => {
     const functionName = fnName(q.name);
     if (q.hasPageInfo) {
@@ -304,7 +525,7 @@ async function prepareContext(ctx) {
   const mutationFnExp = (m, typed = false) => {
     const functionName = mutationFnName(m.name);
     if (!typed) {
-      return `export const ${functionName} = (variables, options) => useGraphqlMutation('${m.name}', variables, options)`;
+      return `export const ${functionName} = (variables, options) => wpMutation('${m.name}', variables, options)`;
     }
     return `  export const ${functionName}: (variables: ${m.name}MutationVariables, options?: WPMutationOptions) => Promise<WPMutationResult<${m.name}Mutation>>`;
   };
@@ -319,11 +540,13 @@ async function prepareContext(ctx) {
     if (hasConnectionQueries) {
       imports.push("useWPConnection");
     }
-    if (mutations.length > 0) {
-      imports.push("useGraphqlMutation");
-    }
     if (imports.length > 0) {
       lines.push(`import { ${imports.join(", ")} } from '#imports'`);
+    }
+    if (mutations.length > 0) {
+      lines.push(`import { wpMutation } from '#wpnuxt-internal'`);
+    }
+    if (lines.length > 0) {
       lines.push("");
     }
     queries.forEach((f) => {
@@ -347,6 +570,7 @@ async function prepareContext(ctx) {
     typeSet.add(`${m.name}MutationVariables`);
     typeSet.add(`${m.name}Mutation`);
   });
+  ctx.referencedTypes = [...typeSet];
   ctx.generateDeclarations = () => {
     const declarations = [
       `import type { ${[...typeSet].join(", ")} } from '#build/graphql-operations'`,
@@ -518,7 +742,7 @@ Make sure WPGraphQL plugin is installed and activated on your WordPress site.`
       );
     }
     await checkWPGraphQLVersion(fullUrl, headers);
-    if (options.schemaPath && !existsSync(options.schemaPath)) {
+    if (options.schemaPath) {
       try {
         const authFlag = options.authToken ? ` -h "Authorization=Bearer ${options.authToken}"` : "";
         execSync(`npx get-graphql-schema "${fullUrl}"${authFlag} > "${options.schemaPath}"`, {
@@ -649,6 +873,40 @@ function patchWPGraphQLSchema(schemaPath) {
   writeFileSync(schemaPath, patchSchemaText(schema));
 }
 
+function validateGeneratedPaths(referencedTypes, operationsDtsPath) {
+  if (!existsSync(operationsDtsPath)) {
+    return { skipped: true, dangling: [] };
+  }
+  const source = readFileSync(operationsDtsPath, "utf8");
+  const sourceFile = ts.createSourceFile(
+    operationsDtsPath,
+    source,
+    ts.ScriptTarget.Latest,
+    false
+  );
+  const declared = /* @__PURE__ */ new Set();
+  const visit = (node) => {
+    if (ts.isTypeAliasDeclaration(node) || ts.isInterfaceDeclaration(node) || ts.isClassDeclaration(node)) {
+      if (node.name) declared.add(node.name.text);
+    } else if (ts.isVariableStatement(node)) {
+      for (const d of node.declarationList.declarations) {
+        if (ts.isIdentifier(d.name)) declared.add(d.name.text);
+      }
+    } else if (ts.isModuleDeclaration(node) && node.body && ts.isModuleBlock(node.body)) {
+      for (const child of node.body.statements) visit(child);
+    }
+  };
+  for (const stmt of sourceFile.statements) visit(stmt);
+  const dangling = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const ref of referencedTypes) {
+    if (seen.has(ref)) continue;
+    seen.add(ref);
+    if (!declared.has(ref)) dangling.push(ref);
+  }
+  return { skipped: false, dangling };
+}
+
 async function runInstall(nuxt) {
   const logger = useLogger("wpnuxt", {
     level: process.env.WPNUXT_DEBUG === "true" ? 4 : 3
@@ -872,6 +1130,11 @@ const module$1 = defineNuxtModule({
       maxAge: 60 * 5,
       // 5 minutes
       swr: true
+    },
+    cpt: {
+      enabled: true,
+      exclude: [],
+      include: []
     }
   },
   async setup(options, nuxt) {
@@ -890,7 +1153,6 @@ const module$1 = defineNuxtModule({
     addPlugin(resolver.resolve("./runtime/plugins/graphqlErrors"));
     addPlugin(resolver.resolve("./runtime/plugins/sanitizeHtml"));
     configureTrailingSlash(nuxt, logger);
-    const mergedQueriesFolder = await mergeQueries(nuxt, wpNuxtConfig, resolver);
     const packageRoot = resolver.resolve("..");
     nuxt.options._layers.push({
       cwd: packageRoot,
@@ -906,31 +1168,21 @@ const module$1 = defineNuxtModule({
     const schemaPath = join(nuxt.options.rootDir, "schema.graphql");
     const schemaExists = existsSync(schemaPath);
     if (wpNuxtConfig.downloadSchema) {
-      if (!schemaExists) {
-        logger.debug(`Downloading schema from: ${wpNuxtConfig.wordpressUrl}${wpNuxtConfig.graphqlEndpoint}`);
+      logger.debug(`Downloading schema from: ${wpNuxtConfig.wordpressUrl}${wpNuxtConfig.graphqlEndpoint}`);
+      try {
         await validateWordPressEndpoint(
           wpNuxtConfig.wordpressUrl,
           wpNuxtConfig.graphqlEndpoint,
           { schemaPath, authToken: wpNuxtConfig.schemaAuthToken }
         );
         logger.debug("Schema downloaded successfully");
-      } else {
-        nuxt.hook("ready", async () => {
-          try {
-            await validateWordPressEndpoint(
-              wpNuxtConfig.wordpressUrl,
-              wpNuxtConfig.graphqlEndpoint,
-              { authToken: wpNuxtConfig.schemaAuthToken }
-            );
-            logger.debug("WordPress endpoint validation passed");
-          } catch (error) {
-            const message = error instanceof Error ? error.message : String(error);
-            logger.warn(`WordPress endpoint validation failed: ${message.split("\n")[0]}`);
-            logger.warn("App will continue with existing schema.graphql file");
-          }
-        });
+      } catch (error) {
+        if (!schemaExists) throw error;
+        const message = error instanceof Error ? error.message : String(error);
+        logger.warn(`Schema refresh failed, using cached schema.graphql: ${message.split("\n")[0]}`);
       }
     }
+    const mergedQueriesFolder = await mergeQueries(nuxt, wpNuxtConfig, resolver, schemaPath);
     await registerModules(nuxt, resolver, wpNuxtConfig, mergedQueriesFolder);
     nuxt.hook("devtools:customTabs", (tabs) => {
       const middlewareTab = tabs.find((tab) => tab.name === "nuxt-graphql-middleware");
@@ -1031,12 +1283,14 @@ const module$1 = defineNuxtModule({
     nuxt.options.alias["#wpnuxt"] = resolver.resolve(nuxt.options.buildDir, "wpnuxt");
     nuxt.options.alias["#wpnuxt/*"] = resolver.resolve(nuxt.options.buildDir, "wpnuxt", "*");
     nuxt.options.alias["#wpnuxt/types"] = resolver.resolve("./types");
+    nuxt.options.alias["#wpnuxt-internal"] = resolver.resolve("./runtime/internal/graphql-client");
     nuxt.options.alias["@wpnuxt/core/server-options"] = resolver.resolve("./server-options");
     nuxt.options.alias["@wpnuxt/core/client-options"] = resolver.resolve("./client-options");
     const nitroOpts = nuxt.options;
     nitroOpts.nitro = nitroOpts.nitro || {};
     nitroOpts.nitro.alias = nitroOpts.nitro.alias || {};
     nitroOpts.nitro.alias["#wpnuxt/types"] = resolver.resolve("./types");
+    nitroOpts.nitro.alias["#wpnuxt-internal"] = resolver.resolve("./runtime/internal/graphql-client");
     nitroOpts.nitro.externals = nitroOpts.nitro.externals || {};
     nitroOpts.nitro.externals.inline = nitroOpts.nitro.externals.inline || [];
     addTemplate({
@@ -1053,6 +1307,16 @@ const module$1 = defineNuxtModule({
       autoimports.push(...ctx.fnImports || []);
     });
     logger.trace("Finished generating composables");
+    nuxt.hook("build:before", () => {
+      if (!ctx.referencedTypes?.length) return;
+      const operationsDtsPath = join(nuxt.options.buildDir, "graphql-operations.d.ts");
+      const result = validateGeneratedPaths(ctx.referencedTypes, operationsDtsPath);
+      if (result.skipped || result.dangling.length === 0) return;
+      logger.warn(
+        `WPNuxt generated composables reference ${result.dangling.length} type(s) not declared in graphql-operations.d.ts. This usually means your WordPress GraphQL schema has drifted from your queries; delete schema.graphql to force a fresh download, then re-run pnpm dev:prepare.`
+      );
+      for (const t of result.dangling) logger.warn(`  - ${t}`);
+    });
     logger.info(`WPNuxt module loaded in ${(/* @__PURE__ */ new Date()).getTime() - startTime}ms`);
   },
   async onInstall(nuxt) {

package/dist/runtime/composables/useWPContent.js

@@ -1,5 +1,6 @@
 import { transformData, normalizeUriParam } from "../util/content.js";
-import { computed, ref, toValue, watch as vueWatch, useAsyncGraphqlQuery, useRuntimeConfig } from "#imports";
+import { computed, ref, toValue, watch as vueWatch, useRuntimeConfig } from "#imports";
+import { wpQuery } from "../internal/graphql-client.js";
 const defaultGetCachedData = (key, app, ctx) => {
   if (app.isHydrating) {
     return app.payload.data[key];
@@ -58,7 +59,7 @@ export const useWPContent = (queryName, nodes, fixImagePaths, params, options) =
       }
     }
   };
-  const asyncResult = useAsyncGraphqlQuery(
+  const asyncResult = wpQuery(
     String(queryName),
     resolvedParams,
     asyncDataOptions

package/dist/runtime/internal/graphql-client.js

@@ -0,0 +1,73 @@
+import { useAsyncGraphqlQuery, useGraphqlMutation, useNuxtApp, watch, toValue } from "#imports";
+export const wpQuery = ((...args) => {
+  const [name, variables] = args;
+  const nuxtApp = useNuxtApp();
+  const result = useAsyncGraphqlQuery(...args);
+  let wasPending = false;
+  let cycleStart = 0;
+  const pendingSource = result.pending;
+  const errorSource = result.error;
+  watch(
+    pendingSource,
+    (isPending) => {
+      if (isPending) {
+        wasPending = true;
+        cycleStart = performance.now();
+        return;
+      }
+      if (!wasPending) return;
+      wasPending = false;
+      const errorVal = errorSource?.value instanceof Error ? errorSource.value : void 0;
+      emitHook(nuxtApp, {
+        queryName: String(name),
+        queryType: "query",
+        variables: normalizeVariables(variables),
+        durationMs: performance.now() - cycleStart,
+        status: errorVal ? "error" : "success",
+        ...errorVal ? { error: errorVal } : {}
+      });
+    },
+    { immediate: true }
+  );
+  return result;
+});
+export const wpMutation = ((...args) => {
+  const [name, variables] = args;
+  const nuxtApp = useNuxtApp();
+  const startTime = performance.now();
+  const promise = useGraphqlMutation(...args);
+  Promise.resolve(promise).then(
+    () => emitHook(nuxtApp, {
+      queryName: String(name),
+      queryType: "mutation",
+      variables: normalizeVariables(variables),
+      durationMs: performance.now() - startTime,
+      status: "success"
+    }),
+    (err) => emitHook(nuxtApp, {
+      queryName: String(name),
+      queryType: "mutation",
+      variables: normalizeVariables(variables),
+      durationMs: performance.now() - startTime,
+      status: "error",
+      error: err instanceof Error ? err : new Error(String(err))
+    })
+  );
+  return promise;
+});
+function normalizeVariables(variables) {
+  const value = toValue(variables);
+  if (value && typeof value === "object") return value;
+  return void 0;
+}
+function emitHook(nuxtApp, payload) {
+  if (typeof nuxtApp?.callHook !== "function") return;
+  const maybePromise = nuxtApp.callHook("wpnuxt:query", payload);
+  if (maybePromise && typeof maybePromise.then === "function") {
+    Promise.resolve(maybePromise).catch((err) => {
+      if (import.meta.dev) {
+        console.warn("[wpnuxt] wpnuxt:query hook handler threw", err);
+      }
+    });
+  }
+}

package/dist/runtime/types/stub.d.ts

@@ -42,6 +42,11 @@ export function useAsyncGraphqlQuery<T = unknown>(
   status: Ref<string>
 }
 export function useGraphqlState(): Record<string, unknown>
+export function useGraphqlMutation<T = unknown>(
+  name: string,
+  variables?: Record<string, unknown>,
+  options?: Record<string, unknown>
+): Promise<{ data: T | null, errors?: Array<{ message: string }> | null }>
 
 // Stub for #nuxt-graphql-middleware/operation-types
 export type Query = Record<string, unknown>

package/dist/runtime/util/content.js

@@ -23,7 +23,11 @@ export const transformData = (data, nodes, fixImagePaths) => {
   if (fixImagePaths && transformedData) {
     if (Array.isArray(transformedData)) {
       transformedData.forEach(addRelativePath);
-    } else {
+    } else if (typeof transformedData === "object") {
+      const maybeNodes = transformedData.nodes;
+      if (Array.isArray(maybeNodes)) {
+        maybeNodes.forEach(addRelativePath);
+      }
       addRelativePath(transformedData);
     }
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wpnuxt/core",
-  "version": "2.2.2",
+  "version": "2.3.0",
   "description": "Nuxt module for WordPress integration via GraphQL (WPGraphQL)",
   "keywords": [
     "nuxt",
@@ -54,7 +54,8 @@
     "dompurify": "^3.4.0",
     "graphql": "^16.13.2",
     "nuxt-graphql-middleware": "5.4.0",
-    "scule": "^1.3.0"
+    "scule": "^1.3.0",
+    "typescript": "^5.9.3"
   },
   "devDependencies": {
     "@nuxt/devtools": "^3.2.3",