Improving webhook update docs per review

.changeset/serious-nails-own.md

@@ -5,3 +5,63 @@
 Added support for `future` flags in the `shopifyApp` function, with a `v3_webhookContext` flag to have `authenticate.webhook` return a standard `admin` context, instead of a different type.
 
 Apps can opt in to the new future at any time, so this is not a breaking change (yet).
+
+<details>
+  <summary>See an example</summary>
+
+Without the `v3_webhookContext` flag, `graphql` provides a `query` function that takes the query string as the `data` param.
+When using variables, `data` needs to be an object containing `query` and `variables`.
+
+```ts
+import {json, ActionFunctionArgs} from '@remix-run/node';
+import {authenticate} from '../shopify.server';
+
+export async function action({request}: ActionFunctionArgs) {
+  const {admin} = await authenticate.webhook(request);
+
+  const response = await admin?.graphql.query<any>({
+    data: {
+      query: `#graphql
+      mutation populateProduct($input: ProductInput!) {
+        productCreate(input: $input) {
+          product {
+            id
+          }
+        }
+      }`,
+      variables: {input: {title: 'Product Name'}},
+    },
+  });
+
+  const productData = response?.body.data;
+  return json({data: productData.data});
+}
+```
+
+With the `v3_webhookContext` flag enabled, `graphql` _is_ a function that takes in the query string and an optional settings object, including `variables`.
+
+```ts
+import {ActionFunctionArgs} from '@remix-run/node';
+import {authenticate} from '../shopify.server';
+
+export async function action({request}: ActionFunctionArgs) {
+  const {admin} = await authenticate.webhook(request);
+
+  const response = await admin?.graphql(
+    `#graphql
+    mutation populateProduct($input: ProductInput!) {
+      productCreate(input: $input) {
+        product {
+          id
+        }
+      }
+    }`,
+    {variables: {input: {title: 'Product Name'}}},
+  );
+
+  const productData = await response.json();
+  return json({data: productData.data});
+}
+```
+
+</details>

packages/shopify-app-remix/docs/generated/generated_static_pages.json

@@ -105,7 +105,7 @@
   {
     "id": "guide-future-flags",
     "title": "Future flags",
-    "description": "Similarly to how [Remix approaches breaking changes](https://remix.run/docs/en/main/start/future-flags), the `@shopify/shopify-app-remix` package also uses future flags.\n\nBigger features are breaking changes are initially added behind a future flag. This means that they're disabled by default, and must be manually enabled by setting the appropriate flag in the `future` option of the `shopifyApp` function.\n\nThis allows apps to gradually adopt new features, and prepare for breaking changes and major releases ahead of time.",
+    "description": "Similarly to how [Remix approaches breaking changes](https://remix.run/docs/en/main/start/future-flags), the `@shopify/shopify-app-remix` package also uses future flags.\n\nBigger features and breaking changes are initially added behind a future flag. This means that they're disabled by default, and must be manually enabled by setting the appropriate flag in the `future` option of the `shopifyApp` function.\n\nThis allows apps to gradually adopt new features, and prepare for breaking changes and major releases ahead of time.",
     "sections": [
       {
         "type": "Generic",
@@ -154,7 +154,7 @@
           {
             "name": "v3_webhookAdminContext",
             "value": "",
-            "description": "Returns the same `admin` context (`AdminApiContext`) from `authenticate.webhook` that is returned from `authenticate.admin`.",
+            "description": "Returns the same `admin` context (`AdminApiContext`) from `authenticate.webhook` that is returned from `authenticate.admin`.\n\nSee [authenticate.webhook](/docs/api/shopify-app-remix/authenticate/webhook#example-admin) for more details.",
             "isOptional": true
           }
         ]

packages/shopify-app-remix/docs/staticPages/future-flags.doc.ts

@@ -5,7 +5,7 @@ const data: LandingTemplateSchema = {
   title: 'Future flags',
   description:
     'Similarly to how [Remix approaches breaking changes](https://remix.run/docs/en/main/start/future-flags), the `@shopify/shopify-app-remix` package also uses future flags.' +
-    "\n\nBigger features are breaking changes are initially added behind a future flag. This means that they're disabled by default, and must be manually enabled by setting the appropriate flag in the `future` option of the `shopifyApp` function." +
+    "\n\nBigger features and breaking changes are initially added behind a future flag. This means that they're disabled by default, and must be manually enabled by setting the appropriate flag in the `future` option of the `shopifyApp` function." +
     '\n\nThis allows apps to gradually adopt new features, and prepare for breaking changes and major releases ahead of time.',
   sections: [
     {
@@ -66,7 +66,8 @@ const data: LandingTemplateSchema = {
           name: 'v3_webhookAdminContext',
           value: '',
           description:
-            'Returns the same `admin` context (`AdminApiContext`) from `authenticate.webhook` that is returned from `authenticate.admin`.',
+            'Returns the same `admin` context (`AdminApiContext`) from `authenticate.webhook` that is returned from `authenticate.admin`.' +
+            '\n\nSee [authenticate.webhook](/docs/api/shopify-app-remix/authenticate/webhook#example-admin) for more details.',
           isOptional: true,
         },
       ],