@okendo/shopify-hydrogen 1.3.1 → 2.0.0

package/README.md

@@ -1,95 +1,48 @@
-### ⚠️ Shopify [has deprecated Hydrogen v1](https://hydrogen.shopify.dev/updates) ⚠️ — Please use [the latest version of this package](https://www.npmjs.com/package/@okendo/shopify-hydrogen) if your store is built with Hydrogen v2 (based on Remix).
+> Note: this package is to be used on stores built with Hydrogen v2, based on Remix. If your store is built with the now deprecated Hydrogen v1, please use [version 1 of this package](https://www.npmjs.com/package/@okendo/shopify-hydrogen/v/1.3.0).
 
-### ⚠️ Only use the following if you are using a legacy Hydrogen v1 store ⚠️
+# Okendo Hydrogen 2 (Remix) React Components
 
-# 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/>
+This package brings [Okendo's review widgets](https://www.okendo.io/blog/widget-plus/) to a Shopify Hydrogen store.
 
 ## 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))
+- A Shopify store with the **Okendo: Product Reviews & UCG** app installed and configured.
+- A current Okendo subscription.
+- A [Storefront access token](https://github.com/okendo/okendo-shopify-hydrogen-demo/wiki/Configure-Shopify-Storefront-API).
+- A [Shopify Hydrogen](https://hydrogen.shopify.dev/) app.
 
-<br/>
+## Demo Store
 
-## Configure Hydrogen app config <a id="configure-hydrogen-app-config" name="configure-hydrogen-app-config"></a>
+Our demo store, which is based on the demo store provided by Shopify, can be found [here](https://github.com/okendo/okendo-shopify-hydrogen-demo).
 
-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.
+## How it works
 
-<br/>
+This package provides:
 
-## Expose Shopify Metafields <a id="expose-shopify-metafields" name="expose-shopify-metafields"></a>
+- one function: `getOkendoProviderData`
+- three React components: `OkendoProvider`, `OkendoStarRating`, and `OkendoReviews`
 
-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.
+The function `getOkendoProviderData` needs to be called in the `loader` function of the `root.tsx` file in the Hydrogen 2 store. The data is then retrieved in `App` through `useLoaderData` and provided to `OkendoProvider` which is added in the `body` of the HTML returned by `App`.
 
-At this point in time, unfortunately Shopify does not have a way of exposing Shop Metafields through their admin UI.
+Then the components `OkendoStarRating` and `OkendoReviews` can be added on the store pages. There are a few more bits of configuration to do, please see below.
 
-The preferred method to expose Metafields is to [contact Okendo Support](mailto:support@okendo.io).
+## Expose Shopify Metafields <a id="expose-shopify-metafields" name="expose-shopify-metafields"></a>
 
-<br/>
+Okendo Reviews use Product and Shop [metafields](https://shopify.dev/api/examples/metafields). You will need to expose these metafields so that they can be retrieved by your Hydrogen app.
 
-### For Technical/Advanced Users
+At the moment, Shopify does not have a way of exposing Shop Metafields through their admin UI, so the preferred method is to [contact Okendo Support](mailto:support@okendo.io).
 
 <details>
-  <summary>Learn How to Expose Metafields Via The Storefront API</summary>
+	<summary>For technical users, follow this method to expose metafields via the storefront API</summary>
 
-## Exposing Metafields via GraphQL
+### Exposing Metafields via GraphQL
 
-### Using Curl
+#### Using Curl
 
-You can also expose the required Okendo Shopify Metafields by using GraphQL with 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.
+2. Run the following command to expose the `WidgetPreRenderStyleTags` shop metafield:
 
 ```bash
 curl -X POST \
@@ -98,26 +51,26 @@ https://{shop}.myshopify.com/admin/api/2022-04/graphql.json \
 -H 'X-Shopify-Access-Token: {access_token}' \
 -d '
 mutation {
-  metafieldStorefrontVisibilityCreate(
-    input: {
-      namespace: "okendo"
-      key: "WidgetPreRenderStyleTags"
-      ownerType: SHOP
-    }
-  ) {
-    metafieldStorefrontVisibility {
-      id
-    }
-    userErrors {
-      field
-      message
-    }
-  }
+	metafieldStorefrontVisibilityCreate(
+		input: {
+			namespace: "okendo"
+			key: "WidgetPreRenderStyleTags"
+			ownerType: SHOP
+		}
+	) {
+		metafieldStorefrontVisibility {
+			id
+		}
+		userErrors {
+			field
+			message
+		}
+	}
 }
 '
 ```
 
-3. Run the following command to expose the `WidgetPreRenderBodyStyleTags` Shop Metafield.
+3. Run the following command to expose the `WidgetPreRenderBodyStyleTags` shop metafield:
 
 ```bash
 curl -X POST \
@@ -126,26 +79,26 @@ https://{shop}.myshopify.com/admin/api/2022-04/graphql.json \
 -H 'X-Shopify-Access-Token: {access_token}' \
 -d '
 mutation {
-  metafieldStorefrontVisibilityCreate(
-    input: {
-      namespace: "okendo"
-      key: "WidgetPreRenderBodyStyleTags"
-      ownerType: SHOP
-    }
-  ) {
-    metafieldStorefrontVisibility {
-      id
-    }
-    userErrors {
-      field
-      message
-    }
-  }
+	metafieldStorefrontVisibilityCreate(
+		input: {
+			namespace: "okendo"
+			key: "WidgetPreRenderBodyStyleTags"
+			ownerType: SHOP
+		}
+	) {
+		metafieldStorefrontVisibility {
+			id
+		}
+		userErrors {
+			field
+			message
+		}
+	}
 }
 '
 ```
 
-4. Run the following command to expose the `ReviewsWidgetSnippet` Product Metafield.
+4. Run the following command to expose the `ReviewsWidgetSnippet` product metafield:
 
 ```bash
 curl -X POST \
@@ -154,26 +107,26 @@ https://{shop}.myshopify.com/admin/api/2022-04/graphql.json \
 -H 'X-Shopify-Access-Token: {access_token}' \
 -d '
 mutation {
-  metafieldStorefrontVisibilityCreate(
-    input: {
-      namespace: "okendo"
-      key: "ReviewsWidgetSnippet"
-      ownerType: PRODUCT
-    }
-  ) {
-    metafieldStorefrontVisibility {
-      id
-    }
-    userErrors {
-      field
-      message
-    }
-  }
+	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.
+5. Run the following command to expose the `StarRatingSnippet` the product metafield:
 
 ```bash
 curl -X POST \
@@ -182,21 +135,21 @@ https://{shop}.myshopify.com/admin/api/2022-04/graphql.json \
 -H 'X-Shopify-Access-Token: {access_token}' \
 -d '
 mutation {
-  metafieldStorefrontVisibilityCreate(
-    input: {
-      namespace: "okendo"
-      key: "StarRatingSnippet"
-      ownerType: PRODUCT
-    }
-  ) {
-    metafieldStorefrontVisibility {
-      id
-    }
-    userErrors {
-      field
-      message
-    }
-  }
+	metafieldStorefrontVisibilityCreate(
+		input: {
+			namespace: "okendo"
+			key: "StarRatingSnippet"
+			ownerType: PRODUCT
+		}
+	) {
+		metafieldStorefrontVisibility {
+			id
+		}
+		userErrors {
+			field
+			message
+		}
+	}
 }
 '
 ```
@@ -204,89 +157,91 @@ mutation {
 ### 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.
+
+- **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 `WidgetPreRenderStyleTags` shop metafield:
 
 ```graphql
 mutation {
-  metafieldStorefrontVisibilityCreate(
-    input: {
-      namespace: "okendo"
-      key: "WidgetPreRenderStyleTags"
-      ownerType: SHOP
-    }
-  ) {
-    metafieldStorefrontVisibility {
-      id
-    }
-    userErrors {
-      field
-      message
-    }
-  }
+	metafieldStorefrontVisibilityCreate(
+		input: {
+			namespace: "okendo"
+			key: "WidgetPreRenderStyleTags"
+			ownerType: SHOP
+		}
+	) {
+		metafieldStorefrontVisibility {
+			id
+		}
+		userErrors {
+			field
+			message
+		}
+	}
 }
 ```
 
-3. Execute the following request to expose the `WidgetPreRenderBodyStyleTags` Shop Metafield.
+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
-    }
-  }
+	metafieldStorefrontVisibilityCreate(
+		input: {
+			namespace: "okendo"
+			key: "WidgetPreRenderBodyStyleTags"
+			ownerType: SHOP
+		}
+	) {
+		metafieldStorefrontVisibility {
+			id
+		}
+		userErrors {
+			field
+			message
+		}
+	}
 }
 ```
 
-4. Execute the following request to expose the `ReviewsWidgetSnippet` Product Metafield.
+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
-    }
-  }
+	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.
+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
-    }
-  }
+	metafieldStorefrontVisibilityCreate(
+		input: { namespace: "okendo", key: "StarRatingSnippet", ownerType: PRODUCT }
+	) {
+		metafieldStorefrontVisibility {
+			id
+		}
+		userErrors {
+			field
+			message
+		}
+	}
 }
 ```
 
@@ -296,337 +251,290 @@ mutation {
 - [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@^1` 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';
+> The code examples provided in this section are based on the [demo store provided by Shopify](https://github.com/Shopify/hydrogen/tree/2023-01/templates/demo-store). You will find the following steps already done in [our demo store](https://github.com/okendo/okendo-shopify-hydrogen-demo).
 
-...
+Run:
 
-const okendoReviewsWidget = <OkendoReviewsWidget productId={product.id} />;
-const okendoStarRating = <OkendoStarRating productId={product.id} />;
+```bash
+npm i @okendo/shopify-hydrogen
 ```
 
-> ℹ️ &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.
+### `app/root.tsx`
 
-Import the `OkendoClientStarRating` component inside a client component and use as a JSX component as seen below:
+Open `app/root.tsx` and add the following import:
 
-```tsx
-import { OkendoClientStarRating } from '@okendo/shopify-hydrogen';
-
-...
-
-const okendoClientStarRating = <OkendoClientStarRating productId={product.id} />;
+```ts
+import {
+	OkendoProvider,
+	getOkendoProviderData,
+} from "@okendo/shopify-hydrogen";
 ```
 
-> ℹ️ &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:
+Locate the `meta` function, and append the property `oke:subscriber_id` containing your Okendo subscriber ID:
 
-- 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      |
+```ts
+	'oke:subscriber_id': '<your-okendo-subscriber-id>',
+```
 
-<br/>
+The `meta` function should now look like the following:
 
-### OkendoClientStarRating<a id="components--okendo-client-star-rating" name="components--okendo-client-star-rating"></a>
+```ts
+export const meta: MetaFunction = () => ({
+	charset: "utf-8",
+	viewport: "width=device-width,initial-scale=1",
+	"oke:subscriber_id": "<your-okendo-subscriber-id>",
+});
+```
 
-The Okendo Star Rating widget - **For use in _client_ components**.
+Locate the `loader` function and append the `okendoProviderData` property to the returned data:
 
-| 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       |
+```ts
+okendoProviderData: await getOkendoProviderData({
+	context,
+	subscriberId: '<your-okendo-subscriber-id>',
+}),
+```
 
-<br/>
+The `loader` function returned data should now look like the following:
+
+```ts
+return defer({
+	isLoggedIn: Boolean(customerAccessToken),
+	layout,
+	selectedLocale: context.storefront.i18n,
+	cart: cartId ? getCart(context, cartId) : undefined,
+	analytics: {
+		shopifySalesChannel: ShopifySalesChannel.hydrogen,
+		shopId: layout.shop.id,
+	},
+	seo,
+	okendoProviderData: await getOkendoProviderData({
+		context,
+		subscriberId: "<your-okendo-subscriber-id>",
+	}),
+});
+```
 
----
+Locate the `App` function, append `OkendoProvider` to `body`, and provide it with the data returned by `getOkendoProviderData`:
 
-# GraphQL Fragments <a id="graphql-fragments" name="graphql-fragments"></a>
+```tsx
+...
+<body>
+	<OkendoProvider okendoProviderData={data.okendoProviderData} />
+	...
+</body>
+...
+```
 
-A GraphQL fragment is a piece of logic that can be shared between multiple queries and mutations.
+### `app/data/fragments.ts`
 
-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.
+Open `app/data/fragments.ts` and add the following import:
 
-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).
+```ts
+import { OKENDO_PRODUCT_STAR_RATING_FRAGMENT } from "@okendo/shopify-hydrogen";
+```
 
-If the pre-rendered mark-up is present, the star rating widget initialization does not occur in the client, offering performance benefits.
+Then add `${OKENDO_PRODUCT_STAR_RATING_FRAGMENT}` and `...OkendoStarRatingSnippet` to `PRODUCT_CARD_FRAGMENT`:
+
+```ts
+export const PRODUCT_CARD_FRAGMENT = `#graphql
+	${OKENDO_PRODUCT_STAR_RATING_FRAGMENT}
+	fragment ProductCard on Product {
+		id
+		title
+		publishedAt
+		handle
+		...OkendoStarRatingSnippet
+		variants(first: 1) {
+		...
+```
 
-<br/>
+### `app/components/ProductCard.tsx`
 
-## Example: Using GraphQL Framgment with OkendoClientStarRating
+Open `app/components/ProductCard.tsx` and add the following import:
 
-> ℹ️ &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.
+```ts
+import {
+	OkendoStarRating,
+	WithOkendoStarRatingSnippet,
+} from "@okendo/shopify-hydrogen";
+```
 
-<br/>
+Tweak the type of the `product` prop to be:
 
-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`.
+```ts
+product: SerializeFrom<Product & WithOkendoStarRatingSnippet>;
+```
 
-Open `ProductGrid.client.tsx` and make the changes to the `PRODUCT_CARD_FRAGMENT` as seen below:
+`ProductCard` should now look like this:
 
-<br/>
+```ts
+export function ProductCard({
+	product,
+	label,
+	className,
+	loading,
+	onClick,
+	quickAdd,
+}: {
+	product: SerializeFrom<Product & WithOkendoStarRatingSnippet>;
+	label?: string;
+	className?: string;
+	loading?: HTMLImageElement['loading'];
+	onClick?: () => void;
+	quickAdd?: boolean;
+}) {
+```
 
-**Before**
+Add the `OkendoStarRating` component:
 
 ```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
-        }
-      }
-    }
-  }
-`;
+<OkendoStarRating
+	productId={product.id}
+	okendoStarRatingSnippet={product.okendoStarRatingSnippet}
+/>
 ```
 
