Core API

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.

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.
`auth`	`Auth`	Authentication client — see Authentication.
`delivery`	`Delivery`	Delivery/shipping client — see Delivery Setup.
`products`	`Products`	Product lookup helpers — see Catalog & Search.
`search`	`Search`	Live search — see Catalog & Search.
`forms`	`Forms`	Contact forms client — see Forms & Content.
`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.
`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):

Explicit options

Passed directly to createStorefront().

window.__BOLDER_CONFIG__

A global config object.

data-* attributes

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

GET /shop.json

Headless-enabled shops only — locale, currency.

Built-in defaults

locale: 'es-CL'.

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

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.

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