Shared types

Use this page when a field on the store, product or cart points to a smaller shape (an image, a category, a price object) and you need its fields.

All types import from @salla.sa/twilight-theme-engine/types, except where a section says otherwise:

import type { Money, Category, MenuItem } from '@salla.sa/twilight-theme-engine/types';

The examples marked "Public store API" are real answers from the public demo store.

MoneyCopy Anchor Link

Where it appears: product variants (skus[].price), base_currency_price on a product, and cart lines (price, total and more).

Example (public store API, a product's base_currency_price):

{ "currency": "SAR", "amount": 3 }

Many price fields are plain numbers instead: on a product, price, regular_price and sale_price are numbers (199), and currency is a separate field. Cart lines can be either. Turn both into a number first, then format it with useMoney:

import type { Money } from '@salla.sa/twilight-theme-engine/types';
import { useMoney } from '@salla.sa/twilight-theme-engine/hooks/useMoney';

function Price({ value }: { value: number | Money }) {
  const { format } = useMoney();
  const amount = typeof value === 'number' ? value : value.amount;
  return <>{format(amount, { currency: typeof value === 'number' ? undefined : value.currency })}</>;
}

ImagesCopy Anchor Link

Where it appears: Product.image and Product.images.

Example (public store API):

{ "url": "https://cdn.salla.sa/mQgZlG/c58e19d6-...-500x500.jpg", "alt": "Chair" }

images can be null when a product has a single image: read image first, and use images ?? []. Images on categories, brands, cart lines and menu items are plain URL strings, not this object.

CategoryCopy Anchor Link

Where it appears: category lists and pages (category API), and on a product as a smaller ProductCategory (name, url, optional id, icon, image).

Example (public store API, GET categories):

BrandCopy Anchor Link

Where it appears: the brands list, brand pages and the home brands block. The engine has two Brand types:

• Brand from @salla.sa/twilight-theme-engine/types: id: number, name, logo, url. This is the small card shape.
• Brand from @salla.sa/twilight-theme-engine/routes: the full record used by the brands pages and the brand API.

Example (public store API, GET brands, description shortened):

metadataCopy Anchor Link

MenuItemCopy Anchor Link

Where it appears: the header and footer menus (menu API), usually passed to your header and footer components.

Example (public store API, GET menus/header, one item with one child):

BreadcrumbCopy Anchor Link

Where it appears: useBreadcrumbs(page) returns a list of them for the trail above a page.

Example (illustrative values):

[
  { "name": "Home", "url": "/" },
  { "name": "Accessories", "url": "/accessories/c1309167683" }
]

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

const crumbs = useBreadcrumbs(page); // [] on the home page

If the page has no trail of its own, the hook returns Home plus the page title. On a product page it inserts the list the customer came from.

PageCopy Anchor Link

Where it appears: every route loader returns a page object, which components pass to useBreadcrumbs and use for the title.

Example (illustrative values):

{ "slug": "product.single", "title": "Chair", "id": 677709975, "url": "/chair/p677709975" }

parentCopy Anchor Link

breadcrumbsCopy Anchor Link

A merchant's custom page is a Page plus content (HTML), metadata and created_at, called StaticPage. The page API returns the raw record, for example from the public store: { "id": 153787377, "name": "Our team", "content": "<p>...</p>", "type": "general" }.

LanguageCopy Anchor Link

Where it appears: useTwilight().settings.languages, the list behind a language switcher.

Example (public store API, languages.EN, plus the iso_code the engine adds):

For the current language, use useTranslation() (locale, direction).

PaginationCopy Anchor Link

Where it appears: lists such as product.list return PaginatedResult<T> from @salla.sa/twilight-theme-engine/api/types.

interface PaginatedResult<T> {
  items: T[];
  next: string | null; // null on the last page
}

Example (illustrative values):

{ "items": [ /* Product, Product, ... */ ], "next": "<opaque cursor>" }

The raw API also sends a cursor object (the Pagination type). Product list results keep it as cursor next to items; cursor.current is the page number for display only.

const first = await product.list({ source: 'latest' });
const second = first.next ? await product.list({ source: 'latest', cursor: first.next }) : null;

Testimonial and SliderCopy Anchor Link

The types exist for theme code that renders store testimonials and home sliders. The engine declares them but does not load them from a named API module, so fill them from the data your own loader or the home block gives you.

TestimonialCopy Anchor Link

SliderCopy Anchor Link

NextCopy Anchor Link

• Store data, Theme data and Product data
• User data and Cart data
• Data overview