-**After**
+For instance, you can add it below the product title, like this:
 
 ```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
-        }
-      }
-    }
-  }
-`;
+<Text
+	className="w-full overflow-hidden whitespace-nowrap text-ellipsis "
+	as="h3"
+>
+	{product.title}
+</Text>
+<OkendoStarRating
+	productId={product.id}
+	okendoStarRatingSnippet={product.okendoStarRatingSnippet}
+/>
 ```
 
-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.
+### `app/routes/($lang)/products/$productHandle.tsx`
 
-To help with typing we have exposed an `OkendoProductFragment` type which can be used as a union type with an existing Hydrogen `Product` type.
+Open `app/routes/($lang)/products/$productHandle.tsx` and add the following imports:
 
-For this example we have used `ProductCard.client.tsx` from our Okendo Hydrogen Demo App.
+```ts
+import {
+	OkendoReviews,
+	OkendoStarRating,
+	WithOkendoStarRatingSnippet,
+	WithOkendoReviewsSnippet,
+	OKENDO_PRODUCT_STAR_RATING_FRAGMENT,
+	OKENDO_PRODUCT_REVIEWS_FRAGMENT,
+} from "@okendo/shopify-hydrogen";
+```
 
-The `ProductCard.client.tsx` component has the result of a server-side `useShopQuery` passed down as props to it.
+In the storefront query, tweak the type of `product` to be:
 
-Because we have implemented our `OKENDO_PRODUCT_STAR_RATING_FRAGMENT` we can express the resulting type as a union:
+```ts
+product: ProductType & {
+	selectedVariant?: ProductVariant;
+} & WithOkendoStarRatingSnippet &
+	WithOkendoReviewsSnippet;
+```
 
-```tsx
-Product & OkendoProductFragment
+The storefront query should now look like this:
+
+```ts
+const { shop, product } = await context.storefront.query<{
+	product: ProductType & {
+		selectedVariant?: ProductVariant;
+	} & WithOkendoStarRatingSnippet &
+		WithOkendoReviewsSnippet;
+	shop: Shop;
+}>(PRODUCT_QUERY, {
+	variables: {
+		handle: productHandle,
+		selectedOptions,
+		country: context.storefront.i18n.country,
+		language: context.storefront.i18n.language,
+	},
+});
 ```
 
