Using with React

Patterns for consuming the Elite Bundle Builder SDK from a React app embedded in a Shopify theme: hooks, events and cart actions.

The SDK is framework-agnostic — it exposes plain JavaScript objects and events. This guide shows patterns for consuming the SDK inside a React app embedded in a Shopify theme.

---

Setup

Install your React app however you like (a <script type="module"> tag, Vite, or a bundled file). It just needs to run on the same page as the bundle.

The SDK is always available at window.eliteBundle — no install or import required. You access it from React via refs and effects, the same as any other global.

---

1. Wait for ready and sync to state

Use a useEffect to subscribe to the ready event, then mirror the SDK state into React.

import { useState, useEffect, useCallback } from 'react';

interface ByobSDK {
  steps: any[];
  cart: any[];
  cartTotalFormatted: string;
  canCheckout: boolean;
  addToCart: (product: any, variantId: string, stepId?: string) => void;
  checkout: (target?: "stay_on_page" | "cart" | "checkout") => Promise<void>;
  formatPrice: (amount: number) => string;
}

function useBundleSDK() {
  const [sdk, setSdk] = useState<ByobSDK | null>(null);
  const [isReady, setIsReady] = useState(false);
  const [error, setError] = useState<string | null>(null);

  useEffect(() => {
    if (!window.eliteBundle?.sdk) return; // SDK not enabled

    function onReady() {
      setSdk(window.eliteBundle.sdk.byob);
      setIsReady(true);
    }

    function onError(e: CustomEvent<{ error: string }>) {
      setError(e.detail.error);
    }

    document.addEventListener('elite:byob:ready', onReady);
    document.addEventListener('elite:byob:error', onError as EventListener);

    // Handle ready already fired
    const current = window.eliteBundle.sdk.byob;
    if (current && !current.isLoading && !current.error) onReady();

    return () => {
      document.removeEventListener('elite:byob:ready', onReady);
      document.removeEventListener('elite:byob:error', onError as EventListener);
    };
  }, []);

  return { sdk, isReady, error };
}

---

2. Sync cart state from SDK events

The SDK state lives outside your React tree, and the SDK object is replaced on every update — so a value you put in state goes stale. Subscribe to events for live updates, and read window.eliteBundle.sdk.byob fresh when you act on it.

function useByobCart() {
  const [cart, setCart] = useState([]);
  const [cartTotal, setCartTotal] = useState('$0.00');
  const [canCheckout, setCanCheckout] = useState(false);

  useEffect(() => {
    function onCartChange(e: CustomEvent) {
      const { cart, cartTotal, canCheckout } = e.detail;
      setCart(cart);
      // The detail carries the raw number — format it for display.
      setCartTotal(window.eliteBundle.sdk.byob.formatPrice(cartTotal));
      setCanCheckout(canCheckout);
    }

    document.addEventListener('elite:byob:cart-change', onCartChange as EventListener);
    return () => {
      document.removeEventListener('elite:byob:cart-change', onCartChange as EventListener);
    };
  }, []);

  return { cart, cartTotal, canCheckout };
}

---

3. Example component

function BundleBuilder() {
  const { sdk, isReady, error } = useBundleSDK();
  const { cart, cartTotal, canCheckout } = useByobCart();
  const [isCheckingOut, setIsCheckingOut] = useState(false);

  const handleCheckout = useCallback(async () => {
    if (!sdk || !canCheckout) return;
    setIsCheckingOut(true);
    try {
      await sdk.checkout('checkout');
    } finally {
      setIsCheckingOut(false);
    }
  }, [sdk, canCheckout]);

  if (error) return <p>Error: {error}</p>;
  if (!isReady || !sdk) return <p>Loading…</p>;

  return (
    <div>
      {sdk.steps.map(step => (
        <StepSection key={step.id} step={step} sdk={sdk} />
      ))}

      <CartDrawer
        cart={cart}
        cartTotal={cartTotal}
        canCheckout={canCheckout}
        isCheckingOut={isCheckingOut}
        onCheckout={handleCheckout}
      />
    </div>
  );
}

---

4. Per-card quantity state

Instead of storing quantities in React state (which would require diffing the cart array on every change), read them directly from the SDK on demand.

function ProductCard({ product, variant, stepId }) {
  const [qty, setQty] = useState(0);

  useEffect(() => {
    function sync() {
      const sdk = window.eliteBundle?.sdk?.byob;
      if (!sdk) return;
      setQty(sdk.getItemQuantity(variant.id, stepId));
    }

    document.addEventListener('elite:byob:cart-change', sync);
    sync(); // initialize

    return () => document.removeEventListener('elite:byob:cart-change', sync);
  }, [variant.id, stepId]);

  const handleAdd = () => {
    const sdk = window.eliteBundle?.sdk?.byob;
    sdk?.addToCart(product, variant.id, stepId);
  };

  const handleInc = () => {
    window.eliteBundle?.sdk?.byob?.updateQuantity(variant.id, 1, stepId);
  };

  const handleDec = () => {
    window.eliteBundle?.sdk?.byob?.updateQuantity(variant.id, -1, stepId);
  };

  return (
    <div>
      <img src={product.featuredImage?.url} alt={product.title} />
      <p>{product.title}</p>
      {qty > 0 ? (
        <div>
          <button onClick={handleDec}>−</button>
          <span>{qty}</span>
          <button onClick={handleInc}>+</button>
        </div>
      ) : (
        <button onClick={handleAdd} disabled={!variant.available}>
          {variant.available ? 'Add' : 'Sold out'}
        </button>
      )}
    </div>
  );
}

---

TypeScript

The SDK is not published as an npm package, so copy the interfaces you need from the Bundle SDK Reference into your own types.ts.

Or add a global declaration to extend the Window type:

// types.d.ts
declare global {
  interface Window {
    eliteBundle: {
      version: string;
      app: Record<string, unknown>;
      byob: Record<string, unknown> | null;
      sdk?: {
        byob: BundleSDK | null;   // your copied interface
      };
      on(event: string, cb: EventListener): void;
      off(event: string, cb: EventListener): void;
    };
  }
}