npm and React

The SDK, the embed and the Checkout Kit are each one script tag. On a site built with npm, two packages put them in your code instead:


`@shoplygg/js`	The three, loaded when a page first needs them, with TypeScript types
`@shoplygg/react`	The same as React components and hooks, for React 18 or newer

npm install @shoplygg/js
# or, with React
npm install @shoplygg/react

Both load Shoply’s own hosted scripts from shoply.gg, the same files a script tag loads. A fix to one reaches your site without you updating the package. Each script is loaded once a page, the first time something asks for it. They run in the browser. With a framework that renders on a server (Next.js, Remix), the React components draw their element there and start once they are in the browser. With @shoplygg/js, call it from an effect or an event handler, not while rendering.

With React

The SDK

import { ShoplyProvider, useShoply, usePageView } from "@shoplygg/react";

export default function Layout({ children }) {
  return <ShoplyProvider storeId="YOUR_STORE_ID">{children}</ShoplyProvider>;
}

function Products() {
  const { shoply, ready } = useShoply();
  // shoply.getProducts(), shoply.addToBasket(), shoply.checkout(email)...
}

shoply is null until the SDK has started. Every method is in the SDK reference. options on the provider are shoply.init()’s, such as currency and track. A site whose router changes the page without loading one counts each page it shows:

usePageView(pathname);

The embed

import { EmbedButton } from "@shoplygg/react";

<EmbedButton product="PRODUCT_ID" variant="VARIANT_ID" className="buy" onPaid={() => router.push("/thanks")}>
  Buy now
</EmbedButton>

A button that opens the checkout over the page. It takes the embed’s options (product, variant, quantity, coupon, theme, email, billing) and anything a button takes. useEmbed() answers open and close, to open it from anywhere else.

The Checkout Kit

import { CheckoutKit, KitPiece, useCheckoutKit } from "@shoplygg/react";

<CheckoutKit items={basket} look={{ accent: "#12a37f", radius: 6 }} onPaid={() => router.push("/thanks")}>
  <aside>
    <KitPiece name="summary" />
  </aside>
  <main>
    <KitPiece name="email" />
    <KitPiece name="payment" />
    <KitPiece name="pay" />
  </main>
</CheckoutKit>

Put the pieces anywhere under <CheckoutKit>, one of them checkout or payment. Its options are the Kit’s, and a change to them after it is up (the cart, the look) is passed to the Kit, so the checkout follows your page’s own basket. useCheckoutKit() answers the Kit, for kit.pay() from a button of your own. onPaid tells the page only: it is no proof of payment. Your server hears of a paid order from webhooks.

Without React

import { initShoply, openEmbed, onCheckout, createKit } from "@shoplygg/js";

const shoply = await initShoply("YOUR_STORE_ID");
const store = await shoply.getStore();

button.addEventListener("click", () => openEmbed({ product: "PRODUCT_ID" }));
onCheckout({ onPaid: () => showThanks() });

const kit = await createKit({ product: "PRODUCT_ID" });
kit.place("payment", "#payment").place("summary", "#order");


`initShoply(storeId, options)`	Loads the SDK and starts it for your store, once a page
`loadShoply()`	Loads the SDK without starting it
`openEmbed(options)`	Opens the checkout over the page
`loadEmbed()`	Loads the embed: `{ open, close }`
`onCheckout({ onPaid, onClose })`	Listens for an order paid through the embed or the Kit. Answers a function that stops listening.
`createKit(options)`	Makes a Checkout Kit, with every element marked `data-shoply-piece` placed
`loadKit()`	Loads the Kit: the `shoplyKit()` function

Types

Both packages carry TypeScript types: the store, products, variants, the basket, the embed’s and the Kit’s options and events. A field Shoply adds later is there before the types name it, as unknown.

Start

The checkout on your site

shoply.js

With React

The SDK

The embed

The Checkout Kit

Without React

Types

​With React

​The SDK

​The embed

​The Checkout Kit

​Without React

​Types

With React

The SDK

The embed

The Checkout Kit

Without React

Types