` re-reads `store` from the Salla SDK config and merges it, one level deep, over the current store. It does nothing when the SDK is not loaded yet, and ignores errors.
## Common tasks [#common-tasks]
### Is the store multilingual, and which languages? [#is-the-store-multilingual-and-which-languages]
`is_multilingual` is on the store. The list of languages is on `settings`, as an array.
```tsx
import { useTwilight } from '@salla.sa/twilight-theme-engine';
function Languages() {
const { store, settings, locale } = useTwilight();
if (!store.settings?.is_multilingual) return null;
return (
{settings.languages?.map((lang) => (
-
{lang.name} {lang.is_rtl ? '(RTL)' : ''}
))}
);
}
```
Demo values: `{ "name": "العربية", "code": "ar", "is_rtl": true, "country_code": "sa", "url": "https://assets.salla.sa/images/flags/ar.svg" }`. The `url` is the flag icon, not a page. The engine also adds `iso_code`, equal to `code`. See [Languages and RTL](https://docs.salla.dev/twilight/react/guide/languages-and-rtl).
### Which currencies are available? [#which-currencies-are-available]
`settings.currencies` is an object keyed by currency code. `amount` is the exchange rate against the store currency (in the demo, `USD.amount` is `0.267589` and `SAR.amount` is `1`). To format prices, use [`useMoney`](https://docs.salla.dev/twilight/react/hooks/use-money).
```tsx
const { store, settings } = useTwilight();
const codes = store.settings?.currencies_enabled ? Object.keys(settings.currencies ?? {}) : [];
// ["AED", "AUD", "BHD", …, "SAR", "USD"]
```
### Do customers sign in by email or mobile? [#do-customers-sign-in-by-email-or-mobile]
```tsx
const { auth } = useStore().settings;
const methods = [auth.email_allowed && 'email', auth.mobile_allowed && 'mobile'].filter(Boolean);
// demo store: ["email"]
```
When `force_login` is `true`, send visitors to sign in before they browse.
### Is the store open right now? [#is-the-store-open-right-now]
`opening_hours` is passed to `useOpeningHours`, which returns `isOpen`, `isEnabled`, `nextOpen` and `nextOpenFormatted`. It treats the store as open when opening hours are not enabled.
```tsx
import { useStore } from '@salla.sa/twilight-theme-engine/hooks/useStore';
import { useOpeningHours } from '@salla.sa/twilight-theme-engine/hooks';
function ClosedNotice() {
const { settings } = useStore();
const { isOpen, nextOpenFormatted } = useOpeningHours(settings.opening_hours);
return isOpen ? null : We are closed. We open {nextOpenFormatted}.
;
}
```
### Is the store in maintenance? [#is-the-store-in-maintenance]
When the merchant closes the store from the dashboard (or the platform closes it, or one market is closed), the settings response carries `maintenance: true` and `maintenance_details`: the merchant's `title` and `message` (plain text), and `button_*` fields that are `null` for customers.
You do not have to handle it. The engine decides per request who sees what, the way the Twig storefront does: a customer gets the maintenance page (`MaintenancePage` from `@salla.sa/twilight-theme-engine/store`) in place of your layout, with a `503` status, and nothing else renders, not even the Salla SDK. The merchant gets the store as usual, with the SDK's maintenance bar on top.
```tsx
const { settings } = useTwilight();
settings.maintenance; // true while the store is closed, for the merchant too
settings.maintenance_details?.title; // what the merchant wrote
```
#### A store that has not launched yet [#a-store-that-has-not-launched-yet]
Until the merchant finishes launching the store, the settings say `maintenance: true` too, but `maintenance_details` then holds the merchant's own "finish launching" notice, which the API sends to every visitor. The engine marks these settings `launched: false`, and `MaintenancePage` shows customers the platform's launching-soon page instead: the store's logo, "The store is launching soon" in the platform's words, and the store's contacts. It never shows them that notice.
```tsx
settings.launched; // false while the store has not launched yet; absent otherwise
```
#### How the engine tells the merchant from a customer [#how-the-engine-tells-the-merchant-from-a-customer]
The decision is made once per request, in the root route's `beforeLoad`, from the settings and the request alone:
1. The dashboard's "view store" button (and the partners portal) opens the store with `?utm_source=dashboard&identifier=` (`portal` for the portal). When `identifier` is this store's `store.id`, the request is the merchant's. The engine answers with the store and sets a session cookie, `salla_view_as=`, so the browser is remembered as the merchant until it closes, as the Twig storefront's PHP session was.
2. A request carrying that cookie for this store is the merchant's too. The cookie opens only the store it was set for.
3. A session the backend marks as a theme preview (`theme.mode === 'preview'`) always sees the store.
4. Anything served from the preview host (`preview.salla.design`) always sees the store, closed or not launched yet. The dashboard's theme editor frames your theme there, and a frame on another site carries neither the link from step 1 nor the cookie from step 2, so the host is what says it is a preview. It holds on every page of the preview, not only the first, as the Twig storefront's own preview hosts do. A merchant's domain, `salla.sa` and a dev server are not the preview host, so they are decided by the other steps. On the preview host the engine also initialises the Salla SDK with `maintenance: false`, so the SDK's merchant maintenance bar is not drawn over the page being edited. Only the SDK's copy changes: the settings you read with `useTwilight()` stay as the API sent them, `maintenance: true` included.
5. Everyone else gets the maintenance page and a `503`, so search engines keep the store indexed as temporarily unavailable.
#### While you develop [#while-you-develop]
Your dev server renders against a real store, so a closed store shows you the maintenance page too. In development the engine pins a bar to the top of it with a link, "View the store as the merchant": the dashboard's link from step 1, for this store. Click it once, and the rest of the browser session renders the store. A private window gives you the customer's page back, which is how you check your own `maintenancePage` below. The bar exists only on the dev server; production builds drop it.
#### Your own maintenance page [#your-own-maintenance-page]
To show your own page instead of the engine's, pass it to the provider beside `layout`. It takes no props and renders alone: no layout, no route, no SDK. It renders for a store that has not launched yet too, so check `settings.launched` before you show `maintenance_details`.
```tsx title="app/routes/__root.tsx"
import { TwilightProvider, useTwilight } from '@salla.sa/twilight-theme-engine';
function ClosedPage() {
const { store, settings } = useTwilight();
return (
{settings.launched === false ? (
Launching soon
) : (
<>
{settings.maintenance_details?.title}
{settings.maintenance_details?.message}
)}
);
}
;
```
### Which payment methods and features are on? [#which-payment-methods-and-features-are-on]
```tsx
const { settings, features = [] } = useStore();
const acceptsCash = settings.payments?.includes('cod');
const guestCheckout = features.includes('guest-checkout');
```
### Free shipping and cart settings [#free-shipping-and-cart-settings]
Free shipping progress is part of the cart, not the store. See [Cart data](https://docs.salla.dev/twilight/react/data/cart). Store-level cart switches are in `settings.cart`, for example `settings.cart.apply_coupon_enabled`.
## Gotchas [#gotchas]
* **Many fields are optional.** `slogan`, `about`, `favicon`, `api`, `scope`, `opening_hours`, `social.*` and `contacts.*` can be missing. Use optional chaining and test for presence before you render a link.
* **Types are looser than the data.** Several settings (`filters`, `buy_now`, `installments`) are unions of a boolean or string, an object and `null`, so narrow them before use. Some real fields are not typed at all.
* **`store.id` is a number**, but ids on other objects, such as `certificate.id`, are strings. Compare with the right type, or convert before you compare.
* **Some setting keys are not valid identifiers.** `settings.product['product-recommendation-type']` and `settings.features['pre-order-campaigns']` need bracket access.
* **Flags that are numbers.** `settings.product.total_sold_enabled` is `1` or `0`.
* **Language-dependent values.** The API response follows the page language, so `url` carries the language prefix (`/en/`). `name` and `description` are what the merchant typed and are not translated.
* **`description` is HTML.** Sanitise it or render it with care.
* **Empty store object.** If the provider is created without settings, `store` is `{}` until settings arrive, so `store.settings` is `undefined`. Use `store.settings?.…` in code that can run that early.
* **Server and browser see the same store.** It comes from the settings loaded for the request, so server and first browser render match. `refresh()` only exists in the browser, because it needs the Salla SDK.
* **`useStore()` returns a new object on every render.** Use `useTwilight().store`, which keeps its identity until `refresh()`, or depend on the fields you read, in effect and memo dependencies.
* **`settings` on `useTwilight()` is not `store.settings`.** `useTwilight().settings` is the whole settings response (store, theme, `languages`, `currencies`, and more). `store.settings` is only the store-level settings group.
## Next [#next]
* [`useStore`](https://docs.salla.dev/twilight/react/hooks/use-store) is the hook reference.
* [Theme data](https://docs.salla.dev/twilight/react/data/theme) describes the theme object next to the store.
* [Product data](https://docs.salla.dev/twilight/react/data/product) and [Cart data](https://docs.salla.dev/twilight/react/data/cart) describe the other objects your components read.