Rebuy Hydrogen 2.0 (Beta) Documentation

🚧
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

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.

// 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 withRebuyContextProvider: 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 withRebuyContextProvider: 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.

`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)

`RebuyDynamicBundleProducts`

Displays products for creating dynamic bundles.

Props:

(Inherits Common 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:

(Inherits Common 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:").

This document pertains to the beta version of the Rebuy Hydrogen package. Functionality and APIs are subject to change.

Overview

Initial Setup

1. Identify Your Framework

2. Install the Package

3. Configure Vite

4. Set Environment Variables

5. Integrate RebuyContextProvider

For Hydrogen Standalone Applications:

For Hydrogen React Applications:

Components

WidgetContainer

Rebuy Widget Components

RebuyCompleteTheLook

RebuyDynamicBundleProducts

RebuyProductRecommendations

RebuyProductAddOns

`WidgetContainer`

`RebuyCompleteTheLook`

`RebuyDynamicBundleProducts`

`RebuyProductRecommendations`

`RebuyProductAddOns`