useTwilight

In plain words

Signature

function useTwilight(): TwilightContextValue   // throws outside TwilightProvider

interface TwilightContextValue {
  isReady: boolean;
  store: Store;
  theme: Theme;
  settings: StoreContext;          // the whole store settings response
  locale: string;                  // 'ar'
  dir: 'ltr' | 'rtl';
  routeId: string;
  location: TwilightLocation;
  authToken: string | null;
  salla: SallaSDK | undefined;     // undefined in the server render
  i18n: i18n;                      // the i18next instance
  config: TwilightConfig;          // { debug }
  log: TwilightLog;                // styled console helpers
  currency: SallaCurrency | null;  // always null today
  extras?: Record<string, unknown>;
}

Try it live

import { useTwilight } from '@salla.sa/twilight-theme-engine';

export function Example() {
  const { store } = useTwilight();
  return <span>{store.name}</span>;
}

Example

import { useTwilight } from '@salla.sa/twilight-theme-engine';

export function StoreHeading() {
  const { store, theme, locale, dir } = useTwilight();
  return (
    <h1 lang={locale} dir={dir} style={{ color: theme.color.primary }}>
      {store.name}
    </h1>
  );
}

How it behaves

• store, theme, isReady and authToken are React state: when they change, every component using the hook renders again. settings, locale, dir, routeId, location, i18n and extras are getters that read the request context when you access them, so they are current when read but never cause a render themselves. useRouteId() and the useIs* hooks subscribe for you.

• store and theme hold the values the page was first rendered with. useStore().refresh() updates store; in development the dev settings widget overlays theme.settings.

• salla reads window.Salla on each access: undefined in the server render and until the SDK script has run.

• log prints styled console output (info, warn, error, label, dir, trace, group, groupCollapsed, groupEnd) whatever debug is set to.

• Hook slot handlers receive this same value as context.twilight. The hook is also exported from /providers.

Gotchas

• authToken is null in every server render, even for a signed-in customer: the provider seeds that state from the context or localStorage only in the browser (src/providers/TwilightProvider.tsx). Markup that depends on it differs between server and browser, a hydration mismatch. Decide after hydration, for example with useIsClient() from @salla.sa/twilight-theme-engine/hooks.

• currency is always null: it is created with useState(null) and never set (src/providers/twilight-init.ts). Format prices with useMoney().

• Reading settings throws SettingsError when the request context holds no settings (the getter in src/twilight/context.ts). Inside a rendered page they are always present.

Related

Source and docs

• Engine source: packages/theme-engine/src/providers/twilight-context.ts