---
title: Core API
description: createStorefront(options), the Emitter, mount(), and the full config reference.
---

## createStorefront(options)

Factory function that wires up the cart and the shared context object used by components. Returns
a `Promise` — it awaits `GET /shop.json` (locale, currency, cart/search settings for
headless-enabled shops) before resolving, so any config it doesn't already have from `options` can
fall back to what the shop reports. Never rejects: a shop that isn't headless-enabled, a network
error, etc. all just fall through to explicit options / built-in defaults.

```js
import { createStorefront } from 'bolder-storefront'

createStorefront({
  shop:        'acme',          // shop subdomain (required unless apiBase is set)
  apiBase:     'https://...',   // override API base URL (optional)
  locale:      'es-CL',         // locale hint (optional — falls back to /shop.json, then 'es-CL')
  currency:    'CLP',           // currency hint (optional — falls back to /shop.json)
  onBeforeAdd: function(proceed) { /* gate for add-to-cart */ proceed() },
  onError:     function(msg)    { /* custom error handler */ },
}).then(function(storefront) {
  // storefront.cart, storefront.mount(...), etc.
})
```

`config.shop`, `.shopName`, and `.quoteFlowEnabled` fall back to `/shop.json` the same way
`locale`/`currency` do — set explicitly only to override. `config.oauthProviders`,
`.timezoneOffset`, and `.cacheBuster` always come from `/shop.json` — not settable via options.

### Return value

Resolves to an object with:

| Property | Type | Description |
|----------|------|-------------|
| `cart` | `Cart` | Cart instance — see [Cart](/frontend/sdk/cart). |
| `auth` | `Auth` | Authentication client — see [Authentication](/frontend/sdk/auth). |
| `delivery` | `Delivery` | Delivery/shipping client — see [Delivery Setup](/frontend/sdk/auth#delivery-setup). |
| `products` | `Products` | Product lookup helpers — see [Catalog & Search](/frontend/sdk/catalog). |
| `search` | `Search` | Live search — see [Catalog & Search](/frontend/sdk/catalog#search). |
| `forms` | `Forms` | Contact forms client — see [Forms & Content](/frontend/sdk/forms). |
| `config` | `Object` | Resolved configuration object (explicit options merged with `/shop.json` defaults). |
| `shared` | `Object` | Context object threaded into component factories. |
| `mount(Factory, target, data?, opts?)` | Function | Mount a component factory onto a DOM element. |
| `components` | `Object` | On-demand component registry — see [Components](/frontend/sdk/components). |
| `authAjax` | Function | Credentialed ajax client (same one `auth` uses). Pass to `createConsole()` for Customer Console data. |
| `shopSettings` | `Object \| null` | Raw `/shop.json` response, or `null` if unavailable. |

### Config priority

Options are merged in this order (highest priority first):

1. **Explicit options**

    Passed directly to `createStorefront()`.

2. **window.__BOLDER_CONFIG__**

    A global config object.

3. **data-* attributes**

    On the `<script>` tag that loaded `storefront.umd.cjs`.

4. **GET /shop.json**

    Headless-enabled shops only — locale, currency.

5. **Built-in defaults**

    `locale: 'es-CL'`.

### mount(Factory, target, data?, opts?)

```js
storefront.mount(MyComponent, '#container', { someOption: true })
```

| Argument | Type | Description |
|----------|------|-------------|
| `Factory` | Function | A component factory |
| `target` | `string \| Element` | CSS selector or DOM element to mount into |
| `data` | `Object` | Initial data / settings passed to the component |
| `opts` | `Object` | Mount options (e.g. `{ shadow: false }` to skip Shadow DOM) |

Returns `{ update(data), unmount() }`.

## Emitter

A lightweight event emitter mixed into `Cart` and available as a standalone export for building custom event buses.

```js
import { Emitter } from 'bolder-storefront'

const bus = new Emitter()
bus.on('change', handler)
bus.trigger('change', payload)
bus.off('change', handler)
bus.once('change', handler)  // fires once then auto-removes

// Mix into an existing object
const obj = {}
Emitter(obj)
obj.on('ping', handler)
```

| Method | Description |
|--------|-------------|
| `on(events, fn)` | Register a listener. `events` may be space-separated. |
| `once(event, fn)` | Register a one-time listener. |
| `off(events?, fn?)` | Remove a specific listener, all listeners for an event, or all listeners with `'*'`. |
| `trigger(event, ...args)` | Fire all listeners for an event. |

## Config reference

All options accepted by `createStorefront()`:

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `shop` | `string` | — | Shop subdomain (e.g. `"acme"`). Used to build `apiBase` and as the default search feed's `shopSubdomain`. Required unless `apiBase` is set. |
| `apiBase` | `string` | `https://<shop>.boldershops.com` | Full base URL for API requests. Every request is made under `apiBase + '/api'`. |
| `searchUrl` | `string` | Bolder's hosted search service | Override the WebSocket URL `storefront.search` connects to. Rarely needed. |
| `locale` | `string` | `"es-CL"` | Locale hint for components. |
| `currency` | `string` | — | Currency code hint (e.g. `"CLP"`, `"USD"`). |
| `widgets` | `Object` | `{}` | Widget configuration forwarded to components via `shared`. |
| `strings` | `Object` | `{}` | Localisation strings forwarded to components via `shared`. |
| `helpers` | `Object` | `{}` | Helper functions forwarded to components via `shared`. |
| `onBeforeAdd` | `function(proceed)` | — | Gate function called before every `quickAdd`. Must call `proceed()` to continue. |
| `onError` | `function(message)` | — | Error handler for cart mutation failures. Defaults to `console.warn`. |