@ecom-atelier/shopify-buy-box

Reusable React Buy Box for Shopify storefronts managed by the Ecom Atelier central Buy Box backend.

The package gets the Shopify storefront connection and the page-specific Buy Box configuration from the central Supabase Edge Function by siteKey + pagePath. Shopify remains the pricing authority. Discount Kit metadata defines available quantity offers, while real prices and checkout URLs come from Shopify Cart API evaluation.

Install

npm install @ecom-atelier/shopify-buy-box

Recommended Lovable setup

Configure the store once at app level:

import {
  BuyBoxProvider,
} from "@ecom-atelier/shopify-buy-box";

import "@ecom-atelier/shopify-buy-box/style.css";

<BuyBoxProvider siteKey="adventure-shop">
  <App />
</BuyBoxProvider>

Then any page can add the Buy Box with:

import {
  BuyBoxSection,
} from "@ecom-atelier/shopify-buy-box";

<BuyBoxSection />

BuyBoxSection automatically uses the current browser pathname, so each page resolves its own central configuration by:

siteKey + pagePath

It also defaults to a full-width landing-page section so common narrow Lovable content wrappers do not squeeze the Buy Box.

For another Shopify storefront, configure that project once with a different registered site key:

<BuyBoxProvider siteKey="ergowohl">
  <App />
</BuyBoxProvider>

The corresponding buy_box_sites row must already exist in the central Supabase project.

Short Lovable prompts

First Buy Box in a new project:

Install and set up @ecom-atelier/shopify-buy-box for this project using site key "adventure-shop". Follow the package's recommended Lovable setup, and add the Buy Box at the main purchase point of this page.

That one-time setup should install the package, import its stylesheet, wrap the app in BuyBoxProvider, and insert BuyBoxSection on the current page.

Additional pages in the same project:

Add the Ecom Atelier Buy Box at the main purchase point of this page.

Direct usage

The lower-level component remains available:

import {
  BuyBox,
} from "@ecom-atelier/shopify-buy-box";

<BuyBox siteKey="adventure-shop" />

Optional section overrides

<BuyBoxSection
  pagePath="/summer-sale"
  productHandle="fallback-product-handle"
  size="large"
  fullBleed={true}
/>

productHandle is only a fallback for pages that do not yet have a saved central configuration.

Central API URL

The Ecom Atelier API URL is built in as the default and is normally inherited from BuyBoxProvider.

Editor

With editorMode="auto", the settings editor is visible in the embedded Lovable editor preview and on localhost, but hidden on normal customer-facing pages.

The editor key is verified and writes are authorized by the central Supabase Edge Function. Never put the editor key or Supabase service-role key into this package.

Architecture

Lovable / React project
        ↓
<BuyBoxProvider siteKey="..." />
        ↓
<BuyBoxSection />
        ↓
Central Supabase Buy Box API
        ↓
buy_box_sites + buy_box_configs
        ↓
Shopify Storefront API
        ↓
Discount Kit metadata + Shopify Cart pricing
        ↓
Shopify checkout