-In the `ProductCard.client.tsx` import the `OkendoProductFragment` type and the `OkendoClientStarRating` component:
+Add the `OkendoStarRating` component:
 
 ```tsx
-import type { OkendoProductFragment } from "@okendo/shopify-hydrogen";
-import { OkendoClientStarRating } from "@okendo/shopify-hydrogen/client";
+<OkendoStarRating
+	productId={product.id}
+	okendoStarRatingSnippet={product.okendoStarRatingSnippet}
+/>
 ```
 
-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:
+For instance, you can add it between the product title and the store name, like this:
 
 ```tsx
-export function ProductCard({
-  product,
-  label,
-  className,
-  loading,
-  onClick,
-}: {
-  product: Product & OkendoProductFragment;
-  label?: string;
-  className?: string;
-  loading?: HTMLImageElement['loading'];
-  onClick?: () => void;
-}) {
-  ...
-}
+<Heading as="h1" className="whitespace-normal">
+	{title}
+</Heading>
+<OkendoStarRating
+	productId={product.id}
+	okendoStarRatingSnippet={product.okendoStarRatingSnippet}
+/>
+{vendor && (
+	<Text className={'opacity-50 font-medium'}>{vendor}</Text>
+)}
 ```
 
-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.
+Add the `OkendoReviews` component:
 
 ```tsx
-{
-  product.okendoStarRatingSnippet?.value ? (
-    <OkendoClientStarRating
-      productId={product.id}
-      okendoStarRatingSnippet={product.okendoStarRatingSnippet}
-    />
-  ) : null;
-}
+<OkendoReviews
+	productId={product.id}
+	okendoReviewsSnippet={product.okendoReviewsSnippet}
+/>
 ```
 
