API Reference

Installation

Step 1: Create a new Hydrogen app

You can create a Hydrogen app locally using yarn, npm, or npx.

NOTE: If you've already created a Hydrogen app, you can jump ahead to Step 4

If you want to integrate with an existing React framework, like Next.js or Gatsby, then you can add the @shopify/hydrogen NPM package to your project.

1. Navigate to your working directory

Navigate to the directory where you want to create your project and run the following command:

cd <directory>

2. Create your project

Create a new Hydrogen project with a default template linked to a demo-store with the following command:

yarn create @shopify/hydrogen --template demo-store

3. Name your project

Follow the prompts to name your new Hydrogen application.

Step 2: Link your Shopify Storefront

Connect your Hydrogen app to your Shopify storefront by updating the properties in the hydrogen.config.js file. You will need to generate a Storefront API access token for your Hydrogen app to communicate with your Shopify store.

1. Open your hydrogen.config.js file

Open hydrogen.config.js file located in the root of your project directory.

2. Update your config file

Edit your hydrogen.config.js file with 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.
  • Update storefrontApiVersion to specify the Storefront API version that you want to use.
export default defineConfig({
  shopify: {
    defaultCountryCode: 'US',
    defaultLanguageCode: 'EN',
    storeDomain: 'YOUR_STORE_NAME.myshopify.com',
    storefrontToken: 'YOUR_STOREFRONT_ACCESS_TOKEN',
    storefrontApiVersion: '2022-07',
  },
});

Step 3: Start a development server

Create a new local development server to start testing your changes.

1. Navigate to your project directory

Navigate to the root of your project directory:

cd <directory>

2. Start the development server

Start up a new local development server on localhost:

yarn dev

The development environment will open automatically at http://localhost:3000.

Step 4: Install Rebuy + Hydrogen Package

Once you have successfully created your new Hydrogen app and linked it to your Shopify store, it's now time to install the Rebuy + Hydrogen package. If you currently have your development server running, you can terminate the server with the following command Ctrl + C.

1. Navigate to your project directory

Navigate to the root of your project directory:

cd <directory>

2. Install the Rebuy + Hydrogen package

Install @rebuy/rebuy-hydrogen with the following command:

yarn add @rebuy/rebuy-hydrogen

3. Update your .env with your Rebuy public API key

You can find your Rebuy public API key in Rebuy admin > Account > API Keys. Once located, update your .env with the following:

PUBLIC_REBUY_API_KEY=yourRebuyAPIKey

If your project does not have an .env file, you can create a new one and save it in the project root directory.

Step 5: Build Personalized Shopping Experiences

Once you have included Rebuy + Hydrogen in your project, it's time to start building dynamic, personalized shopping experiences! In this tutorial, we will accomplish the following:

  • Customize the product details page
  • Display a list of AI-powered product recommendations
  • Display a list of recently viewed products

1. Install the RebuyContextProvider

Open ./src/App.server.jsx and import the RebuyContextProvider so all Rebuy API calls are enriched with contextual information. Open the file and make the following edits:

Import the provider
import {RebuyContextProvider} from '@rebuy/rebuy-hydrogen/RebuyContextProvider.client';
Add RebuyContextProvider component

Wrap the FileRoutes and Route components with RebuyContextProvider, as follows:

<Router>
  <RebuyContextProvider>
    <FileRoutes
      basePath={countryCode ? `/${countryCode}/` : undefined}
      routes={routes}
    />
    <Route path="*" page={<NotFound />} />
  </RebuyContextProvider>
</Router>

2. Customize the Product Details Page

Now let's add a few of the provided Rebuy components to your product pages. Open up the products route file, located here: ./src/routes/products/[handle].server.jsx

Import Rebuy components

Import the RebuyProductRecommendations and RebuyRecentlyViewedProducts client components into the products/[handle].server.jsx file. We will be wrapping each of them in a RebuyWidgetContainer component, which will give us an interface to request data from Rebuy. Let's import that as well, and also include RebuyProductViewed (to keep track of any products viewed) while we're here:

import {RebuyProductRecommendations} from '@rebuy/rebuy-hydrogen/RebuyProductRecommendations.client';
import {RebuyProductViewed} from '@rebuy/rebuy-hydrogen/RebuyProductViewed.client';
import {RebuyRecentlyViewedProducts} from '@rebuy/rebuy-hydrogen/RebuyRecentlyViewedProducts.client';
import {RebuyWidgetContainer} from '@rebuy/rebuy-hydrogen/RebuyWidgetContainer.client';
Add Recommended Products to your product pages

Find the <ProductOptionsProvider data={product}> tag, and insert the RebuyProductRecommendations component after the first closing </Section> tag:

{/* REBUY: Product Recommendations */}
<Suspense>
  <RebuyWidgetContainer
    product={product}
    dataSource="/api/v1/products/recommended"
    limit="6"
  >
    <RebuyProductRecommendations />
  </RebuyWidgetContainer>
</Suspense>
Add Recently Viewed Products to your product pages

Finally, add the RebuyRecentlyViewedProducts and RebuyProductViewed components in the same location:

{/* REBUY: Recently Viewed Products */}
<Suspense>
  <RebuyWidgetContainer
    product={product}
    dataSource="/api/v1/products/viewed"
    limit="3"
  >
    <RebuyRecentlyViewedProducts />
  </RebuyWidgetContainer>
</Suspense>

<Suspense>
  <RebuyProductViewed product={product} />
</Suspense>

The exact placement is up to you, provided the imported Rebuy components remain children of Hydrogen's included <ProductOptionsProvider> component.

Review your changes

When you look at the product details page, you should now see two new sections:

  1. AI-powered product recommendations
  2. Recently viewed products

Additionally, we included the <RebuyProductViewed product={product} /> component, which will automatically send a user -> viewed -> product event to Rebuy. This event is powering the recently viewed component in real-time! As you navigate the site, your browsing history will be tracked and display for easy navigation to previous product pages!

As a visitor's cart changes — such as adding or removing cart lines, updating quantities, etc — your Rebuy powered, smart components will automatically refresh and stay up-to-date, ensuring any established data source rules are applied, and the desired personalization takes effect.