Kaching Bundles for React

A React component for integrating Kaching Bundles into your React-based Shopify store.

Installation

npm install @kachingappz/bundles-react
# or
yarn add @kachingappz/bundles-react
# or
pnpm add @kachingappz/bundles-react

Usage

import {
  KachingBundle,
  fetchKachingBundlesData,
} from "@kachingappz/bundles-react"

const [kachingBundlesData, setKachingBundlesData] = useState(null)

useEffect(() => {
  const loadData = async () => {
    const data = await fetchKachingBundlesData(
      {
        shopifyDomain: "your-store.myshopify.com",
        storefrontAccessToken: "your-storefront-access-token",
      },
      {
        productId: "gid://shopify/Product/123456789",
        dealBlockId: "abc123", // optional - specify which deal block to display
        country: "US", // optional
        language: "EN", // optional
      },
    )

    setKachingBundlesData(data)
  }

  loadData()
}, [])

{
  kachingBundlesData && (
    <KachingBundle
      data={kachingBundlesData}
      selectedVariantId={selectedVariant.id}
      onLinesChange={(lines) => {
        // lines structure:
        // [
        //   {
        //     merchandiseId: "gid://shopify/ProductVariant/123456789",
        //     quantity: 2,
        //     attributes: [{ key: "__kaching_bundles", value: "{ id: 'abc' }" }],
        //     sellingPlanId: "gid://shopify/SellingPlan/987654321" // optional
        //   }
        // ]
        setLines(lines)
      }}
    />
  )
}

Preview Mode

If bundle data is not available (e.g., during development or testing), you can use preview mode instead:

<KachingBundle
  preview={{
    price: 19.99,
    color: "#00CC6A",
    cornerRadius: 10,
  }}
/>

Usage with Hydrogen

1. Import the required components:

import {
  KachingBundle,
  fetchKachingBundlesData,
} from "@kachingappz/bundles-react"

2. Set up the data loader:

function loadDeferredData({ context, params }, productId, dealBlockId) {
  const kachingBundlesData = fetchKachingBundlesData(context.storefront, {
    productId,
    dealBlockId, // optional - specify which deal block to display
  })

  return {
    kachingBundlesData,
  }
}

3. Use the component in your product page:

const { kachingBundlesData } = useLoaderData()

return (
  <ClientOnly>
    <Await resolve={kachingBundlesData}>
      {(data) => (
        <KachingBundle
          data={data}
          selectedVariantId={selectedVariant.id}
          onLinesChange={(lines) => setLines(lines)}
        />
      )}
    </Await>
  </ClientOnly>
)

Usage in iframes

Pass the iframe's window context using targetWindow. This ensures the custom element CSS and JavaScript are injected into the iframe's document:

import Frame, { FrameContextConsumer } from "react-frame-component"
import { KachingBundle } from "@kachingappz/bundles-react"

<Frame>
  <FrameContextConsumer>
    {({ window: iframeWindow }) => (
      <KachingBundle
        targetWindow={iframeWindow}
        data={kachingBundlesData}
      />
    )}
  </FrameContextConsumer>
</Frame>

Supported Storefront API Clients

The component supports the following Storefront API clients:

• @shopify/hydrogen
• @shopify/react-hydrogen
• @shopify/storefront-api-client

Support

For support, please contact the Kaching Bundles team through our help center.