@shopkit/apps-platform-react

React storefront surfaces + builder widgets for the Apps Platform. This is the layer a storefront (e.g. storefront-starter) uses to mount sandboxed marketplace apps into its UI. It wraps @shopkit/apps-platform's host adapter with a provider, slot components, server helpers, and template widgets.

Install

npm install @shopkit/apps-platform-react

Exports

| Import | Purpose | | --- | --- | | AppsRuntimeProvider | Root provider — resolves installed apps, mints/refreshes session JWTs, registers RPC handlers, broadcasts host→app events. Mount near the top of your layout. | | EmbeddedApps | Renders site-wide embed-surface apps at their manifest position. | | AppBlockSlot | Mounts block-surface apps for a given block handle (used inside templates). | | AppAccountSlot | Mounts account-extension apps at a named account slot. | | storefrontRpcHandlers | Default host RPC bridge — the five cart methods over the @shopkit/cart store. Merged with any custom handlers you pass. | | appBlockZone (./constants) | Template-widget factory for declaring a block mount point in a theme template. Also APPS_PLATFORM_WIDGET_TYPES, AppBlockZone / AppBlock / AppAccount. | | createAppsPlatformClient, createInstalledAppsGetHandler, createInstalledAppsResolvers (./server) | Server-side client + Next.js route handlers for the App Ecosystem backend. |

Quick usage

1. Provider in your root layout (shellUrl defaults to the Ratio sandbox; override per env):

import { AppsRuntimeProvider } from "@shopkit/apps-platform-react";

<AppsRuntimeProvider
  merchantInfo={merchantInfo}
  shellUrl={process.env.RATIO_APPS_SHELL_URL}
  /* custom rpcHandlers are merged over storefrontRpcHandlers */
>
  {children}
</AppsRuntimeProvider>;

2. Installed-apps route (app/api/v1/apps/installed/route.ts):

import {
  createInstalledAppsGetHandler,
  createInstalledAppsResolvers,
} from "@shopkit/apps-platform-react/server";

export const GET = createInstalledAppsGetHandler(
  createInstalledAppsResolvers({ baseUrl: process.env.RATIO_APPS_API_URL }),
);
export const dynamic = "force-dynamic";

3. Place a block in a theme template with appBlockZone, or mount a slot directly with <AppBlockSlot> / <AppAccountSlot>. Embeds mount automatically via the provider by their manifest position.

Configuration

| Env var | Purpose | | --- | --- | | RATIO_APPS_API_URL | App Ecosystem backend that returns the installed-apps list and mints session JWTs. | | RATIO_APPS_SHELL_URL | The sandbox shell URL every app iframe loads (https://apps.ratio.win/sandbox.html in prod). |

See ARCHITECTURE.md for the internal design.