Updates to Hydrogen React API reference landing page (#874)

* Update Hydrogen React api landing page

* Correct formatting

packages/hydrogen-react/docs/staticPages/authenticate.client.js

@@ -0,0 +1,8 @@
+import {createStorefrontClient} from '@shopify/hydrogen-react';
+
+export const client = createStorefrontClient({
+  // load environment variables according to your framework and runtime
+  storeDomain: process.env.PUBLIC_STORE_DOMAIN,
+  storefrontApiVersion: process.env.PUBLIC_STOREFRONT_API_VERSION,
+  publicStorefrontToken: process.env.PUBLIC_STOREFRONT_API_TOKEN,
+});

packages/hydrogen-react/docs/staticPages/authenticate.env.example

@@ -0,0 +1,6 @@
+# Replace with your own store domain and Storefront API token
+
+PUBLIC_STOREFRONT_API_TOKEN="public_token"
+PRIVATE_STOREFRONT_API_TOKEN="private_token"
+PUBLIC_STOREFRONT_API_VERSION="2023-04"
+PUBLIC_STORE_DOMAIN="store_id.myshopify.com"

packages/hydrogen-react/docs/staticPages/authenticate.server.js

@@ -0,0 +1,28 @@
+import {client} from './client.js';
+
+export async function getServerSideProps() {
+  const response = await fetch(client.getStorefrontApiUrl(), {
+    body: JSON.stringify({
+      query: GRAPHQL_QUERY,
+    }),
+    // Generate the headers using the private token.
+    headers: client.getPrivateTokenHeaders(),
+    method: 'POST',
+  });
+
+  if (!response.ok) {
+    throw new Error(response.statusText);
+  }
+
+  const json = await response.json();
+
+  return {props: json};
+}
+
+const GRAPHQL_QUERY = `
+  query {
+    shop {
+      name
+    }
+  }
+`;

packages/hydrogen-react/docs/staticPages/hydrogenReact.doc.ts

@@ -3,22 +3,22 @@ import {LandingTemplateSchema} from '@shopify/generate-docs';
 const data: LandingTemplateSchema = {
   title: 'Hydrogen React',
   description:
-    'Hydrogen React is an unopinionated and performant library of Shopify-specific React components, reusable functions, and utilities for interacting with the Storefront API. This guide provides a complete reference of the components, hooks, and utilities that Hydrogen React offers, and their relationships to each other.',
+    'Hydrogen React is a performant, framework-agnostic library of React components, reusable functions, and utilities for interacting with Shopify’s [Storefront API](/docs/api/storefront). It’s bundled with [Hydrogen](/docs/api/hydrogen), but can be used by any React-based web app.',
   id: 'hydrogen-react',
   sections: [
     {
       type: 'Generic',
       anchorLink: 'setup',
       title: 'Setup',
       sectionContent: `
-1. Run one of the example commands to install the package
-1. Import the component, hook, or utility that you want to use in your app. For more detailed instructions, see the Getting Started Guide.
+1. Install Hydrogen React in your project with your preferred package manager.
+1. Import components, hooks, or utilities that you want to use in your app. For more detailed instructions, see the Getting Started guide.
       `,
       sectionCard: [
         {
-          subtitle: 'Navigate to',
-          name: 'Getting Started Guide',
-          url: '/custom-storefronts/hydrogen-react#get-started-with-hydrogen-react',
+          subtitle: 'Tutorial',
+          name: 'Getting Started with Hydrogen React',
+          url: '/docs/custom-storefronts/hydrogen-react',
           type: 'tutorial',
         },
       ],
@@ -40,45 +40,63 @@ const data: LandingTemplateSchema = {
       type: 'Generic',
       anchorLink: 'authentication',
       title: 'Authentication',
-      sectionContent: `
-      To use Hydrogen React, you need to authenticate with and make requests to the [Storefront API](/api/storefront-api). Refer to [Get started with Hydrogen React](/custom-storefronts/hydrogen-react#get-started-with-hydrogen-react) for instructions on how to get an access token and set up the Storefront API client.
-       `,
+      sectionContent:
+        'To use Hydrogen React, you need to authenticate with and make requests to the [Storefront API](/docs/api/storefront). Hydrogen React includes an [API client](/docs/api/hydrogen-react/current/utilities/createstorefrontclient) to securely handle API queries and mutations.\n\nYou can create and manage Storefront API access tokens by installing the [Headless sales channel](https://apps.shopify.com/headless) on your store.\n\nApps have access to [two kinds of tokens](/docs/api/usage/authentication#access-tokens-for-the-storefront-api): a public API token, which can be used in client-side code, and a private API token, which should only be used in server-side contexts and never exposed publicly.',
       sectionCard: [
         {
-          subtitle: 'Navigate to',
-          name: 'Enable Storefront API Access',
-          url: '/custom-storefronts/hydrogen-react#step-2-enable-storefront-api-access',
-          type: 'key',
+          subtitle: 'Install',
+          name: 'Headless sales channel',
+          url: 'https://apps.shopify.com/headless',
+          type: 'apps',
         },
       ],
+      codeblock: {
+        title: 'Authenticate a Hydrogen app',
+        tabs: [
+          {
+            title: 'client.js',
+            code: 'authenticate.client.js',
+            language: 'javascript',
+          },
+          {
+            title: '.env',
+            code: 'authenticate.env.example',
+          },
+          {
+            title: 'server-side-query.js',
+            code: 'authenticate.server.js',
+            language: 'javascript',
+          },
+        ],
+      },
     },
     {
       type: 'Generic',
       anchorLink: 'versioning',
       title: 'Versioning',
       sectionContent:
-        "Hydrogen React is tied to specific versions of the [Storefront API](/api/storefront). For example, if you're using Storefront API version `2023-01`, then Hydrogen React versions `2023.1.x` are fully compatible. \n\n >Caution: \n>If the Storefront API version update includes breaking changes, then Hydrogen React includes breaking changes. Because the API version is updated every three months, breaking changes to Hydrogen React could occur every three months. \n\n Learn more about [API versioning](/api/usage/versioning).",
-      // sectionNotice: [
-      //   {
-      //     title: 'Caution',
-      //     type: 'warning',
-      //     sectionContent:
-      //       'If the Storefront API version update includes breaking changes, then Hydrogen React includes breaking changes. Because the API version is updated every three months, breaking changes to Hydrogen React could occur every three months.',
-      //   },
-      //   {
-      //     title: 'Learn more',
-      //     type: 'note',
-      //     sectionContent:
-      //       'Learn more about [API versioning](/api/usage/versioning).',
-      //   },
-      // ],
+        "Hydrogen React is tied to specific versions of the [Storefront API](/docs/api/storefront), which is versioned quarterly. For example, if you're using Storefront API version `2023-04`, then Hydrogen versions `2023.4.x` are fully compatible.\n\n> Caution:\n>If a Storefront API version includes breaking changes, then the corresponding Hydrogen React version will include the same breaking changes.",
+      sectionCard: [
+        {
+          subtitle: 'Learn more',
+          name: 'Shopify API versioning',
+          url: '/docs/api/usage/versioning',
+          type: 'tutorial',
+        },
+        {
+          subtitle: 'Learn more',
+          name: 'API release notes',
+          url: '/docs/api/release-notes',
+          type: 'changelog',
+        },
+      ],
     },
     {
       type: 'Generic',
       anchorLink: 'components',
       title: 'Components',
       sectionContent:
-        'A component encapsulates all of the business logic and data parsing/processing for the concept it represents and outputs limited, sensible markup. Components provide defaults, but allow customizations and provide no visual styles, other than those provided natively by the browser.',
+        'Components include all the business logic and data parsing required to produce predictable markup for objects available through the Storefront API. Components provide defaults but can be customized. Hydrogen React components include no visual styles, other than the ones provided natively by browsers.',
       codeblock: {
         title: 'Component example',
         tabs: [
@@ -95,7 +113,7 @@ const data: LandingTemplateSchema = {
       anchorLink: 'hooks',
       title: 'Hooks',
       sectionContent:
-        'Hooks are functions that provide reusable, business and/or stateful logic. These functions allow you to leverage the business logic and state management functions used in the components with more flexibility.',
+        'Hooks are functions that provide reusable business and/or state logic. They give you additional flexibility to control the behavior and display of Hydrogen React components.',
       codeblock: {
         title: 'Hook example',
         tabs: [
@@ -112,7 +130,7 @@ const data: LandingTemplateSchema = {
       anchorLink: 'utilities',
       title: 'Utilities',
       sectionContent:
-        'Utilities are reusable functions for common data manipulations performed on Storefront API data.',
+        'Utilities are reusable functions for common manipulations performed on data returned from the Storefront API.',
       codeblock: {
         title: 'Utility example',
         tabs: [
@@ -124,29 +142,51 @@ const data: LandingTemplateSchema = {
         ],
       },
     },
+    {
+      type: 'Generic',
+      anchorLink: 'with_hydrogen',
+      title: 'How Hydrogen React works with Hydrogen',
+      sectionContent:
+        'Hydrogen React is bundled as part of Hydrogen, Shopify’s opinionated headless commerce stack built on [Remix](https://remix.run). Hydrogen React is also published separately as a standalone package so that it can be used by other React-based frameworks.\n\nHydrogen adds features like standard routes, caching strategies, redirects, and SEO. When using Hydrogen, you can also install the Hydrogen sales channel, which includes built-in support for Oxygen, Shopify’s global edge hosting platform. Consider which approach works best for your use case and existing technology stack.',
+      sectionCard: [
+        {
+          subtitle: 'Learn more',
+          name: 'Hydrogen',
+          url: '/docs/custom-storefronts/hydrogen',
+          type: 'tutorial',
+        },
+        {
+          subtitle: 'Install',
+          name: 'Hydrogen sales channel',
+          url: 'https://apps.shopify.com/hydrogen',
+          type: 'hydrogen',
+        },
+      ],
+    },
     {
       type: 'Resource',
       anchorLink: 'resources',
       title: 'Resources',
       resources: [
         {
-          name: 'Custom Storefronts',
+          name: 'Custom storefronts on Shopify',
           subtitle:
-            'Learn more about how to design, build, and manage, your custom storefront.',
+            'Learn more about how to design, build, and manage custom storefronts on Shopify.',
           url: '/custom-storefronts',
           type: 'custom-storefronts',
         },
         {
-          name: 'Getting started guide',
-          subtitle: 'Follow this tutorial to get started with Hydrogen React.',
-          url: '/custom-storefronts/hydrogen-react#get-started-with-hydrogen-react',
-          type: 'quickstart',
+          name: 'Hydrogen on Discord',
+          subtitle:
+            'Chat with the growing community of commerce developers building with Hydrogen.',
+          url: 'https://discord.gg/shopifydevs',
+          type: 'discord',
         },
         {
-          name: 'Hydrogen React README',
+          name: 'Hydrogen on GitHub',
           subtitle:
-            'Get more details on how to improve your end-to-end development experience.',
-          url: 'https://github.com/Shopify/hydrogen/blob/main/packages/hydrogen-react/README.md',
+            'Follow the Hydrogen project, file bugs and feature requests, preview upcoming features, and more.',
+          url: 'https://github.com/Shopify/hydrogen',
           type: 'github',
         },
       ],