> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shoppex.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Storefront SDK

> Build headless or embedded storefronts with the browser-safe Shoppex Storefront SDK.

# Storefront SDK

The Storefront SDK is for **custom storefronts outside the Shoppex hosted theme runtime**.

Use it when you build your own customer-facing surface, for example:

* a Next.js or Astro storefront
* a plain HTML embed on an existing site
* a React Native app with a small web checkout handoff
* a SaaS app that sells add-ons from its own UI

<Warning>
  Do not use this page as the hosted theme guide. Hosted Shoppex storefronts use ThemeDocuments. Start at [Theme Development](/themes/introduction) for theme work.
</Warning>

## Package Names

Use `@shoppexio/storefront` in browser/headless storefront code.

Use `@shoppexio/sdk` only on trusted servers that call the Developer API.

Simple example:

* Browser product grid: `@shoppexio/storefront`
* Backend order automation: `@shoppexio/sdk`
* Hosted Shoppex theme: ThemeDocument plus platform commerce runtime

## What The Storefront SDK Does

<CardGroup cols={2}>
  <Card title="Public Catalog Reads" icon="box">
    Fetch store metadata, products, groups, reviews, and listing data from public storefront endpoints.
  </Card>

  <Card title="Browser Cart State" icon="cart-shopping">
    Add, update, and remove cart items. Cart data persists locally in the browser.
  </Card>

  <Card title="Hosted Checkout Handoff" icon="lock">
    Create a checkout handoff and redirect customers to Shoppex hosted checkout.
  </Card>

  <Card title="Framework Neutral" icon="feather">
    Works with React, Vue, Svelte, Astro, plain HTML, or any browser runtime.
  </Card>
</CardGroup>

## Quick Example

```html theme={"system"}
<script src="https://cdn.shoppex.io/sdk/v1.0/shoppex.umd.js"></script>
<script>
  shoppex.init('your-store');

  const response = await shoppex.getStorefront();
  const products = response.data.products;

  products.forEach((product) => {
    console.log(product.title, product.cdn_image_url);
  });

  shoppex.addToCart('product-id', 'variant-id', 1);
  await shoppex.checkout();
</script>
```

## Use The Dev API For Server Work

The Storefront SDK is browser-safe and public. It does not replace the Developer API.

Use the Developer API from your server when you need to:

* create catalog-backed orders
* manage customers
* validate licenses
* fulfill orders
* manage webhooks
* read private operational data

Never ship a secret `shx_...` API key in browser code.

## Next Steps

<CardGroup cols={2}>
  <Card title="Installation" icon="download" href="/sdk/installation">
    Add the SDK via CDN or npm.
  </Card>

  <Card title="Quick Start" icon="rocket" href="/sdk/quickstart">
    Build your first embedded storefront.
  </Card>

  <Card title="Theme Development" icon="palette" href="/themes/introduction">
    Build the Shoppex-hosted theme surface.
  </Card>

  <Card title="Developer API SDKs" icon="server" href="/api-reference/sdks">
    Use `@shoppexio/sdk` from trusted backend code.
  </Card>
</CardGroup>