-**References**
-
-- [GraphQL Fragments](https://www.apollographql.com/docs/react/data/fragments/)
+For instance, you can add it below the product section:
 
----
-
-<br/>
+```tsx
+...
+</Section>
+<OkendoReviews
+	productId={product.id}
+	okendoReviewsSnippet={product.okendoReviewsSnippet}
+/>
+<Suspense fallback={<Skeleton className="h-32" />}>
+...
+```
 
-## View Our Okendo Sample Hydrogen App <a id="view-our-okendo-sample-hydrogen-app" name="view-our-okendo-sample-hydrogen-app"></a>
+Locate `PRODUCT_QUERY` and add the following to it:
 
-We have created a Shopify Hydrogen sample application with our widgets pre-installed.
+```ts
+	...
+	${OKENDO_PRODUCT_STAR_RATING_FRAGMENT}
+	${OKENDO_PRODUCT_REVIEWS_FRAGMENT}
+	...
+			...OkendoStarRatingSnippet
+			...OkendoReviewsSnippet
+```
 
-- [View our Sample Okendo Shopify Hydrogen Demo Repository](https://github.com/okendo/okendo-shopify-hydrogen-demo)
+It should now look like this:
+
+```ts
+const PRODUCT_QUERY = `#graphql
+	${MEDIA_FRAGMENT}
+	${PRODUCT_VARIANT_FRAGMENT}
+	${OKENDO_PRODUCT_STAR_RATING_FRAGMENT}
+	${OKENDO_PRODUCT_REVIEWS_FRAGMENT}
+query Product(
+		$country: CountryCode
+		$language: LanguageCode
+		$handle: String!
+		$selectedOptions: [SelectedOptionInput!]!
+	) @inContext(country: $country, language: $language) {
+		product(handle: $handle) {
+			id
+			title
+			vendor
+			handle
+			descriptionHtml
+			description
+			...OkendoStarRatingSnippet
+			...OkendoReviewsSnippet
+			options {
+			...
+```