@okendo/shopify-hydrogen 2.4.0 → 2.5.0

package/README.md

@@ -1,15 +1,15 @@
-> Note: this package is to be used on stores built with Hydrogen v2, based on Remix. If your store is built with the deprecated Hydrogen v1, please use the [version 1](https://www.npmjs.com/package/@okendo/shopify-hydrogen/v/1.6.6) of this package.
+> **Note**: this package is to be used on stores built with **Shopify Hydrogen v2**. If your store is built with the deprecated Shopify Hydrogen v1, please use the [version 1](https://www.npmjs.com/package/@okendo/shopify-hydrogen/v/1.6.6) of this package.
 
-# Okendo Hydrogen 2 (Remix) React Components
+> **Note**: the new version of Shopify Hydrogen v2 uses **React Router**. Previous versions used **Remix**. If your store is built with Remix, please use [version `2.4`](https://www.npmjs.com/package/@okendo/shopify-hydrogen/v/2.4.0) of this package.
 
-This package brings [Okendo's review widgets](https://www.okendo.io/blog/widget-plus/) and [Loyalty widgets](https://okendo.io/loyalty/) to a Shopify Hydrogen store.
+# Okendo Hydrogen (React Router) React Components
+
+This package brings Okendo's [Reviews widgets](https://okendo.io/reviews) and [Loyalty widgets](https://okendo.io/loyalty) to a Shopify Hydrogen store.
 
 ## Requirements
 
-- A Shopify store with the [**Okendo: Product Reviews & UCG**](https://apps.shopify.com/okendo-reviews) app installed and configured.
-- For existing merchants, your store must be upgraded to Okendo's Widget Plus widgets. It is free to upgrade. For more information please [contact Okendo Support](mailto:support@okendo.io).
-- A current Okendo subscription.
-- A [Shopify Hydrogen](https://hydrogen.shopify.dev/) app.
+- A Shopify store with a [Hydrogen](https://hydrogen.shopify.dev/) storefront and [Okendo](https://apps.shopify.com/okendo-reviews) installed and configured.
+- For existing merchants, your store must be using Okendo's Widget Plus widgets. [Contact us](mailto:support@okendo.io) if it's not the case, it's free to upgrade.
 
 ## Demo Store
 
@@ -17,418 +17,17 @@ Our demo store, which is based on the demo store provided by Shopify, can be fou
 
 > Note: there have been multiple versions of Shopify's Hydrogen demo store. If your project is based on an old version of it, consult the [history of our demo store's repository](https://github.com/okendo/okendo-shopify-hydrogen-demo/commits/master/).
 
-## Exposition of Shopify Metafields <a id="expose-shopify-metafields" name="expose-shopify-metafields"></a>
-
-Okendo Reviews use Product and Shop [metafields](https://help.shopify.com/en/manual/custom-data/metafields). You will need to expose these metafields so that they can be retrieved by your Hydrogen app.
-
-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's Support](mailto:support@okendo.io).
-
-<details>
-
-<summary>If you're a technical user however, you can click here and follow the method to expose the metafields via the storefront API.</summary>
-
-### Exposing Metafields via GraphQL
-
-You will need a **Storefront access token** with the following API access scopes:
-
-```
-unauthenticated_read_content
-unauthenticated_read_customers
-unauthenticated_read_product_listings
-unauthenticated_read_product_inventory
-unauthenticated_read_product_pickup_locations
-unauthenticated_read_product_tags
-```
-
-Follow the instructions on [this page](https://help.shopify.com/en/manual/apps/app-types/custom-apps#create-and-install-a-custom-app) to create it.
-
-#### Using Curl
-
-> Note: The settings metafields exist within the Okendo App's Reserved Namespace. To access these metafields we need to include the Okendo App ID (`app--1576377`) as a prefix in the `namespace` field.
-
-Open a new terminal or PowerShell window, then:
-
-1. Run the following command to expose the `widget_pre_render_style_tags` shop metafield:
-
-```bash
-curl -X POST \
-https://{shop}.myshopify.com/admin/api/2024-10/graphql.json \
--H 'Content-Type: application/graphql' \
--H 'X-Shopify-Access-Token: {access_token}' \
--d '
-mutation {
-	metafieldDefinitionCreate(
-		definition: {
-			name: "WidgetPreRenderStyleTags"
-            namespace: "app--1576377--reviews"
-			key: "widget_pre_render_style_tags"
-			type: "multi_line_text_field"
-			ownerType: SHOP
-			access: {
-				admin: PUBLIC_READ
-				storefront: PUBLIC_READ
-			}
-		}
-	) {
-		createdDefinition { id name }
-		userErrors { field message code }
-	}
-}
-'
-```
-
-2. Run the following command to expose the `widget_pre_render_body_style_tags` shop metafield:
-
-```bash
-curl -X POST \
-https://{shop}.myshopify.com/admin/api/2024-10/graphql.json \
--H 'Content-Type: application/graphql' \
--H 'X-Shopify-Access-Token: {access_token}' \
--d '
-mutation {
-	metafieldDefinitionCreate(
-		definition: {
-			name: "WidgetPreRenderBodyStyleTags"
-            namespace: "app--1576377--reviews"
-			key: "widget_pre_render_body_style_tags"
-			type: "multi_line_text_field"
-			ownerType: SHOP
-			access: {
-				admin: PUBLIC_READ
-				storefront: PUBLIC_READ
-			}
-		}
-	) {
-		createdDefinition { id name }
-		userErrors { field message code }
-	}
-}
-'
-```
-
-3. Run the following command to expose the `reviews_widget_snippet` product metafield:
-
-```bash
-curl -X POST \
-https://{shop}.myshopify.com/admin/api/2024-10/graphql.json \
--H 'Content-Type: application/graphql' \
--H 'X-Shopify-Access-Token: {access_token}' \
--d '
-mutation {
-	metafieldDefinitionCreate(
-		definition: {
-			name: "ReviewsWidgetSnippet"
-			namespace: "app--1576377--reviews"
-			key: "reviews_widget_snippet"
-			type: "multi_line_text_field"
-			ownerType: PRODUCT
-			access: {
-				admin: PUBLIC_READ
-				storefront: PUBLIC_READ
-			}
-		}
-	) {
-		createdDefinition { id name }
-		userErrors { field message code }
-	}
-}
-'
-```
-
-4. Run the following command to expose the `star_rating_snippet` product metafield:
-
-```bash
-curl -X POST \
-https://{shop}.myshopify.com/admin/api/2024-10/graphql.json \
--H 'Content-Type: application/graphql' \
--H 'X-Shopify-Access-Token: {access_token}' \
--d '
-mutation {
-	metafieldDefinitionCreate(
-		definition: {
-			name: "StarRatingSnippet"
-			namespace: "app--1576377--reviews"
-			key: "star_rating_snippet"
-			type: "multi_line_text_field"
-			ownerType: PRODUCT
-			access: {
-				admin: PUBLIC_READ
-				storefront: PUBLIC_READ
-			}
-		}
-	) {
-		createdDefinition { id name }
-		userErrors { field message code }
-	}
-}
-'
-```
-
-5. Run the following command to expose the `review_count` product metafield:
-
-```bash
-curl -X POST \
-https://{shop}.myshopify.com/admin/api/2024-10/graphql.json \
--H 'Content-Type: application/graphql' \
--H 'X-Shopify-Access-Token: {access_token}' \
--d '
-mutation {
-	metafieldDefinitionCreate(
-		definition: {
-			name: "ReviewCount"
-			namespace: "app--1576377--reviews"
-			key: "review_count"
-			type: "number_integer"
-			ownerType: PRODUCT
-			access: {
-				admin: PUBLIC_READ
-				storefront: PUBLIC_READ
-			}
-		}
-	) {
-		createdDefinition { id name }
-		userErrors { field message code }
-	}
-}
-'
-```
-
-6. Run the following command to expose the `average_rating` product metafield:
-
-```bash
-curl -X POST \
-https://{shop}.myshopify.com/admin/api/2024-10/graphql.json \
--H 'Content-Type: application/graphql' \
--H 'X-Shopify-Access-Token: {access_token}' \
--d '
-mutation {
-	metafieldDefinitionCreate(
-		definition: {
-			name: "AverageRating"
-			namespace: "app--1576377--reviews"
-			key: "average_rating"
-			type: "rating"
-			ownerType: PRODUCT
-			access: {
-				admin: PUBLIC_READ
-				storefront: PUBLIC_READ
-			}
-		}
-	) {
-		createdDefinition { id name }
-		userErrors { field message code }
-	}
-}
-'
-```
-
-### Using GraphQL IDE
-
-Open your GraphQL IDE (such as Postman) and make `POST` requests with the following details:
-
-- **URL:** https://{shop}.myshopify.com/admin/api/2024-10/graphql.json
-- **Headers:** - X-Shopify-Access-Token: {access_token} - Content-Type: application/json
-
-1. Execute the following request to expose the `widget_pre_render_style_tags` shop metafield:
-
-```graphql
-mutation {
-	metafieldDefinitionCreate(
-		definition: {
-			name: "WidgetPreRenderStyleTags"
-			namespace: "app--1576377--reviews"
-			key: "widget_pre_render_style_tags"
-			type: "multi_line_text_field"
-			ownerType: SHOP
-            access: {
-                admin: PUBLIC_READ,
-                storefront: PUBLIC_READ
-            }
-		}
-	) {
-		createdDefinition {
-			id
-			name
-		}
-		userErrors {
-			field
-			message
-			code
-		}
-	}
-}
-```
-
-2. Execute the following request to expose the `widget_pre_render_body_style_tags` shop metafield:
-
-```graphql
-mutation {
-	metafieldDefinitionCreate(
-		definition: {
-			name: "WidgetPreRenderBodyStyleTags"
-			namespace: "app--1576377--reviews"
-			key: "widget_pre_render_body_style_tags"
-			type: "multi_line_text_field"
-			ownerType: SHOP
-            access: {
-                admin: PUBLIC_READ,
-                storefront: PUBLIC_READ
-            }
-		}
-	) {
-		createdDefinition {
-			id
-			name
-		}
-		userErrors {
-			field
-			message
-			code
-		}
-	}
-}
-```
-
-3. Execute the following request to expose the `reviews_widget_snippet` product metafield:
-
-```graphql
-mutation {
-	metafieldDefinitionCreate(
-		definition: {
-			name: "ReviewsWidgetSnippet"
-			namespace: "app--1576377--reviews"
-			key: "reviews_widget_snippet"
-			type: "multi_line_text_field"
-			ownerType: PRODUCT
-            access: {
-                admin: PUBLIC_READ,
-                storefront: PUBLIC_READ
-            }
-		}
-	) {
-		createdDefinition {
-			id
-			name
-		}
-		userErrors {
-			field
-			message
-			code
-		}
-	}
-}
-```
-
-4. Execute the following request to expose the `star_rating_snippet` product metafield:
-
-```graphql
-mutation {
-	metafieldDefinitionCreate(
-		definition: {
-			name: "StarRatingSnippet"
-			namespace: "app--1576377--reviews"
-			key: "star_rating_snippet"
-			type: "multi_line_text_field"
-			ownerType: PRODUCT
-            access: {
-                admin: PUBLIC_READ,
-                storefront: PUBLIC_READ
-            }
-		}
-	) {
-		createdDefinition {
-			id
-			name
-		}
-		userErrors {
-			field
-			message
-			code
-		}
-	}
-}
-```
-
-5. Execute the following request to expose the `review_count` product metafield:
-
-```graphql
-mutation {
-	metafieldDefinitionCreate(
-		definition: {
-			name: "ReviewCount"
-			namespace: "app--1576377--reviews"
-			key: "review_count"
-			type: "number_integer"
-			ownerType: PRODUCT
-            access: {
-                admin: PUBLIC_READ,
-                storefront: PUBLIC_READ
-            }
-		}
-	) {
-		createdDefinition {
-			id
-			name
-		}
-		userErrors {
-			field
-			message
-			code
-		}
-	}
-}
-```
-
-6. Execute the following request to expose the `average_rating` product metafield:
-
-```graphql
-mutation {
-	metafieldDefinitionCreate(
-		definition: {
-			name: "AverageRating"
-			namespace: "app--1576377--reviews"
-			key: "average_rating"
-			type: "rating"
-			ownerType: PRODUCT
-            access: {
-                admin: PUBLIC_READ,
-                storefront: PUBLIC_READ
-            }
-		}
-	) {
-		createdDefinition {
-			id
-			name
-		}
-		userErrors {
-			field
-			message
-			code
-		}
-	}
-}
-```
-
-**References**
-
-- [https://shopify.dev/api/examples/metafields#step-1-expose-metafields](https://shopify.dev/api/examples/metafields#step-1-expose-metafields)
-- [https://shopify.dev/docs/api/admin-graphql/2024-10/mutations/metafieldDefinitionCreate](https://shopify.dev/docs/api/admin-graphql/2024-10/mutations/metafieldDefinitionCreate)
-
-</details>
-
 ## Installation
 
 This package provides:
 
 - one function: `getOkendoProviderData`,
 - one provider: `OkendoProvider`,
-- two React components: `OkendoStarRating` and `OkendoReviews`.
+- three React components: `OkendoStarRating`, `OkendoReviews`, and `OkendoReviewsCarousel`.
 
-The function `getOkendoProviderData` needs to be called in the `loader` function of `root.tsx` in the Hydrogen 2 store. The data is then passed to `OkendoProvider`, which is added to your website's `body` and wraps everything in it.
+The function `getOkendoProviderData` needs to be called in the `loader` function of `root.tsx` in your Hydrogen store. The data is then passed to `OkendoProvider`, which is added to your website's `body` and wraps everything in it.
 
-> Important: `OkendoProvider` supports two ways of loading the data returned by `getOkendoProviderData`: either as a promise, or as the data itself. Its behaviour is different between the two ways — this is explained below.
-
-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.
+Then, the React components can be added on your store pages. There are a few more bits of configuration to do, please see below.
 
 > The code examples provided in this section are based on the Shopify template store created by running `npm create @shopify/hydrogen@latest` (see [Shopify's documentation](https://shopify.dev/docs/custom-storefronts/hydrogen/getting-started)). You will find the following steps already done in [our demo store](https://github.com/okendo/okendo-shopify-hydrogen-demo).
 
@@ -440,64 +39,42 @@ npm i @okendo/shopify-hydrogen
 
 ### `app/root.tsx`
 
-`OkendoProvider` supports two ways of loading the data returned by `getOkendoProviderData`:
-
-- **as a promise**: in this case, the query getting the data is deferred, which allows your page to load as quickly as it does without Okendo's widgets. When the data is ready, it is sent to the browser, and Okendo's widgets are rendered. Blank placeholders are shown until the widgets are rendered. You can customise these placeholders to show loading spinners or skeletons that fit well with your store's theme.
-- **as the data**: in this case, the query getting the data needs to complete before your page loads, which can add a couple hundreds milliseconds of loading time. Widgets are then rendered server-side, and so appear as soon as your page loads.
-
-To summarise the differences between the two behaviours:
-
-- Pass the promise to `OkendoProvider` — so don't use `await` with `getOkendoProviderData`:
-
-  - The page loading time won't be increased at all.
-  - The widgets will be rendered client-side.
-  - Placeholders (which are customisable) are shown until the widgets are rendered.
-
-- Pass the data to `OkendoProvider` — so use `await` with `getOkendoProviderData`:
-  - The page loading time can be increased by a couple hundreds milliseconds.
-  - The widgets will be rendered server-side.
-  - The widgets are shown as soon as the page loads — no placeholders needed.
-
-You can easily experiment with the two ways, and decide which is the one you'd like to keep for your store.
-
 Open `app/root.tsx` and add the following import:
 
 ```ts
 import {
-	OkendoProvider,
-	getOkendoProviderData,
+  OkendoProvider,
+  getOkendoProviderData,
 } from '@okendo/shopify-hydrogen';
 ```
 
-Locate the `loader` function, append `okendoProviderData` to the returned data as shown below, and set `subscriberId` to your Okendo subscriber ID.
-
-As explained above, set `okendoProviderData` to either `getOkendoProviderData(...)`, or `await getOkendoProviderData(...)`:
+Locate the `loadDeferredData` function, append `okendoProviderData` to the returned data as shown below, and set `subscriberId` to your Okendo subscriber ID.
 
 ```ts
-return defer({
-  // ...
-  okendoProviderData:
-    /* place `await` here if you want server-rendered widgets */ getOkendoProviderData(
-	{
-        context: args.context,
-        subscriberId: '<your-okendo-subscriber-id>',
-	},
-    ),
-});
+// ...
+return {
+  cart: cart.get(),
+  isLoggedIn: customerAccount.isLoggedIn(),
+  footer,
+  okendoProviderData: getOkendoProviderData({
+    context,
+    subscriberId: '<your-okendo-subscriber-id>',
+  }),
+};
 ```
 
 Locate the `Layout` component, add the `meta` tag `oke:subscriber_id` to `head`, and place your Okendo subscriber ID in its content:
 
 ```tsx
 <head>
-	<meta charSet="utf-8" />
-	<meta name="viewport" content="width=device-width,initial-scale=1" />
-	<meta name="oke:subscriber_id" content="<your-okendo-subscriber-id>" />
-	...
+  <meta charSet="utf-8" />
+  <meta name="viewport" content="width=device-width,initial-scale=1" />
+  <meta name="oke:subscriber_id" content="<your-okendo-subscriber-id>" />
+  ...
 </head>
 ```
 
-Append `OkendoProvider` to `body`, and pass it the promise — or the data — returned by `getOkendoProviderData`. If Content Security Policy is active in your project, you also need to provide the `nonce` (available with `const nonce = useNonce()` in Shopify's Hydrogen demo store):
+Append `OkendoProvider` to `body`, and pass it the promise returned by `getOkendoProviderData`. If Content Security Policy is active in your project, you also need to provide the `nonce` (available with `const nonce = useNonce()` in Shopify's Hydrogen demo store):
 
 ```tsx
 <body>
@@ -507,10 +84,10 @@ Append `OkendoProvider` to `body`, and pass it the promise — or the data — r
         cart={data.cart}
         shop={data.shop}
         consent={data.consent}
-	>
+      >
         <PageLayout {...data}>{children}</PageLayout>
       </Analytics.Provider>
-	</OkendoProvider>
+    </OkendoProvider>
   ) : (
     children
   )}
@@ -524,7 +101,8 @@ Append `OkendoProvider` to `body`, and pass it the promise — or the data — r
 > This is only necessary if Content Security Policy is active in your project.
 
 Locate the call to `createContentSecurityPolicy`, and ensure your configuration includes the entries below:
-Note that it's necessary to to add the default values (`'self'`, etc.) when [extending the CSP](https://shopify.dev/docs/custom-storefronts/hydrogen/content-security-policy). The call to `createContentSecurityPolicy` should now look like the following:
+
+> Note that it's necessary to to add the default values (`'self'`, etc.) when [extending the CSP](https://shopify.dev/docs/custom-storefronts/hydrogen/content-security-policy). The call to `createContentSecurityPolicy` should now look like the following:
 
 ```ts
 const { nonce, header, NonceProvider } = createContentSecurityPolicy({
@@ -532,8 +110,8 @@ const { nonce, header, NonceProvider } = createContentSecurityPolicy({
     checkoutDomain: context.env.PUBLIC_CHECKOUT_DOMAIN,
     storeDomain: context.env.PUBLIC_STORE_DOMAIN,
   },
-    defaultSrc: [
-      "'self'",
+  defaultSrc: [
+    "'self'",
     'localhost:*',
     'https://cdn.shopify.com',
     'https://www.google.com',
@@ -545,9 +123,9 @@ const { nonce, header, NonceProvider } = createContentSecurityPolicy({
     'https://surveys.okendo.io',
     'https://api.okendo.io',
     'data:',
-    ],
-    imgSrc: [
-      "'self'",
+  ],
+  imgSrc: [
+    "'self'",
     'https://cdn.shopify.com',
     'data:',
     'https://d3hw6dc1ow8pp2.cloudfront.net',
@@ -555,26 +133,26 @@ const { nonce, header, NonceProvider } = createContentSecurityPolicy({
     'https://dov7r31oq5dkj.cloudfront.net',
     'https://cdn-static.okendo.io',
     'https://surveys.okendo.io',
-    ],
-    mediaSrc: [
-      "'self'",
+  ],
+  mediaSrc: [
+    "'self'",
     'https://d3hw6dc1ow8pp2.cloudfront.net',
     'https://d3g5hqndtiniji.cloudfront.net',
     'https://dov7r31oq5dkj.cloudfront.net',
     'https://cdn-static.okendo.io',
-    ],
+  ],
   styleSrc: [
-      "'self'",
-      "'unsafe-inline'",
+    "'self'",
+    "'unsafe-inline'",
     'https://cdn.shopify.com',
     'https://fonts.googleapis.com',
     'https://fonts.gstatic.com',
     'https://d3hw6dc1ow8pp2.cloudfront.net',
     'https://cdn-static.okendo.io',
     'https://surveys.okendo.io',
-    ],
-    scriptSrc: [
-      "'self'",
+  ],
+  scriptSrc: [
+    "'self'",
     'https://cdn.shopify.com',
     'https://d3hw6dc1ow8pp2.cloudfront.net',
     'https://dov7r31oq5dkj.cloudfront.net',
@@ -583,18 +161,18 @@ const { nonce, header, NonceProvider } = createContentSecurityPolicy({
     'https://api.okendo.io',
     'https://www.google.com',
     'https://www.gstatic.com',
-    ],
-    fontSrc: [
-      "'self'",
+  ],
+  fontSrc: [
+    "'self'",
     'https://fonts.gstatic.com',
     'https://d3hw6dc1ow8pp2.cloudfront.net',
     'https://dov7r31oq5dkj.cloudfront.net',
     'https://cdn.shopify.com',
     'https://cdn-static.okendo.io',
     'https://surveys.okendo.io',
-    ],
-    connectSrc: [
-      "'self'",
+  ],
+  connectSrc: [
+    "'self'",
     'https://monorail-edge.shopifysvc.com',
     'localhost:*',
     'ws://localhost:*',
@@ -605,223 +183,313 @@ const { nonce, header, NonceProvider } = createContentSecurityPolicy({
     'https://api.raygun.com',
     'https://www.google.com',
     'https://www.gstatic.com',
-    ],
+  ],
   frameSrc: ['https://www.google.com', 'https://www.gstatic.com'],
 });
 ```
 
+### `app/lib/fragments.ts`
+
+Add the following GraphQL fragment at the bottom of the file:
+
+```ts
+export const OKENDO_PRODUCT_STAR_RATING_FRAGMENT = `#graphql
+  fragment OkendoStarRatingSnippet on Product {
+    okendoStarRatingSnippet: metafield(
+      namespace: "app--1576377--reviews"
+      key: "star_rating_snippet"
+    ) {
+      value
+    }
+  }
+` as const;
+
+export const OKENDO_PRODUCT_REVIEWS_FRAGMENT = `#graphql
+  fragment OkendoReviewsSnippet on Product {
+    okendoReviewsSnippet: metafield(
+      namespace: "app--1576377--reviews"
+      key: "reviews_widget_snippet"
+    ) {
+      value
+    }
+  }
+` as const;
+```
+
 ### `app/routes/_index.tsx`
 
 Add the following import:
 
 ```ts
-import { OkendoStarRating } from '@okendo/shopify-hydrogen';
+import { OKENDO_PRODUCT_STAR_RATING_FRAGMENT } from '~/lib/fragments';
+```
+
+Then append `${OKENDO_PRODUCT_STAR_RATING_FRAGMENT}` and `...OkendoStarRatingSnippet` to `RECOMMENDED_PRODUCTS_QUERY`:
+
+```ts
+const RECOMMENDED_PRODUCTS_QUERY = `#graphql
+  ${OKENDO_PRODUCT_STAR_RATING_FRAGMENT}
+  fragment RecommendedProduct on Product {
+    id
+    title
+    handle
+    priceRange {
+      minVariantPrice {
+        amount
+        currencyCode
+      }
+    }
+    images(first: 1) {
+      nodes {
+        id
+        url
+        altText
+        width
+        height
+      }
+    }
+    ...OkendoStarRatingSnippet
+  }
+  query RecommendedProducts ($country: CountryCode, $language: LanguageCode)
+    @inContext(country: $country, language: $language) {
+    products(first: 4, sortKey: UPDATED_AT, reverse: true) {
+      nodes {
+        ...RecommendedProduct
+      }
+    }
+  }
+` as const;
+```
+
+### `app/routes/collections.all.tsx`
+
+Add the following import:
+
+```ts
+import { OKENDO_PRODUCT_STAR_RATING_FRAGMENT } from '~/lib/fragments';
 ```
 
-Add the following block just before the `RECOMMENDED_PRODUCTS_QUERY` GraphQL query:
+Then append `${OKENDO_PRODUCT_STAR_RATING_FRAGMENT}` and `...OkendoStarRatingSnippet` to `COLLECTION_ITEM_FRAGMENT`:
 
 ```ts
-const OKENDO_PRODUCT_STAR_RATING_FRAGMENT = `#graphql
-	fragment OkendoStarRatingSnippet on Product {
-		okendoStarRatingSnippet: metafield(
-            namespace: "app--1576377--reviews"
-            key: "star_rating_snippet"
-		) {
-			value
-		}
-	}
+const COLLECTION_ITEM_FRAGMENT = `#graphql
+  ${OKENDO_PRODUCT_STAR_RATING_FRAGMENT}
+  fragment MoneyCollectionItem on MoneyV2 {
+    amount
+    currencyCode
+  }
+  fragment CollectionItem on Product {
+    id
+    handle
+    title
+    featuredImage {
+      id
+      altText
+      url
+      width
+      height
+    }
+    priceRange {
+      minVariantPrice {
+        ...MoneyCollectionItem
+      }
+      maxVariantPrice {
+        ...MoneyCollectionItem
+      }
+    }
+    ...OkendoStarRatingSnippet
+  }
 ` as const;
 ```
 
-Then append `${OKENDO_PRODUCT_STAR_RATING_FRAGMENT}` and `...OkendoStarRatingSnippet` to `RECOMMENDED_PRODUCTS_QUERY`:
+### `app/routes/collections.$handle.tsx`
+
+Add the following import:
 
 ```ts
-const RECOMMENDED_PRODUCTS_QUERY = `#graphql
-	${OKENDO_PRODUCT_STAR_RATING_FRAGMENT}
-	fragment RecommendedProduct on Product {
-		id
-		title
-		handle
-		priceRange {
-			minVariantPrice {
-				amount
-				currencyCode
-			}
-		}
-		images(first: 1) {
-			nodes {
-				id
-				url
-				altText
-				width
-				height
-			}
-		}
-		...OkendoStarRatingSnippet
-	}
-	query RecommendedProducts ($country: CountryCode, $language: LanguageCode)
-		@inContext(country: $country, language: $language) {
-		products(first: 4, sortKey: UPDATED_AT, reverse: true) {
-			nodes {
-				...RecommendedProduct
-			}
-		}
-	}
+import { OKENDO_PRODUCT_STAR_RATING_FRAGMENT } from '~/lib/fragments';
+```
+
+Then append `${OKENDO_PRODUCT_STAR_RATING_FRAGMENT}` and `...OkendoStarRatingSnippet` to `COLLECTION_ITEM_FRAGMENT`:
+
+```ts
+const PRODUCT_ITEM_FRAGMENT = `#graphql
+  ${OKENDO_PRODUCT_STAR_RATING_FRAGMENT}
+  fragment MoneyProductItem on MoneyV2 {
+    amount
+    currencyCode
+  }
+  fragment ProductItem on Product {
+    id
+    handle
+    title
+    featuredImage {
+      id
+      altText
+      url
+      width
+      height
+    }
+    priceRange {
+      minVariantPrice {
+        ...MoneyProductItem
+      }
+      maxVariantPrice {
+        ...MoneyProductItem
+      }
+    }
+    ...OkendoStarRatingSnippet
+  }
 ` as const;
 ```
 
-> Note: if you get a type error on `product`, restart the dev server to get the types (`storefrontapi.generated.d.ts`) regenerated from the GraphQL fragments.
+### `app/components/ProductItem.tsx`
+
+Add the following import:
+
+```ts
+import { OkendoStarRating } from '@okendo/shopify-hydrogen';
+```
 
 Add `OkendoStarRating` to the `RecommendedProducts` component — for instance, we can add it below the product title, like this:
 
 ```tsx
 <Image
-	data={product.images.nodes[0]}
-	aspectRatio="1/1"
-	sizes="(min-width: 45em) 20vw, 50vw"
+  data={product.images.nodes[0]}
+  aspectRatio="1/1"
+  sizes="(min-width: 45em) 20vw, 50vw"
 />
 <h4>{product.title}</h4>
 <OkendoStarRating
-	productId={product.id}
-	okendoStarRatingSnippet={product.okendoStarRatingSnippet}
+  className="mb-2"
+  productId={product.id}
+  okendoStarRatingSnippet={product.okendoStarRatingSnippet}
 />
 <small>
-	<Money data={product.priceRange.minVariantPrice} />
+  <Money data={product.priceRange.minVariantPrice} />
 </small>
 ```
 
-> Note: if the widgets are rendered client-side (if you don't use `await` when calling `getOkendoProviderData`), you can provide your own placeholder by using the `placeholder` property of `OkendoStarRating`.
+> Note: if you get a type error on `product`, restart the dev server to get the types (`storefrontapi.generated.d.ts`) regenerated from the GraphQL fragments.
 
 We now have the Okendo Star Rating widget visible on our page:
 
-![Okendo's Star Rating widget](./readme-res/okendo-star-rating-widget.png)
-
-You can do the same changes to the files `app/routes/collections.$handle.tsx` and `app/routes/collections.all.tsx` to make the items' Okendo Star Rating visible on collection pages.
+![Okendo's Star Rating widget](./res/okendo-star-rating-widget.webp)
 
 ### `app/routes/products.$handle.tsx`
 
-Add the following import:
+Add the following imports:
 
 ```ts
 import { OkendoReviews, OkendoStarRating } from '@okendo/shopify-hydrogen';
-```
-
-Add the following block just before the `PRODUCT_FRAGMENT` GraphQL query:
-
-```ts
-const OKENDO_PRODUCT_STAR_RATING_FRAGMENT = `#graphql
-	fragment OkendoStarRatingSnippet on Product {
-		okendoStarRatingSnippet: metafield(
-            namespace: "app--1576377--reviews"
-            key: "star_rating_snippet"
-		) {
-			value
-		}
-	}
-` as const;
-
-const OKENDO_PRODUCT_REVIEWS_FRAGMENT = `#graphql
-	fragment OkendoReviewsSnippet on Product {
-		okendoReviewsSnippet: metafield(
-            namespace: "app--1576377--reviews"
-            key: "reviews_widget_snippet"
-		) {
-			value
-		}
-	}
-` as const;
+import {
+  OKENDO_PRODUCT_REVIEWS_FRAGMENT,
+  OKENDO_PRODUCT_STAR_RATING_FRAGMENT,
+} from '~/lib/fragments';
 ```
 
 Then append `${OKENDO_PRODUCT_STAR_RATING_FRAGMENT}`, `${OKENDO_PRODUCT_REVIEWS_FRAGMENT}`, `...OkendoStarRatingSnippet`, and `...OkendoReviewsSnippet` to `PRODUCT_FRAGMENT`:
 
 ```ts
 const PRODUCT_FRAGMENT = `#graphql
-	${OKENDO_PRODUCT_STAR_RATING_FRAGMENT}
-	${OKENDO_PRODUCT_REVIEWS_FRAGMENT}
-	fragment Product on Product {
-		id
-		title
-		vendor
-		handle
-		descriptionHtml
-		description
-		options {
-			name
-			values
-		}
-		selectedVariant: variantBySelectedOptions(selectedOptions: $selectedOptions) {
-			...ProductVariant
-		}
-		variants(first: 1) {
-			nodes {
-				...ProductVariant
-			}
-		}
-		seo {
-			description
-			title
-		}
-		...OkendoStarRatingSnippet
-		...OkendoReviewsSnippet
-	}
-	${PRODUCT_VARIANT_FRAGMENT}
+  ${OKENDO_PRODUCT_STAR_RATING_FRAGMENT}
+  ${OKENDO_PRODUCT_REVIEWS_FRAGMENT}
+  fragment Product on Product {
+    id
+    title
+    vendor
+    handle
+    descriptionHtml
+    description
+    encodedVariantExistence
+    encodedVariantAvailability
+    options {
+      name
+      optionValues {
+        name
+        firstSelectableVariant {
+          ...ProductVariant
+        }
+        swatch {
+          color
+          image {
+            previewImage {
+              url
+            }
+          }
+        }
+      }
+    }
+    selectedOrFirstAvailableVariant(selectedOptions: $selectedOptions, ignoreUnknownOptions: true, caseInsensitiveMatch: true) {
+      ...ProductVariant
+    }
+    adjacentVariants (selectedOptions: $selectedOptions) {
+      ...ProductVariant
+    }
+    seo {
+      description
+      title
+    }
+    ...OkendoStarRatingSnippet
+    ...OkendoReviewsSnippet
+  }
+  ${PRODUCT_VARIANT_FRAGMENT}
 ` as const;
 ```
 
-> Note: if you get a type error on `product`, restart the dev server to get the types (`storefrontapi.generated.d.ts`) regenerated from the GraphQL fragments.
-
 Add `OkendoStarRating` and `OkendoReviews` to the `Product` component:
 
 ```tsx
 <>
-	<div className="product">
-		<ProductImage image={selectedVariant?.image} />
+  <div className="product">
+    <ProductImage image={selectedVariant?.image} />
     <div className="product-main">
       <h1>{title}</h1>
       <OkendoStarRating
+        className="mb-4"
         productId={product.id}
         okendoStarRatingSnippet={product.okendoStarRatingSnippet}
-		/>
+      />
       <ProductPrice
         price={selectedVariant?.price}
         compareAtPrice={selectedVariant?.compareAtPrice}
       />
       ...
-	</div>
+    </div>
     ...
   </div>
 
-	<OkendoReviews
-		productId={product.id}
-		okendoReviewsSnippet={product.okendoReviewsSnippet}
-	/>
+  <OkendoReviews
+    productId={product.id}
+    okendoReviewsSnippet={product.okendoReviewsSnippet}
+  />
 </>
 ```
 
-> Note: if the widgets are rendered client-side (if you don't use `await` when calling `getOkendoProviderData`), you can provide your own placeholder by using the `placeholder` property of `OkendoStarRating` and `OkendoReviews`.
+> Note: if you get a type error on `product`, restart the dev server to get the types (`storefrontapi.generated.d.ts`) regenerated from the GraphQL fragments.
 
 We now have the Okendo Star Rating and Reviews widgets visible on our product page:
 
-![Okendo's Star Rating and Reviews widgets](./readme-res/okendo-star-rating-and-reviews-widgets.png)
+![Okendo's Star Rating and Reviews widgets](./res/okendo-star-rating-and-reviews-widgets.webp)
 
-### All Reviews Widget - Client Side Only
+### All-Reviews Widget - Client Side Only
 
-If you would like to include a copy of the Okendo Reviews Widget which displays all reviews for a given store (to be used on a reviews page for example), please add the `OkendoReviewsWidget` without supplying the `productId`.
+If you would like to include a copy of the Okendo Reviews Widget which displays all reviews for a given store (to be used on a reviews page for example), please add `OkendoReviews` without supplying the `productId`.
 
-Please note the all reviews widget loads on the client, not the server.
+Please note the all-reviews widget loads on the client, not the server.
 
 ```tsx
-import { type MetaFunction } from '@remix-run/react';
+import { type MetaFunction } from 'react-router';
 import { OkendoReviews } from '@okendo/shopify-hydrogen';
 
 export const meta: MetaFunction = () => {
-  return [{title: `Hydrogen | Okendo All Reviews`}];
+  return [{ title: `Hydrogen | Okendo All Reviews` }];
 };
 
 export default function ReviewsPage() {
   return (
     <div className="all-reviews">
-      <h1>All Reviews Widget</h1>
+      <h1>All-Reviews Widget</h1>
       <OkendoReviews />
     </div>
   );
@@ -829,32 +497,48 @@ export default function ReviewsPage() {
 ```
 
 ### Okendo Reviews Carousel Widget - Client Side Only
-If you would like to include a copy of the Okendo Reviews Carousel Widget which displays reviews by product or group for a given store (to be used on a homepage or featured page for example), please add the `OkendoReviewsCarouselWidget` with or without the the `productId` or `groupId`.
 
-Please note the all reviews widget loads on the client not the server.
+If you would like to include a copy of the Okendo Reviews Carousel Widget which displays reviews by product or group for a given store (to be used on a homepage or featured page for example), please add `OkendoReviewsCarousel` with or without the `productId` or `groupId`.
+
+Please note the carousel widget loads on the client, not the server.
 
 ```tsx
-import { type MetaFunction } from '@remix-run/react';
+import { type MetaFunction } from 'react-router';
 import { OkendoReviews } from '@okendo/shopify-hydrogen';
 
 export const meta: MetaFunction = () => {
-  return [{title: `Hydrogen | Okendo Reviews Carousel`}];
+  return [{ title: `Hydrogen | Okendo Reviews Carousel` }];
 };
 
 export default function AFeaturedPage() {
   return (
     <div className="all-reviews">
       <h1>Reviews Carousel Widget</h1>
-      <OkendoReviewsCarousel 
-	      productId={product.id}
-	  />
+      <OkendoReviewsCarousel productId={product.id} />
+    </div>
+  );
+}
+```
+
+You can also use `OkendoReviewsCarousel` without `productId`, in order to display reviews for all products. For instance, we can add it to the homepage in `app/routes/_index.tsx`:
+
+```ts
+export default function Homepage() {
+  const data = useLoaderData<typeof loader>();
+  return (
+    <div className="home">
+      <FeaturedCollection collection={data.featuredCollection} />
+      <RecommendedProducts products={data.recommendedProducts} />
+      <OkendoReviewsCarousel />
     </div>
   );
 }
 ```
 
 # Loyalty Widgets
+
 ## Installation
+
 To include Loyalty Widgets in your Shopify Hydrogen store, you will need to make the following changes:
 
 1. Add `customerAccessToken: await args.context.customerAccount.getAccessToken(),` to your `loader` function, this will be used to log your customer into the Loyalty App.
@@ -864,35 +548,35 @@ To include Loyalty Widgets in your Shopify Hydrogen store, you will need to make
 > Note: If you only wish to use the Loyalty product and not reviews then simply leave out the `'reviews'` from the array like so: `okendoProducts: ['loyalty'],`.
 
 The relevant section should now look something like this:
+
 ```ts
 return defer({
   // ...
   customerAccessToken: await args.context.customerAccount.getAccessToken(),
-  okendoProviderData:
-    getOkendoProviderData(
-	{
-        context: args.context,
-        subscriberId: '<your-okendo-subscriber-id>',
-        okendoProducts: ['reviews', 'loyalty'],
-	},
-    ),
+  okendoProviderData: getOkendoProviderData({
+    context: args.context,
+    subscriberId: '<your-okendo-subscriber-id>',
+    okendoProducts: ['reviews', 'loyalty'],
+  }),
 });
 ```
 
 3. Add `customerAccessToken={data.customerAccessToken}` to the `OkendoProvider` component, it should now look like:
-```ts
+
+```tsx
 <OkendoProvider
-    nonce={nonce}
-    okendoProviderData={data.okendoProviderData}
-    customerAccessToken={data.customerAccessToken}
+  nonce={nonce}
+  okendoProviderData={data.okendoProviderData}
+  customerAccessToken={data.customerAccessToken}
 >
-    ...
+  ...
 </OkendoProvider>
 ```
 
 If your Okendo Loyalty Settings are [correctly set up](https://support.okendo.io/en/collections/8270193-okendo-loyalty) and your program has launched, the Loyalty Floating Widget will now appear on your store.
 
 ## Dedicated Loyalty Page
+
 Add `<OkendoLoyaltyEmbeddedWidget />` to any components/pages where you wish to have the Dedicated Loyalty Page appear.
 
-*Make sure you are importing the component from the `okendo-shopify-hydrogen` package: `import {OkendoLoyaltyEmbeddedWidget} from '@okendo/shopify-hydrogen';`*
+_Make sure you are importing the component from the `okendo-shopify-hydrogen` package: `import {OkendoLoyaltyEmbeddedWidget} from '@okendo/shopify-hydrogen';`_