@replohq/sdk

v1.13.0

Published

4 hours ago

Replo SDK — cart, analytics, and data loaders for agent-built Next.js sites.

0High
0Medium
0Low

`@replohq/sdk`

The Replo SDK provides the React providers, data loaders, cart utilities, analytics, consent handling, routing helpers, and Next.js integrations used by Replo-powered storefronts.

Installation

Install the SDK and its runtime peers in a Next.js application:

pnpm add @replohq/sdk @opennextjs/cloudflare @tanstack/react-query

The application must use Next.js 15 or newer and React 18.2 or newer. React, React DOM, and their type packages are peer dependencies and are normally already present in a Next.js application.

Set up the provider

Mount ReploProvider once around the application. It provides the query client, cart state, analytics, and loader error handling used by the rest of the SDK. Render managed third-party scripts separately with ReploScripts from @replohq/sdk/consent/replo-scripts.

// app/layout.tsx
import { ReploProvider } from "@replohq/sdk/providers/replo-provider";

export default function RootLayout({ children }: React.PropsWithChildren) {
  return (
    <html lang="en">
      <body>
        <ReploProvider>{children}</ReploProvider>
      </body>
    </html>
  );
}

ReploProvider is an async Server Component. Components that use SDK hooks or loaders must render beneath it.

Buy now checkout

Use useBuyNow from @replohq/sdk/cart/hooks/use-buy-now to send a shopper directly to checkout. Shopify checkout applies selling plans and discount codes. Stripe checkout ignores both, logs a server warning when either is supplied, and still creates the checkout session.

Data loaders

Data loaders retrieve data from integrations configured for the Replo project. Use constants from DATA_LOADER_KEYS instead of copying loader-key strings. The key selects the integration operation and is also the first part of the React Query cache key.

Loader components are Client Components that pass data to a render function:

// components/product-title.tsx
"use client";

import { ProductLoader } from "@replohq/sdk/loaders/product-loader";
import { DATA_LOADER_KEYS } from "@replohq/sdk/loaders/loader-keys";

export function ProductTitle({ handle }: { handle: string }) {
  return (
    <ProductLoader
      loaderKey={DATA_LOADER_KEYS.SHOPIFY_PRODUCT}
      handle={handle}
      loadingFallback={<p>Loading…</p>}
      fallback={<p>Product unavailable.</p>}
    >
      {(product) => <h1>{product.title}</h1>}
    </ProductLoader>
  );
}

Loader environments and integrations

Loaders fetch on the server: directly during SSR, and through a Server Action after hydration. The application needs its Replo project configuration in every environment:

During local development and builds, wrangler.jsonc must provide CANOPY_API_HOST and PROJECT_ID in vars.
In a deployed OpenNext/Cloudflare environment, provide the same values as runtime bindings.
Connect each integration in the Replo project; the site holds no provider credentials.

Use these public loader components and keys for each configured integration:

| Integration | Loader component | DATA_LOADER_KEYS value | | --- | --- | --- | | Shopify Storefront | ProductLoader | SHOPIFY_PRODUCT | | Replo product catalog | ProductLoader | REPLO_PRODUCT | | Shopify Storefront | CollectionLoader | SHOPIFY_COLLECTION | | Shopify Storefront | CollectionProductsLoader | SHOPIFY_COLLECTION_PRODUCTS | | Shopify Storefront | MetaobjectLoader | SHOPIFY_METAOBJECT | | Shopify Storefront | MetaobjectsLoader | SHOPIFY_METAOBJECTS | | Okendo | OkendoReviewsLoader | OKENDO_PRODUCT_REVIEWS | | Okendo | OkendoReviewAggregateLoader | OKENDO_PRODUCT_REVIEW_AGGREGATE | | Rebuy | RebuyRecommendationsLoader | REBUY_RECOMMENDATIONS | | Levanta | LevantaProductLoader | LEVANTA_PRODUCT | | Smile.io | SmileVipTiersLoader | SMILE_IO_VIP_TIERS | | Smile.io | SmileEarningRulesLoader | SMILE_IO_EARNING_RULES | | Smile.io | SmileRewardsLoader | SMILE_IO_REWARDS | | Yotpo | YotpoReviewsLoader | YOTPO_PRODUCT_REVIEWS | | Yotpo | YotpoReviewAggregateLoader | YOTPO_PRODUCT_REVIEW_AGGREGATE | | Reviews.io | ReviewsIoReviewsLoader | REVIEWS_IO_PRODUCT_REVIEWS | | Reviews.io | ReviewsIoReviewAggregateLoader | REVIEWS_IO_PRODUCT_REVIEW_AGGREGATE | | Loox | LooxReviewsLoader | LOOX_PRODUCT_REVIEWS | | Loox | LooxReviewAggregateLoader | LOOX_PRODUCT_REVIEW_AGGREGATE | | Judge.me | JudgemeReviewsLoader | JUDGEME_PRODUCT_REVIEWS | | Judge.me | JudgemeReviewAggregateLoader | JUDGEME_PRODUCT_REVIEW_AGGREGATE | | Statsig | StatsigExperimentLoader | STATSIG_EXPERIMENT | | Contentful | ContentfulEntryLoader | CONTENTFUL_ENTRY | | Contentful | ContentfulEntriesLoader | CONTENTFUL_ENTRIES |

Import each component from its kebab-case subpath, for example CollectionLoader from @replohq/sdk/loaders/collection-loader.

Prefetch on the server

PrefetchedLoaders is a Server Component that fetches loader data during SSR and hydrates the React Query cache. Wrap the matching Client Component to avoid a loading state on the first paint:

// app/products/[handle]/page.tsx
import { PrefetchedLoaders } from "@replohq/sdk/loaders/prefetch-loaders";
import { DATA_LOADER_KEYS } from "@replohq/sdk/loaders/loader-keys";

import { ProductTitle } from "../../../components/product-title";

export default async function ProductPage({
  params,
}: {
  params: Promise<{ handle: string }>;
}) {
  const { handle } = await params;

  return (
    <PrefetchedLoaders
      queries={[
        {
          loaderKey: DATA_LOADER_KEYS.SHOPIFY_PRODUCT,
          args: { handle },
        },
      ]}
    >
      <ProductTitle handle={handle} />
    </PrefetchedLoaders>
  );
}

The loaderKey and complete args object must exactly match the props used by the loader component, including optional locale, pagination, or metafield arguments. PrefetchedLoaders accepts revalidateSeconds per query; it defaults to 60 seconds, and false enables indefinite tag-based caching.

Server-only code that does not hydrate a loader component can call invokeLoaderServer from @replohq/sdk/loaders/invoke-loader-server.

License

This package is proprietary software. See LICENSE (SEE LICENSE IN LICENSE) and the Replo Terms of Service.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme