initial storefront graphql reference docs

Author: alexphelps

content/docs/storefront/graphql/index.mdx

@@ -136,6 +136,3 @@ Handle customer registration and authentication directly from your storefront wi
 ### Vouchers and discounts
 
 Apply and remove voucher codes from carts using `addVoucher` and `removeVoucher` mutations, enabling custom promo code UIs.
-
-
-

content/docs/storefront/graphql/meta.json

@@ -1,5 +1,5 @@
 {
-  "title": "GraphQL API",
+  "title": "Storefront GraphQL API",
   "pages": [
     "queries",
     "mutations"

next-env.d.ts

@@ -1,6 +1,6 @@
 /// <reference types="next" />
 /// <reference types="next/image-types/global" />
-import "./.next/types/routes.d.ts";
+import "./.next/dev/types/routes.d.ts";
 
 // NOTE: This file should not be edited
 // see https://nextjs.org/docs/app/api-reference/config/typescript for more information.

scripts/generate-graphql-docs.mjs

@@ -23,6 +23,16 @@ const LINK_ROOT = '/docs/storefront/graphql';
 
 // ── Step 1: Clean & generate ────────────────────────────────────────────────
 
+// Preserve hand-written files (index.mdx, meta.json) during regeneration
+const preserveFiles = ['index.mdx', 'meta.json'];
+const preserved = {};
+for (const file of preserveFiles) {
+  const p = join(GRAPHQL_DIR, file);
+  if (existsSync(p)) {
+    preserved[file] = readFileSync(p, 'utf8');
+  }
+}
+
 if (existsSync(GRAPHQL_DIR)) {
   rmSync(GRAPHQL_DIR, { recursive: true });
 }
@@ -51,25 +61,14 @@ for (const dir of ['operations', 'types']) {
   if (existsSync(p)) rmSync(p, { recursive: true });
 }
 
-// Remove the generated landing page
+// Remove the generated landing page (we maintain a custom index.mdx)
 const generatedPath = join(GRAPHQL_DIR, 'generated.md');
 if (existsSync(generatedPath)) rmSync(generatedPath);
 
-// Write clean index
-const indexPath = join(GRAPHQL_DIR, 'index.md');
-writeFileSync(indexPath, `---
-title: GraphQL Reference
----
-
-The Storefront GraphQL API reference documentation, automatically generated from the schema.
-
-Browse all available [Queries](/docs/storefront/graphql/queries) and [Mutations](/docs/storefront/graphql/mutations).
-`);
-
-writeFileSync(join(GRAPHQL_DIR, 'meta.json'), JSON.stringify({
-  title: 'GraphQL Reference',
-  pages: ['queries', 'mutations'],
-}, null, 2) + '\n');
+// Restore hand-written files that were preserved before the clean
+for (const [file, content] of Object.entries(preserved)) {
+  writeFileSync(join(GRAPHQL_DIR, file), content);
+}
 
 // ── Step 3: Introspect schema ───────────────────────────────────────────────