> ## 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.

# Installation

> Add the browser-safe Shoppex Storefront SDK to a custom headless storefront

<Warning>
  This SDK is for custom browser/headless storefronts. Hosted Shoppex themes use
  ThemeDocuments and the platform commerce runtime. Start at
  [Theme Development](/themes/introduction) for hosted theme work.
</Warning>

## CDN (Recommended)

Fastest way to get started — one script tag, no build step. Use npm instead if you have a bundler and want TypeScript types.

```html theme={"system"}
<script src="https://cdn.shoppex.io/sdk/v1.0/shoppex.umd.js"></script>
```

For ESM imports without npm, load the module build directly:

```html theme={"system"}
<script type="module">
  import shoppex from 'https://cdn.shoppex.io/sdk/v1.0/shoppex.esm.js';

  shoppex.init('your-store');
</script>
```

<Warning>
  Use `@shoppexio/storefront` for browser/headless storefront code. Use `@shoppexio/sdk` only from trusted backend code.
</Warning>

## npm / yarn / pnpm

Install the SDK as a dependency:

<CodeGroup>
  ```bash npm theme={"system"}
  npm install @shoppexio/storefront
  ```

  ```bash yarn theme={"system"}
  yarn add @shoppexio/storefront
  ```

  ```bash pnpm theme={"system"}
  pnpm add @shoppexio/storefront
  ```
</CodeGroup>

Then import and use:

```typescript theme={"system"}
import shoppex from '@shoppexio/storefront';

shoppex.init('your-store');
```

## Initialization

After loading the SDK, initialize it with your store slug:

```javascript theme={"system"}
shoppex.init('your-store', {
  locale: 'en',        // Optional: default language
  currency: 'USD',     // Optional: default currency
});
```

<ParamField path="storeSlug" type="string" required>
  Your store's unique identifier. Find this in your Shoppex dashboard under Settings.
</ParamField>

<ParamField path="options.locale" type="string" default="en">
  Default language for the SDK. Affects price formatting and checkout language.
</ParamField>

<ParamField path="options.currency" type="string">
  Override the store's default currency. Must be a valid ISO 4217 currency code.
</ParamField>

## Verify Installation

Check if the SDK is loaded and initialized:

```javascript theme={"system"}
// Check if SDK is loaded
if (typeof shoppex !== 'undefined') {
  console.log('SDK loaded');
}

// Check if SDK is initialized
if (shoppex.isInitialized()) {
  console.log('SDK initialized for:', shoppex.getConfig().storeSlug);
}
```

## TypeScript Support

The SDK includes TypeScript definitions. Import types directly:

```typescript theme={"system"}
import shoppex, {
  type Product,
  type CartItem,
  type ShoppexConfig
} from '@shoppexio/storefront';
```

## Browser Support

The SDK supports all modern browsers:

| Browser | Minimum Version |
| ------- | --------------- |
| Chrome  | 60+             |
| Firefox | 55+             |
| Safari  | 12+             |
| Edge    | 79+             |

<Note>
  Internet Explorer is not supported. The SDK uses modern JavaScript features like Promises, async/await, and ES6+ syntax.
</Note>

## Next Steps

<CardGroup cols={2}>
  <Card title="Quick Start" icon="rocket" href="/sdk/quickstart">
    Fetch products and build a cart in under 5 minutes.
  </Card>

  <Card title="Store API" icon="store" href="/sdk/api/store">
    Load store metadata, products, and groups.
  </Card>
</CardGroup>