Skip to content

Hydrogen SDK: Getting Started

Beta SDK

These SDKs are currently in beta. APIs may change before stable release.

React components and hooks for integrating Rebuy's personalization engine into Shopify Hydrogen storefronts.

Installation

npm install @rebuy/core-sdk @rebuy/hydrogen-sdk

Peer Dependencies:

  • React 18+
  • @shopify/hydrogen 2024.4+

Quick Start

1. Setup the Provider

Wrap your Hydrogen app with RebuyProvider in your root.tsx:

// app/root.tsx
import { RebuyProvider } from '@rebuy/hydrogen-sdk';

export default function App() {
    return (
        <html lang="en">
            <body>
                <RebuyProvider apiKey="your-rebuy-api-key">
                    <Layout>
                        <Outlet />
                    </Layout>
                </RebuyProvider>
            </body>
        </html>
    );
}

2. Choose Your Implementation Approach

The SDK supports both server-side and client-side rendering patterns.

Pattern Best For Benefits
Server-side (Recommended) Most widgets, cart-based recommendations SEO, faster loads, automatic cart reactivity
Client-side Recently Viewed, browser-dependent features Access to localStorage, real-time interactions

See Implementation Patterns for detailed guidance.

Environment Variables

Set up your environment variables:

# .env
PUBLIC_REBUY_API_KEY=your-rebuy-api-key
REBUY_SDK_DEBUG=true  # optional - enables debug logging

The getRebuyData helper and RebuyProvider will automatically use these.

Example: Server-Side Widget

Here's a complete example of a server-side rendered widget:

// app/routes/($locale)._index.tsx
import { getRebuyData } from '@rebuy/hydrogen-sdk';
import { defer, type LoaderFunctionArgs } from '@shopify/remix-oxygen';
import { useLoaderData } from 'react-router';

export async function loader({ context, request }: LoaderFunctionArgs) {
    const { rebuy } = await getRebuyData({ context, request });

    // Fetch data on the server
    const topSellers = await rebuy.sdk.products.getTopSellers({
        limit: 5,
        filter_oos: 'yes',
    });

    return defer({ topSellers });
}

export default function Homepage() {
    const { topSellers } = useLoaderData<typeof loader>();

    return (
        <section>
            <h2>Top Sellers</h2>
            <div className="product-grid">
                {topSellers.map((product) => (
                    <div key={product.id}>
                        <img src={product.image?.src} alt={product.title} />
                        <h3>{product.title}</h3>
                        <p>${product.variants?.[0]?.price}</p>
                    </div>
                ))}
            </div>
        </section>
    );
}

Key Benefits:

  • Products are in the initial HTML (SEO-friendly)
  • No loading spinners or layout shifts
  • Automatically updates when cart changes (cart reactivity)

Example: Client-Side Widget

For features like Recently Viewed that need browser access:

// app/routes/($locale).products.$handle.tsx
import { RebuyProductView, RecentlyViewed } from '@rebuy/hydrogen-sdk';

export default function Product() {
    const { product } = useLoaderData<typeof loader>();

    return (
        <div className="product">
            {/* Track this product view */}
            <RebuyProductView
                product={{
                    id: product.id,
                    handle: product.handle,
                }}
            />

            <h1>{product.title}</h1>
            {/* ... product details ... */}

            {/* Display recently viewed products */}
            <section>
                <h2>Recently Viewed</h2>
                <RecentlyViewed limit={4} />
            </section>
        </div>
    );
}

Next Steps

See something that needs updating? Suggest an edit