@okendo/shopify-hydrogen 1.0.3 → 1.2.1

package/README.md

@@ -1,628 +1,628 @@
-# Okendo Hydrogen React Components
-
-This is the React component library to support Okendo Widget Plus Widgets in Shopify Hydrogen Projects.
-
-Currently we provide the following components:
-
-### Server Components
-
-1. [Reviews List](#components--okendo-reviews-widget)
-2. [Star Ratings](#components--okendo-star-rating)
-
-### Client Components
-
-1. [Star Ratings](#components--okendo-client-star-rating)
-
-<br/>
-
-# Table of contents
-
-1. [What is Okendo Shopify Hydrogen](#introduction)
-2. [Guided Installation](#installation)
-   - [Configure Hydrogen App](#configure-hydrogen-app-config)
-   - [Expose Shopify Metafields](#expose-shopify-metafields)
-3. [How to Use Okendo Hydrogen Components In Your Hydrogen Apps](#how-to-use-okendo-hydrogen-components-in-your-hydrogen-app)
-4. [Components](#components)
-5. [GraphQL Fragments](#graphql-fragments)
-6. [View Our Okendo Sample Hydrogen App](#view-our-okendo-sample-hydrogen-app)
-
-<br/><br/>
-
-# What is Okendo Shopify Hydrogen? <a id="introduction" name="introduction"></a>
-
-Okendo Shopify Hydrogen is a React component library to be used in Shopify Hydrogen apps. This utilises [Shopify’s Hydrogen framework](https://shopify.dev/custom-storefronts/hydrogen/framework) which is used to create custom storefronts using both server-side rendered and client-side rendered React components.
-
-The purpose of this library is for a Hydrogen-based React Shopify storefront to import this library so that the Okendo Reviews List and Okendo Star Ratings components can be rendered within their React application, providing [Okendo’s reviews display functionality](https://www.okendo.io/blog/widget-plus/).
-
-<br/>
-
-# Guided Installation <a id="installation" name="installation"></a>
-
-The purpose of this documentation is to guide you on the following:
-
-- How to configure your Shopify store ready for Okendo Shopify Hydrogen.
-- How to install and configure Okendo Shopify Hydrogen components in your Shopify Hydrogen app.
-
-<br/>
-
-## Requirements
-
-- You have an existing Shopify store.
-- You have an existing Hydrogen app. ([Learn how to create a Hydrogen app](https://shopify.dev/custom-storefronts/hydrogen/getting-started/create))
-- You have a current Okendo Reviews subscription and have the **Okendo: Product Reviews & UCG** app installed and configured.
-- You have an existing Shopify custom app with Storefront access token. ([Learn how to configure Shopify Storefront](https://github.com/okendo/okendo-shopify-hydrogen-demo/wiki/Configure-Shopify-Storefront-API))
-
-<br/>
-
-## Configure Hydrogen app config <a id="configure-hydrogen-app-config" name="configure-hydrogen-app-config"></a>
-
-1. Open **hydrogen.config.ts** in your project.
-2. Make the following changes and save the file:
-   - Update `storeDomain` to specify your store's domain name.
-   - Update `storefrontToken` to specify your Storefront API access token.
-
-<br/>
-
-## Expose Shopify Metafields <a id="expose-shopify-metafields" name="expose-shopify-metafields"></a>
-
-Okendo Reviews utilise Product and Shop specific [metafields](https://shopify.dev/api/examples/metafields) in order to function and provide a seamless user experience. You will need to expose these metafields so that they can be retrieved by your Hydrogen app.
-
-At this point in time, unfortunately Shopify does not have a way of exposing Shop Metafields through their admin UI.
-
-The preferred method to expose Metafields is to [contact Okendo Support](mailto:support@okendo.io).
-
-<br/>
-
-### For Technical/Advanced Users
-
-<details>
-  <summary>Learn How to Expose Metafields Via The Storefront API</summary>
-
-## Exposing Metafields via GraphQL
-
-### Using Curl
-
-You can also expose the required Okendo Shopify Metafields by using GraphQL with curl.
-
-1. Open a new terminal or PowerShell window.
-2. Run the following command to expose the `WidgetPreRenderStyleTag` Shop Metafield.
-
-```bash
-curl -X POST \
-https://{shop}.myshopify.com/admin/api/2022-04/graphql.json \
--H 'Content-Type: application/graphql' \
--H 'X-Shopify-Access-Token: {access_token}' \
--d '
-mutation {
-  metafieldStorefrontVisibilityCreate(
-    input: {
-      namespace: "okendo"
-      key: "WidgetPreRenderStyleTags"
-      ownerType: SHOP
-    }
-  ) {
-    metafieldStorefrontVisibility {
-      id
-    }
-    userErrors {
-      field
-      message
-    }
-  }
-}
-'
-```
-
-3. Run the following command to expose the `WidgetPreRenderBodyStyleTags` Shop Metafield.
-
-```bash
-curl -X POST \
-https://{shop}.myshopify.com/admin/api/2022-04/graphql.json \
--H 'Content-Type: application/graphql' \
--H 'X-Shopify-Access-Token: {access_token}' \
--d '
-mutation {
-  metafieldStorefrontVisibilityCreate(
-    input: {
-      namespace: "okendo"
-      key: "WidgetPreRenderBodyStyleTags"
-      ownerType: SHOP
-    }
-  ) {
-    metafieldStorefrontVisibility {
-      id
-    }
-    userErrors {
-      field
-      message
-    }
-  }
-}
-'
-```
-
-4. Run the following command to expose the `ReviewsWidgetSnippet` Product Metafield.
-
-```bash
-curl -X POST \
-https://{shop}.myshopify.com/admin/api/2022-04/graphql.json \
--H 'Content-Type: application/graphql' \
--H 'X-Shopify-Access-Token: {access_token}' \
--d '
-mutation {
-  metafieldStorefrontVisibilityCreate(
-    input: {
-      namespace: "okendo"
-      key: "ReviewsWidgetSnippet"
-      ownerType: PRODUCT
-    }
-  ) {
-    metafieldStorefrontVisibility {
-      id
-    }
-    userErrors {
-      field
-      message
-    }
-  }
-}
-'
-```
-
-5. Run the following command to expose the `StarRatingSnippet` the Product Metafield.
-
-```bash
-curl -X POST \
-https://{shop}.myshopify.com/admin/api/2022-04/graphql.json \
--H 'Content-Type: application/graphql' \
--H 'X-Shopify-Access-Token: {access_token}' \
--d '
-mutation {
-  metafieldStorefrontVisibilityCreate(
-    input: {
-      namespace: "okendo"
-      key: "StarRatingSnippet"
-      ownerType: PRODUCT
-    }
-  ) {
-    metafieldStorefrontVisibility {
-      id
-    }
-    userErrors {
-      field
-      message
-    }
-  }
-}
-'
-```
-
-### Using GraphQL IDE
-
-1. Open your GraphQL IDE (such as Postman) and make a `POST` request with the following details:
-   - **URL:** https://{shop}.myshopify.com/admin/api/2022-04/graphql.json
-   - **Headers:** - X-Shopify-Access-Token: {access_token} - Content-Type: application/json
-2. Execute the following request to expose the `WidgetPreRenderStyleTag` Shop Metafield.
-
-```graphql
-mutation {
-  metafieldStorefrontVisibilityCreate(
-    input: {
-      namespace: "okendo"
-      key: "WidgetPreRenderStyleTags"
-      ownerType: SHOP
-    }
-  ) {
-    metafieldStorefrontVisibility {
-      id
-    }
-    userErrors {
-      field
-      message
-    }
-  }
-}
-```
-
-3. Execute the following request to expose the `WidgetPreRenderBodyStyleTags` Shop Metafield.
-
-```graphql
-mutation {
-  metafieldStorefrontVisibilityCreate(
-    input: {
-      namespace: "okendo"
-      key: "WidgetPreRenderBodyStyleTags"
-      ownerType: SHOP
-    }
-  ) {
-    metafieldStorefrontVisibility {
-      id
-    }
-    userErrors {
-      field
-      message
-    }
-  }
-}
-```
-
-4. Execute the following request to expose the `ReviewsWidgetSnippet` Product Metafield.
-
-```graphql
-mutation {
-  metafieldStorefrontVisibilityCreate(
-    input: {
-      namespace: "okendo"
-      key: "ReviewsWidgetSnippet"
-      ownerType: PRODUCT
-    }
-  ) {
-    metafieldStorefrontVisibility {
-      id
-    }
-    userErrors {
-      field
-      message
-    }
-  }
-}
-```
-
-5. Execute the following request to expose the `StarRatingSnippet` the Product Metafield.
-
-```graphql
-mutation {
-  metafieldStorefrontVisibilityCreate(
-    input: { namespace: "okendo", key: "StarRatingSnippet", ownerType: PRODUCT }
-  ) {
-    metafieldStorefrontVisibility {
-      id
-    }
-    userErrors {
-      field
-      message
-    }
-  }
-}
-```
-
-**References**
-
-- [https://shopify.dev/api/examples/metafields#step-1-expose-metafields](https://shopify.dev/api/examples/metafields#step-1-expose-metafields)
-- [https://shopify.dev/api/admin-graphql/2022-04/mutations/metafieldstorefrontvisibilitycreate](https://shopify.dev/api/admin-graphql/2022-04/mutations/metafieldstorefrontvisibilitycreate)
-</details>
-
-<br/><br/>
-
-# How to Use Okendo Hydrogen Components In Your Hydrogen App <a id="how-to-use-okendo-hydrogen-components-in-your-hydrogen-app" name="3-how-to-use-okendo-hydrogen-components-in-your-hydrogen-app"></a>
-
-## Installation
-
-1. In your Hydrogen app directory, run `npm install @okendo/shopify-hydrogen` inside a terminal or PowerShell window.
-2. **Optional:** Create (or add to) your `.env` file at the top level of your project (next to **hydrogen.config.ts**) the following, where `<your_subscriber_id>` is replaced with your Okendo Subscriber ID:
-
-   ```sh
-   # .env
-   VITE_OKENDO_SUBSCRIBER_ID=<your_subscriber_id>
-   ```
-
-3. Open **vite.config.ts** and add `import okendo from '@okendo/shopify-hydrogen/plugin';` to the list of imports.
-4. Add `okendo()` to the list of `plugins`.
-
-   ```tsx
-   /* vite.config.ts */
-   /// <reference types="vitest" />
-   import { defineConfig } from "vite";
-   import hydrogen from "@shopify/hydrogen/plugin";
-   import okendo from "@okendo/shopify-hydrogen/plugin";
-
-   export default defineConfig({
-     plugins: [hydrogen(), okendo()],
-     resolve: {
-       alias: [{ find: /^~\/(.*)/, replacement: "/src/$1" }],
-     },
-     optimizeDeps: {
-       include: ["@headlessui/react", "clsx", "react-use", "typographic-base"],
-     },
-     test: {
-       globals: true,
-       testTimeout: 10000,
-       hookTimeout: 10000,
-     },
-   });
-   ```
-
-5. Open **App.server.tsx** and import `OkendoProvider`.
-6. Include the `OkendoProvider` as shown below, passing through your `subscriberId` from your Vite environment variables.
-
-   ```tsx
-   /* App.server.tsx */
-   import {OkendoProvider} from '@okendo/shopify-hydrogen';
-
-   function App() {
-     return (
-       <Suspense fallback={<LoadingFallback />}>
-         <ShopifyProvider>
-           <!-- *** Include OkendoProvider HERE *** -->
-           <OkendoProvider
-             subscriberId={import.meta.env.VITE_OKENDO_SUBSCRIBER_ID}
-           />
-           <ServerCartProvider>
-             <DefaultSeo />
-             <Router>
-               <FileRoutes />
-               <Route path="*" page={<NotFound />} />
-             </Router>
-           </ServerCartProvider>
-           <PerformanceMetrics />
-           {import.meta.env.DEV && <PerformanceMetricsDebug />}
-         </ShopifyProvider>
-       </Suspense>
-     );
-   ```
-
-   If your app doesn't use Vite environment variables from a `.env` file, you could also provide your Okendo Subscriber ID through other means, i.e. directly:
-
-   ```tsx
-   <OkendoProvider subscriberId={okendoSubscriberId} />
-   ```
-
-## Widget Usage
-
-### Server Components
-
-Import `OkendoReviewsWidget` and `OkendoStarRating` and use as JSX components. Pass in the Shopify Product ID as a prop.
-
-The `productId` prop is optional for the `OkendoReviewsWidget`. Not providing it will mean that the widget will display reviews for all products, which is ideal for homepages or collection pages.
-
-```tsx
-import {
-  OkendoReviewsWidget,
-  OkendoStarRating,
-} from '@okendo/shopify-hydrogen';
-
-...
-
-const okendoReviewsWidget = <OkendoReviewsWidget productId={product.id} />;
-const okendoStarRating = <OkendoStarRating productId={product.id} />;
-```
-
-> ℹ️ &nbsp;Okendo `OkendoReviewsWidget` and `OkendoStarRating` widgets are server components. If you want to use them within a client component, you must pass the widget components as props to your client component. Widget components can be used directly in a server component. [Learn more here](#graphql-fragments).
-
-<br />
-
-### Client Components
-
-#### Star Rating Widget Usage in Client Components
-
-We also include an `OkendoClientStarRating` component for use within client-side (e.g.`<your component>.client.tsx`) components.
-
-Import the `OkendoClientStarRating` component inside a client component and use as a JSX component as seen below:
-
-```tsx
-import { OkendoClientStarRating } from '@okendo/shopify-hydrogen';
-
-...
-
-const okendoClientStarRating = <OkendoClientStarRating productId={product.id} />;
-```
-
-> ℹ️ &nbsp;OPTIONAL: You can render the `OkendoClientStarRating` component without making any client-side network requests by using an optional prop `okendoStarRatingSnippet`. This can be achieved using a GraphQL Fragment. [Learn more here](#graphql-fragments).
-
-<br />
-
-# Components <a id="components" name="components"></a>
-
-### OkendoProvider
-
-Top level component for enabling Okendo Widgets.
-
-We recommend using it directly inside the `<ShopifyProvider>` as its first child in **App.server.tsx**.
-
-It will provide:
-
-- Okendo Subscriber settings
-- Okendo widget CSS, including:
-  - Base variables
-  - Custom CSS specified in the Okendo Admin (if applicable)
-  - "Above the fold" CSS essential for Server-Side Rendered (SSR) widgets. This ensures styled widgets prior to client-side hydration.
-- Okendo widget initialisation script
-  - Used to render/hydrate widgets on the page
-
-| Name                                  | Type                                            | Description                                                                                                                                                                                                 | Required |
-| ------------------------------------- | ----------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
-| <code>subscriberId</code>             | <code>string</code>                             | The Okendo subscriber ID.                                                                                                                                                                                   | yes      |
-| <code>apiDomain</code>                | <code>string</code>                             | To override the default Okendo API Domain. (Default: <code>api.okendo.io/v1</code>)                                                                                                                         | no       |
-| <code>cdnDomain</code>                | <code>string</code>                             | To override the default Okendo CDN domain. (Default: <code>cdn-static.okendo.io</code>)                                                                                                                     | no       |
-| <code>productUrlFormatOverride</code> | <code>(product: ReviewProduct) => string</code> | By default, we use Hydrogen's out of the box product routing.<br />**Advanced Usage Only:** Function hook which allows the custom configuration of the Shopify product URLs from the Okendo Reviews Widget. | no       |
-
-### OkendoReviewsWidget<a id="components--okendo-reviews-widget" name="components--okendo-reviews-widget"></a>
-
-The Okendo Reviews List widget.
-
-| Name                   | Type                | Description                                                                                                                                                                                  | Required |
-| ---------------------- | ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
-| <code>productId</code> | <code>string</code> | The Shopify Product ID. If provided, the Reviews Widget will be configured to display reviews specific to that product. Otherwise, the Reviews Widget will display reviews for all products. | no       |
-
-### OkendoStarRating<a id="components--okendo-star-rating" name="components--okendo-star-rating"></a>
-
-The Okendo Star Rating widget - **For use in _server_ components**.
-
-| Name                   | Type                | Description             | Required |
-| ---------------------- | ------------------- | ----------------------- | -------- |
-| <code>productId</code> | <code>string</code> | The Shopify Product ID. | yes      |
-
-<br/>
-
-### OkendoClientStarRating<a id="components--okendo-client-star-rating" name="components--okendo-client-star-rating"></a>
-
-The Okendo Star Rating widget - **For use in _client_ components**.
-
-| Name                                 | Type                                               | Description                                                     | Required |
-| ------------------------------------ | -------------------------------------------------- | --------------------------------------------------------------- | -------- |
-| <code>productId</code>               | <code>string</code>                                | The Shopify Product ID.                                         | yes      |
-| <code>okendoStarRatingSnippet</code> | <code>Pick<Metafield, "value"> \| undefined</code> | The server-side pre-rendered markup representing a star snippet | no       |
-
-<br/>
-
----
-
-# GraphQL Fragments <a id="graphql-fragments" name="graphql-fragments"></a>
-
-A GraphQL fragment is a piece of logic that can be shared between multiple queries and mutations.
-
-We offer performance benefits even when using our client Star Rating Widget by exposing an `OKENDO_PRODUCT_STAR_RATING_FRAGMENT` GraphQL Fragment for use in your server components.
-
-This allows you to fetch pre-rendered markup in a **server component** for use within the client component (usually passed down as a property from the server component to the client).
-
-If the pre-rendered mark-up is present, the star rating widget initialization does not occur in the client, offering performance benefits.
-
-<br/>
-
-## Example: Using GraphQL Framgment with OkendoClientStarRating
-
-> ℹ️ &nbsp;NOTE: The following example usage is based on our Okendo Hydrogen Demo Store. Refer to the [Github repo](https://github.com/okendo/okendo-shopify-hydrogen-demo) to see a working example.
-
-<br/>
-
-In the sample [Okendo Hydrogen Demo Store](https://github.com/okendo/okendo-shopify-hydrogen-demo) we extend the `PRODUCT_CARD_FRAGMENT` with our `OKENDO_PRODUCT_STAR_RATING_FRAGMENT`.
-
-Open `ProductGrid.client.tsx` and make the changes to the `PRODUCT_CARD_FRAGMENT` as seen below:
-
-<br/>
-
-**Before**
-
-```tsx
-export const PRODUCT_CARD_FRAGMENT = gql`
-  fragment ProductCard on Product {
-    id
-    title
-    publishedAt
-    handle
-    variants(first: 1) {
-      nodes {
-        id
-        image {
-          url
-          altText
-          width
-          height
-        }
-        priceV2 {
-          amount
-          currencyCode
-        }
-        compareAtPriceV2 {
-          amount
-          currencyCode
-        }
-      }
-    }
-  }
-`;
-```
-
-**After**
-
-```tsx
-export const PRODUCT_CARD_FRAGMENT = gql`
-  ${OKENDO_PRODUCT_STAR_RATING_FRAGMENT}
-  fragment ProductCard on Product {
-    id
-    title
-    publishedAt
-    handle
-    ...OkendoStarRatingSnippet
-    variants(first: 1) {
-      nodes {
-        id
-        image {
-          url
-          altText
-          width
-          height
-        }
-        priceV2 {
-          amount
-          currencyCode
-        }
-        compareAtPriceV2 {
-          amount
-          currencyCode
-        }
-      }
-    }
-  }
-`;
-```
-
-Adding the `OKENDO_PRODUCT_STAR_RATING_FRAGMENT` GraphQL Fragment allows you to access and include an `okendoStarRatingSnippet` in your `Product` query.
-
-The `okendoStarRatingSnippet` is a server-side rendered version of the output of your star rating contents. This is supplied to your `Product`/`Collection` queries using the `OKENDO_PRODUCT_STAR_RATING_FRAGMENT` to fetch a metafield containg the markup.
-
-To help with typing we have exposed an `OkendoProductFragment` type which can be used as a union type with an existing Hydrogen `Product` type.
-
-For this example we have used `ProductCard.client.tsx` from our Okendo Hydrogen Demo App.
-
-The `ProductCard.client.tsx` component has the result of a server-side `useShopQuery` passed down as props to it.
-
-Because we have implemented our `OKENDO_PRODUCT_STAR_RATING_FRAGMENT` we can express the resulting type as a union:
-
-```tsx
-Product & OkendoProductFragment
-```
-
-In the `ProductCard.client.tsx` import the `OkendoProductFragment` type and the `OkendoClientStarRating` component:
-
-```tsx
-import type { OkendoProductFragment } from "@okendo/shopify-hydrogen";
-import { OkendoClientStarRating } from "@okendo/shopify-hydrogen/client";
-```
-
-The constructor of the `ProductCard.client.tsx` component can then be modified to use a union-type for the `Product` being passed in to the constructor:
-
-```tsx
-export function ProductCard({
-  product,
-  label,
-  className,
-  loading,
-  onClick,
-}: {
-  product: Product & OkendoProductFragment;
-  label?: string;
-  className?: string;
-  loading?: HTMLImageElement['loading'];
-  onClick?: () => void;
-}) {
-  ...
-}
-```
-
-Import the `OkendoClientStarRating` component inside the client component and use as seen below. Pass in `product.okendoStarRatingSnippet` as the value for the optional prop `okendoStarRatingSnippet`. This will use the pre-rendered value of the star rating markup without having to make any client-side network requests.
-
-```tsx
-{
-  product.okendoStarRatingSnippet?.value ? (
-    <OkendoClientStarRating
-      productId={product.id}
-      okendoStarRatingSnippet={product.okendoStarRatingSnippet}
-    />
-  ) : null;
-}
-```
-
-**References**
-
-- [GraphQL Fragments](https://www.apollographql.com/docs/react/data/fragments/)
-
----
-
-<br/>
-
-## View Our Okendo Sample Hydrogen App <a id="view-our-okendo-sample-hydrogen-app" name="view-our-okendo-sample-hydrogen-app"></a>
-
-We have created a Shopify Hydrogen sample application with our widgets pre-installed.
-
-- [View our Sample Okendo Shopify Hydrogen Demo Repository](https://github.com/okendo/okendo-shopify-hydrogen-demo)
+# Okendo Hydrogen React Components
+
+This is the React component library to support Okendo Widget Plus Widgets in Shopify Hydrogen Projects.
+
+Currently we provide the following components:
+
+### Server Components
+
+1. [Reviews List](#components--okendo-reviews-widget)
+2. [Star Ratings](#components--okendo-star-rating)
+
+### Client Components
+
+1. [Star Ratings](#components--okendo-client-star-rating)
+
+<br/>
+
+# Table of contents
+
+1. [What is Okendo Shopify Hydrogen](#introduction)
+2. [Guided Installation](#installation)
+   - [Configure Hydrogen App](#configure-hydrogen-app-config)
+   - [Expose Shopify Metafields](#expose-shopify-metafields)
+3. [How to Use Okendo Hydrogen Components In Your Hydrogen Apps](#how-to-use-okendo-hydrogen-components-in-your-hydrogen-app)
+4. [Components](#components)
+5. [GraphQL Fragments](#graphql-fragments)
+6. [View Our Okendo Sample Hydrogen App](#view-our-okendo-sample-hydrogen-app)
+
+<br/><br/>
+
+# What is Okendo Shopify Hydrogen? <a id="introduction" name="introduction"></a>
+
+Okendo Shopify Hydrogen is a React component library to be used in Shopify Hydrogen apps. This utilises [Shopify’s Hydrogen framework](https://shopify.dev/custom-storefronts/hydrogen/framework) which is used to create custom storefronts using both server-side rendered and client-side rendered React components.
+
+The purpose of this library is for a Hydrogen-based React Shopify storefront to import this library so that the Okendo Reviews List and Okendo Star Ratings components can be rendered within their React application, providing [Okendo’s reviews display functionality](https://www.okendo.io/blog/widget-plus/).
+
+<br/>
+
+# Guided Installation <a id="installation" name="installation"></a>
+
+The purpose of this documentation is to guide you on the following:
+
+- How to configure your Shopify store ready for Okendo Shopify Hydrogen.
+- How to install and configure Okendo Shopify Hydrogen components in your Shopify Hydrogen app.
+
+<br/>
+
+## Requirements
+
+- You have an existing Shopify store.
+- You have an existing Hydrogen app. ([Learn how to create a Hydrogen app](https://shopify.dev/custom-storefronts/hydrogen/getting-started/create))
+- You have a current Okendo Reviews subscription and have the **Okendo: Product Reviews & UCG** app installed and configured.
+- You have an existing Shopify custom app with Storefront access token. ([Learn how to configure Shopify Storefront](https://github.com/okendo/okendo-shopify-hydrogen-demo/wiki/Configure-Shopify-Storefront-API))
+
+<br/>
+
+## Configure Hydrogen app config <a id="configure-hydrogen-app-config" name="configure-hydrogen-app-config"></a>
+
+1. Open **hydrogen.config.ts** in your project.
+2. Make the following changes and save the file:
+   - Update `storeDomain` to specify your store's domain name.
+   - Update `storefrontToken` to specify your Storefront API access token.
+
+<br/>
+
+## Expose Shopify Metafields <a id="expose-shopify-metafields" name="expose-shopify-metafields"></a>
+
+Okendo Reviews utilise Product and Shop specific [metafields](https://shopify.dev/api/examples/metafields) in order to function and provide a seamless user experience. You will need to expose these metafields so that they can be retrieved by your Hydrogen app.
+
+At this point in time, unfortunately Shopify does not have a way of exposing Shop Metafields through their admin UI.
+
+The preferred method to expose Metafields is to [contact Okendo Support](mailto:support@okendo.io).
+
+<br/>
+
+### For Technical/Advanced Users
+
+<details>
+  <summary>Learn How to Expose Metafields Via The Storefront API</summary>
+
+## Exposing Metafields via GraphQL
+
+### Using Curl
+
+You can also expose the required Okendo Shopify Metafields by using GraphQL with curl.
+
+1. Open a new terminal or PowerShell window.
+2. Run the following command to expose the `WidgetPreRenderStyleTag` Shop Metafield.
+
+```bash
+curl -X POST \
+https://{shop}.myshopify.com/admin/api/2022-04/graphql.json \
+-H 'Content-Type: application/graphql' \
+-H 'X-Shopify-Access-Token: {access_token}' \
+-d '
+mutation {
+  metafieldStorefrontVisibilityCreate(
+    input: {
+      namespace: "okendo"
+      key: "WidgetPreRenderStyleTags"
+      ownerType: SHOP
+    }
+  ) {
+    metafieldStorefrontVisibility {
+      id
+    }
+    userErrors {
+      field
+      message
+    }
+  }
+}
+'
+```
+
+3. Run the following command to expose the `WidgetPreRenderBodyStyleTags` Shop Metafield.
+
+```bash
+curl -X POST \
+https://{shop}.myshopify.com/admin/api/2022-04/graphql.json \
+-H 'Content-Type: application/graphql' \
+-H 'X-Shopify-Access-Token: {access_token}' \
+-d '
+mutation {
+  metafieldStorefrontVisibilityCreate(
+    input: {
+      namespace: "okendo"
+      key: "WidgetPreRenderBodyStyleTags"
+      ownerType: SHOP
+    }
+  ) {
+    metafieldStorefrontVisibility {
+      id
+    }
+    userErrors {
+      field
+      message
+    }
+  }
+}
+'
+```
+
+4. Run the following command to expose the `ReviewsWidgetSnippet` Product Metafield.
+
+```bash
+curl -X POST \
+https://{shop}.myshopify.com/admin/api/2022-04/graphql.json \
+-H 'Content-Type: application/graphql' \
+-H 'X-Shopify-Access-Token: {access_token}' \
+-d '
+mutation {
+  metafieldStorefrontVisibilityCreate(
+    input: {
+      namespace: "okendo"
+      key: "ReviewsWidgetSnippet"
+      ownerType: PRODUCT
+    }
+  ) {
+    metafieldStorefrontVisibility {
+      id
+    }
+    userErrors {
+      field
+      message
+    }
+  }
+}
+'
+```
+
+5. Run the following command to expose the `StarRatingSnippet` the Product Metafield.
+
+```bash
+curl -X POST \
+https://{shop}.myshopify.com/admin/api/2022-04/graphql.json \
+-H 'Content-Type: application/graphql' \
+-H 'X-Shopify-Access-Token: {access_token}' \
+-d '
+mutation {
+  metafieldStorefrontVisibilityCreate(
+    input: {
+      namespace: "okendo"
+      key: "StarRatingSnippet"
+      ownerType: PRODUCT
+    }
+  ) {
+    metafieldStorefrontVisibility {
+      id
+    }
+    userErrors {
+      field
+      message
+    }
+  }
+}
+'
+```
+
+### Using GraphQL IDE
+
+1. Open your GraphQL IDE (such as Postman) and make a `POST` request with the following details:
+   - **URL:** https://{shop}.myshopify.com/admin/api/2022-04/graphql.json
+   - **Headers:** - X-Shopify-Access-Token: {access_token} - Content-Type: application/json
+2. Execute the following request to expose the `WidgetPreRenderStyleTag` Shop Metafield.
+
+```graphql
+mutation {
+  metafieldStorefrontVisibilityCreate(
+    input: {
+      namespace: "okendo"
+      key: "WidgetPreRenderStyleTags"
+      ownerType: SHOP
+    }
+  ) {
+    metafieldStorefrontVisibility {
+      id
+    }
+    userErrors {
+      field
+      message
+    }
+  }
+}
+```
+
+3. Execute the following request to expose the `WidgetPreRenderBodyStyleTags` Shop Metafield.
+
+```graphql
+mutation {
+  metafieldStorefrontVisibilityCreate(
+    input: {
+      namespace: "okendo"
+      key: "WidgetPreRenderBodyStyleTags"
+      ownerType: SHOP
+    }
+  ) {
+    metafieldStorefrontVisibility {
+      id
+    }
+    userErrors {
+      field
+      message
+    }
+  }
+}
+```
+
+4. Execute the following request to expose the `ReviewsWidgetSnippet` Product Metafield.
+
+```graphql
+mutation {
+  metafieldStorefrontVisibilityCreate(
+    input: {
+      namespace: "okendo"
+      key: "ReviewsWidgetSnippet"
+      ownerType: PRODUCT
+    }
+  ) {
+    metafieldStorefrontVisibility {
+      id
+    }
+    userErrors {
+      field
+      message
+    }
+  }
+}
+```
+
+5. Execute the following request to expose the `StarRatingSnippet` the Product Metafield.
+
+```graphql
+mutation {
+  metafieldStorefrontVisibilityCreate(
+    input: { namespace: "okendo", key: "StarRatingSnippet", ownerType: PRODUCT }
+  ) {
+    metafieldStorefrontVisibility {
+      id
+    }
+    userErrors {
+      field
+      message
+    }
+  }
+}
+```
+
+**References**
+
+- [https://shopify.dev/api/examples/metafields#step-1-expose-metafields](https://shopify.dev/api/examples/metafields#step-1-expose-metafields)
+- [https://shopify.dev/api/admin-graphql/2022-04/mutations/metafieldstorefrontvisibilitycreate](https://shopify.dev/api/admin-graphql/2022-04/mutations/metafieldstorefrontvisibilitycreate)
+</details>
+
+<br/><br/>
+
+# How to Use Okendo Hydrogen Components In Your Hydrogen App <a id="how-to-use-okendo-hydrogen-components-in-your-hydrogen-app" name="3-how-to-use-okendo-hydrogen-components-in-your-hydrogen-app"></a>
+
+## Installation
+
+1. In your Hydrogen app directory, run `npm install @okendo/shopify-hydrogen` inside a terminal or PowerShell window.
+2. **Optional:** Create (or add to) your `.env` file at the top level of your project (next to **hydrogen.config.ts**) the following, where `<your_subscriber_id>` is replaced with your Okendo Subscriber ID:
+
+   ```sh
+   # .env
+   VITE_OKENDO_SUBSCRIBER_ID=<your_subscriber_id>
+   ```
+
+3. Open **vite.config.ts** and add `import okendo from '@okendo/shopify-hydrogen/plugin';` to the list of imports.
+4. Add `okendo()` to the list of `plugins`.
+
+   ```tsx
+   /* vite.config.ts */
+   /// <reference types="vitest" />
+   import { defineConfig } from "vite";
+   import hydrogen from "@shopify/hydrogen/plugin";
+   import okendo from "@okendo/shopify-hydrogen/plugin";
+
+   export default defineConfig({
+     plugins: [hydrogen(), okendo()],
+     resolve: {
+       alias: [{ find: /^~\/(.*)/, replacement: "/src/$1" }],
+     },
+     optimizeDeps: {
+       include: ["@headlessui/react", "clsx", "react-use", "typographic-base"],
+     },
+     test: {
+       globals: true,
+       testTimeout: 10000,
+       hookTimeout: 10000,
+     },
+   });
+   ```
+
+5. Open **App.server.tsx** and import `OkendoProvider`.
+6. Include the `OkendoProvider` as shown below, passing through your `subscriberId` from your Vite environment variables.
+
+   ```tsx
+   /* App.server.tsx */
+   import {OkendoProvider} from '@okendo/shopify-hydrogen';
+
+   function App() {
+     return (
+       <Suspense fallback={<LoadingFallback />}>
+         <ShopifyProvider>
+           <!-- *** Include OkendoProvider HERE *** -->
+           <OkendoProvider
+             subscriberId={import.meta.env.VITE_OKENDO_SUBSCRIBER_ID}
+           />
+           <ServerCartProvider>
+             <DefaultSeo />
+             <Router>
+               <FileRoutes />
+               <Route path="*" page={<NotFound />} />
+             </Router>
+           </ServerCartProvider>
+           <PerformanceMetrics />
+           {import.meta.env.DEV && <PerformanceMetricsDebug />}
+         </ShopifyProvider>
+       </Suspense>
+     );
+   ```
+
+   If your app doesn't use Vite environment variables from a `.env` file, you could also provide your Okendo Subscriber ID through other means, i.e. directly:
+
+   ```tsx
+   <OkendoProvider subscriberId={okendoSubscriberId} />
+   ```
+
+## Widget Usage
+
+### Server Components
+
+Import `OkendoReviewsWidget` and `OkendoStarRating` and use as JSX components. Pass in the Shopify Product ID as a prop.
+
+The `productId` prop is optional for the `OkendoReviewsWidget`. Not providing it will mean that the widget will display reviews for all products, which is ideal for homepages or collection pages.
+
+```tsx
+import {
+  OkendoReviewsWidget,
+  OkendoStarRating,
+} from '@okendo/shopify-hydrogen';
+
+...
+
+const okendoReviewsWidget = <OkendoReviewsWidget productId={product.id} />;
+const okendoStarRating = <OkendoStarRating productId={product.id} />;
+```
+
+> ℹ️ &nbsp;Okendo `OkendoReviewsWidget` and `OkendoStarRating` widgets are server components. If you want to use them within a client component, you must pass the widget components as props to your client component. Widget components can be used directly in a server component. [Learn more here](#graphql-fragments).
+
+<br />
+
+### Client Components
+
+#### Star Rating Widget Usage in Client Components
+
+We also include an `OkendoClientStarRating` component for use within client-side (e.g.`<your component>.client.tsx`) components.
+
+Import the `OkendoClientStarRating` component inside a client component and use as a JSX component as seen below:
+
+```tsx
+import { OkendoClientStarRating } from '@okendo/shopify-hydrogen';
+
+...
+
+const okendoClientStarRating = <OkendoClientStarRating productId={product.id} />;
+```
+
+> ℹ️ &nbsp;OPTIONAL: You can render the `OkendoClientStarRating` component without making any client-side network requests by using an optional prop `okendoStarRatingSnippet`. This can be achieved using a GraphQL Fragment. [Learn more here](#graphql-fragments).
+
+<br />
+
+# Components <a id="components" name="components"></a>
+
+### OkendoProvider
+
+Top level component for enabling Okendo Widgets.
+
+We recommend using it directly inside the `<ShopifyProvider>` as its first child in **App.server.tsx**.
+
+It will provide:
+
+- Okendo Subscriber settings
+- Okendo widget CSS, including:
+  - Base variables
+  - Custom CSS specified in the Okendo Admin (if applicable)
+  - "Above the fold" CSS essential for Server-Side Rendered (SSR) widgets. This ensures styled widgets prior to client-side hydration.
+- Okendo widget initialisation script
+  - Used to render/hydrate widgets on the page
+
+| Name                                  | Type                                            | Description                                                                                                                                                                                                 | Required |
+| ------------------------------------- | ----------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
+| <code>subscriberId</code>             | <code>string</code>                             | The Okendo subscriber ID.                                                                                                                                                                                   | yes      |
+| <code>apiDomain</code>                | <code>string</code>                             | To override the default Okendo API Domain. (Default: <code>api.okendo.io/v1</code>)                                                                                                                         | no       |
+| <code>cdnDomain</code>                | <code>string</code>                             | To override the default Okendo CDN domain. (Default: <code>cdn-static.okendo.io</code>)                                                                                                                     | no       |
+| <code>productUrlFormatOverride</code> | <code>(product: ReviewProduct) => string</code> | By default, we use Hydrogen's out of the box product routing.<br />**Advanced Usage Only:** Function hook which allows the custom configuration of the Shopify product URLs from the Okendo Reviews Widget. | no       |
+
+### OkendoReviewsWidget<a id="components--okendo-reviews-widget" name="components--okendo-reviews-widget"></a>
+
+The Okendo Reviews List widget.
+
+| Name                   | Type                | Description                                                                                                                                                                                  | Required |
+| ---------------------- | ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
+| <code>productId</code> | <code>string</code> | The Shopify Product ID. If provided, the Reviews Widget will be configured to display reviews specific to that product. Otherwise, the Reviews Widget will display reviews for all products. | no       |
+
+### OkendoStarRating<a id="components--okendo-star-rating" name="components--okendo-star-rating"></a>
+
+The Okendo Star Rating widget - **For use in _server_ components**.
+
+| Name                   | Type                | Description             | Required |
+| ---------------------- | ------------------- | ----------------------- | -------- |
+| <code>productId</code> | <code>string</code> | The Shopify Product ID. | yes      |
+
+<br/>
+
+### OkendoClientStarRating<a id="components--okendo-client-star-rating" name="components--okendo-client-star-rating"></a>
+
+The Okendo Star Rating widget - **For use in _client_ components**.
+
+| Name                                 | Type                                               | Description                                                     | Required |
+| ------------------------------------ | -------------------------------------------------- | --------------------------------------------------------------- | -------- |
+| <code>productId</code>               | <code>string</code>                                | The Shopify Product ID.                                         | yes      |
+| <code>okendoStarRatingSnippet</code> | <code>Pick<Metafield, "value"> \| undefined</code> | The server-side pre-rendered markup representing a star snippet | no       |
+
+<br/>
+
+---
+
+# GraphQL Fragments <a id="graphql-fragments" name="graphql-fragments"></a>
+
+A GraphQL fragment is a piece of logic that can be shared between multiple queries and mutations.
+
+We offer performance benefits even when using our client Star Rating Widget by exposing an `OKENDO_PRODUCT_STAR_RATING_FRAGMENT` GraphQL Fragment for use in your server components.
+
+This allows you to fetch pre-rendered markup in a **server component** for use within the client component (usually passed down as a property from the server component to the client).
+
+If the pre-rendered mark-up is present, the star rating widget initialization does not occur in the client, offering performance benefits.
+
+<br/>
+
+## Example: Using GraphQL Framgment with OkendoClientStarRating
+
+> ℹ️ &nbsp;NOTE: The following example usage is based on our Okendo Hydrogen Demo Store. Refer to the [Github repo](https://github.com/okendo/okendo-shopify-hydrogen-demo) to see a working example.
+
+<br/>
+
+In the sample [Okendo Hydrogen Demo Store](https://github.com/okendo/okendo-shopify-hydrogen-demo) we extend the `PRODUCT_CARD_FRAGMENT` with our `OKENDO_PRODUCT_STAR_RATING_FRAGMENT`.
+
+Open `ProductGrid.client.tsx` and make the changes to the `PRODUCT_CARD_FRAGMENT` as seen below:
+
+<br/>
+
+**Before**
+
+```tsx
+export const PRODUCT_CARD_FRAGMENT = gql`
+  fragment ProductCard on Product {
+    id
+    title
+    publishedAt
+    handle
+    variants(first: 1) {
+      nodes {
+        id
+        image {
+          url
+          altText
+          width
+          height
+        }
+        priceV2 {
+          amount
+          currencyCode
+        }
+        compareAtPriceV2 {
+          amount
+          currencyCode
+        }
+      }
+    }
+  }
+`;
+```
+
+**After**
+
+```tsx
+export const PRODUCT_CARD_FRAGMENT = gql`
+  ${OKENDO_PRODUCT_STAR_RATING_FRAGMENT}
+  fragment ProductCard on Product {
+    id
+    title
+    publishedAt
+    handle
+    ...OkendoStarRatingSnippet
+    variants(first: 1) {
+      nodes {
+        id
+        image {
+          url
+          altText
+          width
+          height
+        }
+        priceV2 {
+          amount
+          currencyCode
+        }
+        compareAtPriceV2 {
+          amount
+          currencyCode
+        }
+      }
+    }
+  }
+`;
+```
+
+Adding the `OKENDO_PRODUCT_STAR_RATING_FRAGMENT` GraphQL Fragment allows you to access and include an `okendoStarRatingSnippet` in your `Product` query.
+
+The `okendoStarRatingSnippet` is a server-side rendered version of the output of your star rating contents. This is supplied to your `Product`/`Collection` queries using the `OKENDO_PRODUCT_STAR_RATING_FRAGMENT` to fetch a metafield containg the markup.
+
+To help with typing we have exposed an `OkendoProductFragment` type which can be used as a union type with an existing Hydrogen `Product` type.
+
+For this example we have used `ProductCard.client.tsx` from our Okendo Hydrogen Demo App.
+
+The `ProductCard.client.tsx` component has the result of a server-side `useShopQuery` passed down as props to it.
+
+Because we have implemented our `OKENDO_PRODUCT_STAR_RATING_FRAGMENT` we can express the resulting type as a union:
+
+```tsx
+Product & OkendoProductFragment
+```
+
+In the `ProductCard.client.tsx` import the `OkendoProductFragment` type and the `OkendoClientStarRating` component:
+
+```tsx
+import type { OkendoProductFragment } from "@okendo/shopify-hydrogen";
+import { OkendoClientStarRating } from "@okendo/shopify-hydrogen/client";
+```
+
+The constructor of the `ProductCard.client.tsx` component can then be modified to use a union-type for the `Product` being passed in to the constructor:
+
+```tsx
+export function ProductCard({
+  product,
+  label,
+  className,
+  loading,
+  onClick,
+}: {
+  product: Product & OkendoProductFragment;
+  label?: string;
+  className?: string;
+  loading?: HTMLImageElement['loading'];
+  onClick?: () => void;
+}) {
+  ...
+}
+```
+
+Import the `OkendoClientStarRating` component inside the client component and use as seen below. Pass in `product.okendoStarRatingSnippet` as the value for the optional prop `okendoStarRatingSnippet`. This will use the pre-rendered value of the star rating markup without having to make any client-side network requests.
+
+```tsx
+{
+  product.okendoStarRatingSnippet?.value ? (
+    <OkendoClientStarRating
+      productId={product.id}
+      okendoStarRatingSnippet={product.okendoStarRatingSnippet}
+    />
+  ) : null;
+}
+```
+
+**References**
+
+- [GraphQL Fragments](https://www.apollographql.com/docs/react/data/fragments/)
+
+---
+
+<br/>
+
+## View Our Okendo Sample Hydrogen App <a id="view-our-okendo-sample-hydrogen-app" name="view-our-okendo-sample-hydrogen-app"></a>
+
+We have created a Shopify Hydrogen sample application with our widgets pre-installed.
+
+- [View our Sample Okendo Shopify Hydrogen Demo Repository](https://github.com/okendo/okendo-shopify-hydrogen-demo)