Rebuy Hydrogen 2.0 (Beta) Documentation
Beta: APIs May Change
This document pertains to the beta version of the Rebuy Hydrogen package. Functionality and APIs are subject to change.
Overview
The Rebuy Hydrogen package (beta) is engineered for seamless integration with Shopify's Hydrogen and Hydrogen React frameworks, specifically versions 2.0. Our goal is to provide a streamlined, plug-and-play experience, where the package handles the heavy lifting of integrating Rebuy's powerful personalization features into your headless Shopify store.
This guide details each component and provides instructions for implementing them within your application.
Initial Setup
Follow these steps to get the Rebuy Hydrogen package up and running in your project.
1. Identify Your Framework
Determine if your application uses:
- Hydrogen standalone: You are using only the core Hydrogen framework.
- Hydrogen React: You are using Hydrogen React, which inherently includes Hydrogen.
This distinction is crucial because the Rebuy package utilizes different hooks and functions depending on your setup. If you're using Hydrogen React, our components will automatically leverage Hydrogen React-specific functionalities.
2. Install the Package
Install the beta version of the Rebuy Hydrogen package from npm:
npm install @rebuy/rebuy-hydrogen@beta
# or
yarn add @rebuy/rebuy-hydrogen@beta
The package can be found at: https://www.npmjs.com/package/@rebuy/rebuy-hydrogen
Navigate to your vite.config.ts file and add the following envPrefix entries to the defineConfig object. This ensures your environment variables are correctly exposed to your client-side application.
// vite.config.ts
import {defineConfig} from 'vite';
// ... other imports
export default defineConfig({
// ... other configurations
envPrefix: [
'PUBLIC_REBUY_API_KEY',
'PUBLIC_STORE_DOMAIN',
'PUBLIC_STOREFRONT_API_TOKEN',
'PRIMARY_DOMAIN' // Ensure this is also included if used elsewhere
],
});
4. Set Environment Variables
In your project's .env file, add your Rebuy API key:
PUBLIC_REBUY_API_KEY=your_rebuy_api_key_here
You can find or create your API key in the Rebuy Admin panel under Settings> API Keys. Click "Create New API Key" or copy an existing one.
5. Integrate RebuyContextProvider
The RebuyContextProvider is essential for making Rebuy functionality available throughout your application.
For Hydrogen Standalone Applications:
- Import necessary modules: In your
app/root.tsx file, add the following imports:
// app/root.tsx
import { RebuyContextProvider } from '@rebuy/rebuy-hydrogen';
import '@rebuy/rebuy-hydrogen/dist/index.css'; // Import default styles
- Wrap your application with
RebuyContextProvider: Place the <RebuyContextProvider> component as a parent, typically after the <body> tag, wrapping your main page layout. Pass the cart object (e.g., data.cart) and isHydrogenReact={false} as props.
// app/root.tsx (example structure)
// ... other imports
import { RebuyContextProvider } from '@rebuy/rebuy-hydrogen';
import '@rebuy/rebuy-hydrogen/dist/index.css';
import {Analytics} from '@shopify/hydrogen'; // Assuming Analytics is used
// ... component definition
export default function App({data, children}) { // Example structure
return (
<Suspense>
<ShopifyProvider shopifyConfig={shopifyConfig}>
{/* Other providers */}
{data ? (
<RebuyContextProvider cart={data.cart} isHydrogenReact={false}>
<Analytics.Provider
cart={data.cart}
shop={data.shop}
consent={data.consent} // Ensure consent is handled
>
<PageLayout {...data}> {/* Your PageLayout component */}
{children}
</PageLayout>
</Analytics.Provider>
</RebuyContextProvider>
) : (
children // Fallback or loading state
)}
{/* Other providers */}
</ShopifyProvider>
</Suspense>
);
}
For Hydrogen React Applications:
- Import CSS: In your
app/root.tsx file (or a similar global entry point), import the Rebuy CSS:
// app/root.tsx
import '@rebuy/rebuy-hydrogen/dist/index.css'; // Import default styles
- Wrap with
RebuyContextProvider: Navigate to the file where your application's context providers are defined (e.g., app/context/ContextProvider.tsx if using a structure like Pack Digital's starter). Wrap the children components with <RebuyContextProvider>. Pass isHydrogenReact={true} as a prop.
// app/context/ContextProvider.tsx (example structure)
import { RebuyContextProvider } from '@rebuy/rebuy-hydrogen';
// ... other context imports
// TODO - example snippet
Components
Rebuy components are designed to work seamlessly regardless of whether you are using Hydrogen standalone or Hydrogen React. They leverage the context provided by RebuyContextProvider to call the appropriate hooks and functions.
This component acts as a parent wrapper for Rebuy widgets, providing them with the necessary data and context to fetch and display recommendations.
Props:
dataSource: string (Required)- The Rebuy API endpoint for product recommendations (e.g.,
cart, product, collection).
productId?: string- The Shopify Product ID (e.g.,
gid://shopify/Product/12345). Used when dataSource relates to a specific product.
product?: Product- The entire Shopify product object. Can be used as an alternative to
productId.
variantId?: string- The Shopify Variant ID of the currently selected variant (e.g.,
gid://shopify/ProductVariant/67890).
variant?: ProductVariant- The entire Shopify product variant object. Can be used as an alternative to
variantId.
limit?: number- The maximum number of product recommendations to return.
options?: object- An object containing additional key-value pairs to be passed as arguments to the Rebuy REST API (e.g.,
{ metafields: "yes" }).
The following components render specific Rebuy widgets. They share several common props for customization and callbacks.
Common Props for Widget Components:
customTitle?: string- A custom title to be displayed above the component.
customTitleLevel?: 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6'- Sets the HTML heading level for the
customTitle (e.g., h2). Other titles within the component will adjust hierarchically (e.g., to h3).
customTitleStyle?: object- A React style object for custom styling of the
customTitle (e.g., { color: 'blue', textAlign: 'center' }).
addToCartCallback?: () => void- A callback function executed after an item is successfully added to the cart. Useful for triggering actions like opening a cart drawer or showing a confirmation.
addToCartBtnText?: string- Custom text for the "Add to Cart" button within the widget.
RebuyCompleteTheLook
Displays "Complete the Look" recommendations, often used on product detail pages.
Props:
RebuyDynamicBundleProducts
Displays products for creating dynamic bundles.
Props:
RebuyProductRecommendations
A versatile component for displaying various types of product recommendations (e.g., "You May Also Like," "Frequently Bought Together"). The specific recommendations are determined by the dataSource prop on the parent WidgetContainer and your Rebuy widget rules.
Props:
RebuyProductAddOns
Displays product add-ons, typically used on product detail pages or in the cart.
Props:
- (Inherits Common Props)
includeMainProduct?: boolean- If
true, the main product (passed via productId or product to WidgetContainer) will be included in the "add to cart" action when a bundle of add-ons is added.
- Defaults to
false.
learnMoreText?: string- Custom text for the "Learn More" link/button that directs users to the product detail page of an add-on item.
subtotalText?: string- Custom text displayed before the subtotal of all selected add-on products (e.g., "Add-ons Subtotal:").
withProductText?: string- Custom text displayed before the total price if
includeMainProduct is true and the main product's price is included in the displayed total (e.g., "Total with Product:").
---
title: Rebuy Hydrogen 2.0 (Beta) Documentation
excerpt: ''
deprecated: false
hidden: true
metadata:
title: ''
description: ''
robots: index
next:
description: ''
---
!!! warning "Beta: APIs May Change"
This document pertains to the **beta** version of the Rebuy Hydrogen package. Functionality and APIs are subject to change.
## Overview
The Rebuy Hydrogen package (beta) is engineered for seamless integration with Shopify's Hydrogen and Hydrogen React frameworks, specifically versions 2.0. Our goal is to provide a streamlined, plug-and-play experience, where the package handles the heavy lifting of integrating Rebuy's powerful personalization features into your headless Shopify store.
This guide details each component and provides instructions for implementing them within your application.
## Initial Setup
Follow these steps to get the Rebuy Hydrogen package up and running in your project.
### 1\. Identify Your Framework
Determine if your application uses:
* **Hydrogen standalone:** You are using only the core Hydrogen framework.
* **Hydrogen React:** You are using Hydrogen React, which inherently includes Hydrogen.
This distinction is crucial because the Rebuy package utilizes different hooks and functions depending on your setup. If you're using Hydrogen React, our components will automatically leverage Hydrogen React-specific functionalities.
### 2\. Install the Package
Install the beta version of the Rebuy Hydrogen package from npm:
```
npm install @rebuy/rebuy-hydrogen@beta
# or
yarn add @rebuy/rebuy-hydrogen@beta
```
The package can be found at: [https://www.npmjs.com/package/@rebuy/rebuy-hydrogen](https://www.npmjs.com/package/@rebuy/rebuy-hydrogen)
### 3\. Configure Vite
Navigate to your `vite.config.ts` file and add the following `envPrefix` entries to the `defineConfig` object. This ensures your environment variables are correctly exposed to your client-side application.
```javascript
// vite.config.ts
import {defineConfig} from 'vite';
// ... other imports
export default defineConfig({
// ... other configurations
envPrefix: [
'PUBLIC_REBUY_API_KEY',
'PUBLIC_STORE_DOMAIN',
'PUBLIC_STOREFRONT_API_TOKEN',
'PRIMARY_DOMAIN' // Ensure this is also included if used elsewhere
],
});
```
### 4\. Set Environment Variables
In your project's `.env` file, add your Rebuy API key:
```
PUBLIC_REBUY_API_KEY=your_rebuy_api_key_here
```
You can find or create your API key in the Rebuy Admin panel under **Settings\> API Keys**. Click "Create New API Key" or copy an existing one.
### 5\. Integrate RebuyContextProvider
The `RebuyContextProvider` is essential for making Rebuy functionality available throughout your application.
#### For **Hydrogen** Standalone Applications:
1. **Import necessary modules:** In your `app/root.tsx` file, add the following imports:
```javascript
// app/root.tsx
import { RebuyContextProvider } from '@rebuy/rebuy-hydrogen';
import '@rebuy/rebuy-hydrogen/dist/index.css'; // Import default styles
```
2. **Wrap your application with`RebuyContextProvider`:** Place the `<RebuyContextProvider>` component as a parent, typically after the `<body>` tag, wrapping your main page layout. Pass the `cart` object (e.g., `data.cart`) and `isHydrogenReact={false}` as props.
```javascript
// app/root.tsx (example structure)
// ... other imports
import { RebuyContextProvider } from '@rebuy/rebuy-hydrogen';
import '@rebuy/rebuy-hydrogen/dist/index.css';
import {Analytics} from '@shopify/hydrogen'; // Assuming Analytics is used
// ... component definition
export default function App({data, children}) { // Example structure
return (
<Suspense>
<ShopifyProvider shopifyConfig={shopifyConfig}>
{/* Other providers */}
{data ? (
<RebuyContextProvider cart={data.cart} isHydrogenReact={false}>
<Analytics.Provider
cart={data.cart}
shop={data.shop}
consent={data.consent} // Ensure consent is handled
>
<PageLayout {...data}> {/* Your PageLayout component */}
{children}
</PageLayout>
</Analytics.Provider>
</RebuyContextProvider>
) : (
children // Fallback or loading state
)}
{/* Other providers */}
</ShopifyProvider>
</Suspense>
);
}
```
#### For **Hydrogen React** Applications:
1. **Import CSS:** In your `app/root.tsx` file (or a similar global entry point), import the Rebuy CSS:
```javascript
// app/root.tsx
import '@rebuy/rebuy-hydrogen/dist/index.css'; // Import default styles
```
2. **Wrap with`RebuyContextProvider`:** Navigate to the file where your application's context providers are defined (e.g., `app/context/ContextProvider.tsx` if using a structure like Pack Digital's starter). Wrap the children components with `<RebuyContextProvider>`. Pass `isHydrogenReact={true}` as a prop.
```javascript
// app/context/ContextProvider.tsx (example structure)
import { RebuyContextProvider } from '@rebuy/rebuy-hydrogen';
// ... other context imports
// TODO - example snippet
```
## Components
Rebuy components are designed to work seamlessly regardless of whether you are using Hydrogen standalone or Hydrogen React. They leverage the context provided by `RebuyContextProvider` to call the appropriate hooks and functions.
### `WidgetContainer`
This component acts as a parent wrapper for Rebuy widgets, providing them with the necessary data and context to fetch and display recommendations.
**Props:**
* `dataSource: string` (Required)
* The Rebuy API endpoint for product recommendations (e.g., `cart`, `product`, `collection`).
* `productId?: string`
* The Shopify Product ID (e.g., `gid://shopify/Product/12345`). Used when `dataSource` relates to a specific product.
* `product?: Product`
* The entire Shopify product object. Can be used as an alternative to `productId`.
* `variantId?: string`
* The Shopify Variant ID of the currently selected variant (e.g., `gid://shopify/ProductVariant/67890`).
* `variant?: ProductVariant`
* The entire Shopify product variant object. Can be used as an alternative to `variantId`.
* `limit?: number`
* The maximum number of product recommendations to return.
* `options?: object`
* An object containing additional key-value pairs to be passed as arguments to the Rebuy REST API (e.g., `{ metafields: "yes" }`).
### Rebuy Widget Components
The following components render specific Rebuy widgets. They share several common props for customization and callbacks.
**Common Props for Widget Components:**
* `customTitle?: string`
* A custom title to be displayed above the component.
* `customTitleLevel?: 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6'`
* Sets the HTML heading level for the `customTitle` (e.g., `h2`). Other titles within the component will adjust hierarchically (e.g., to `h3`).
* `customTitleStyle?: object`
* A React style object for custom styling of the `customTitle` (e.g., `{ color: 'blue', textAlign: 'center' }`).
* `addToCartCallback?: () => void`
* A callback function executed after an item is successfully added to the cart. Useful for triggering actions like opening a cart drawer or showing a confirmation.
* `addToCartBtnText?: string`
* Custom text for the "Add to Cart" button within the widget.
***
### `RebuyCompleteTheLook`
Displays "Complete the Look" recommendations, often used on product detail pages.
**Props:**
* *(Inherits Common Props)*
<br />
***
### `RebuyDynamicBundleProducts`
Displays products for creating dynamic bundles.
**Props:**
* *(Inherits Common Props)*
<br />
***
### `RebuyProductRecommendations`
A versatile component for displaying various types of product recommendations (e.g., "You May Also Like," "Frequently Bought Together"). The specific recommendations are determined by the `dataSource` prop on the parent `WidgetContainer` and your Rebuy widget rules.
**Props:**
* *(Inherits Common Props)*
<br />
***
### `RebuyProductAddOns`
Displays product add-ons, typically used on product detail pages or in the cart.
**Props:**
* *(Inherits Common Props)*
* `includeMainProduct?: boolean`
* If `true`, the main product (passed via `productId` or `product` to `WidgetContainer`) will be included in the "add to cart" action when a bundle of add-ons is added.
* Defaults to `false`.
* `learnMoreText?: string`
* Custom text for the "Learn More" link/button that directs users to the product detail page of an add-on item.
* `subtotalText?: string`
* Custom text displayed before the subtotal of all selected add-on products (e.g., "Add-ons Subtotal:").
* `withProductText?: string`
* Custom text displayed before the total price if `includeMainProduct` is `true` and the main product's price is included in the displayed total (e.g., "Total with Product:").