From d4a4548aec8660e58dac243115d43a6011a2233c Mon Sep 17 00:00:00 2001
From: morgan-coded <256248948+morgan-coded@users.noreply.github.com>
Date: Fri, 29 May 2026 01:55:48 -0500
Subject: [PATCH] docs(api-codegen-preset): clarify that anonymous operations
 are ignored (fixes #1997)

The README's note that operations "must have a name" did not explain the
silent-failure mode reported in #1997: anonymous operations are counted as
documents (so they don't trigger the "no documents" error) but are skipped
during generation, so a project with only anonymous operations produces an
empty *.generated.d.ts with no warning. Expand the note with this behavior
and a named-vs-anonymous example so users don't lose time to an empty output.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 .../docs-codegen-anonymous-operations.md      |  8 +++++++
 .../api-clients/api-codegen-preset/README.md  | 23 ++++++++++++++++++-
 2 files changed, 30 insertions(+), 1 deletion(-)
 create mode 100644 .changeset/docs-codegen-anonymous-operations.md

diff --git a/.changeset/docs-codegen-anonymous-operations.md b/.changeset/docs-codegen-anonymous-operations.md
new file mode 100644
index 0000000000..3b75ac4878
--- /dev/null
+++ b/.changeset/docs-codegen-anonymous-operations.md
@@ -0,0 +1,8 @@
+---
+'@shopify/api-codegen-preset': patch
+---
+
+Document that anonymous GraphQL operations are silently ignored during type
+generation. Only named queries and mutations produce types; a project
+containing only anonymous operations generates an empty `*.generated.d.ts`
+without an error. (README-only change.)
diff --git a/packages/api-clients/api-codegen-preset/README.md b/packages/api-clients/api-codegen-preset/README.md
index f89537faa4..0dde750c25 100644
--- a/packages/api-clients/api-codegen-preset/README.md
+++ b/packages/api-clients/api-codegen-preset/README.md
@@ -332,7 +332,28 @@ pnpm graphql-codegen --project=UIExtensions
 > [!NOTE]
 > Codegen will fail if it can't find any documents to parse.
 > To fix that, either create a query or set the [`ignoreNoDocuments` option](https://the-guild.dev/graphql/codegen/docs/config-reference/codegen-config#configuration-options) to `true`.
-> Queries and mutations must have a name for the parsing to work.
+
+> [!IMPORTANT]
+> Your queries and mutations **must be named** for types to be generated.
+> Anonymous operations (e.g. `query { ... }` with no operation name) are
+> counted as documents, so they won't trigger the "no documents" error above,
+> but they are silently skipped during generation. A project containing only
+> anonymous operations therefore produces an empty `*.generated.d.ts` file with
+> no warning. Give every operation a name to have its types generated:
+>
+> ```ts
+> // Not generated — anonymous operation:
+> `#graphql
+> query {
+>   products(first: 5) { edges { node { id } } }
+> }`;
+>
+> // Generated — named operation:
+> `#graphql
+> query getProducts {
+>   products(first: 5) { edges { node { id } } }
+> }`;
+> ```
 
 Once the script parses your operations, you can mark any operations for parsing by adding the `#graphql` tag to the string.
 For example: