Skip to content
Twilight React Playground
ثيم رائدaren

home

objectBeginnerserverbrowserlive demo

Fetches the blocks the merchant arranged on the home page, in order, each with its own settings.

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

In plain words

A merchant builds the home page from blocks in the Salla dashboard: a slider, a row of offers, a banner. home.components() returns that list in page order. Each block names its kind in path and carries its settings right beside it.

The engine's home page loads this list and draws each block with the component registered for its path.

Signature

home.components(): Promise<HomeComponentData[]>   // GET component/list
home.queries.components()                         // key ['home', 'components']

interface HomeComponentData {
  path: string;                   // 'home.enhanced-slider', 'fixed-banner', …
  key?: string | number | null;
  view_style?: string | null;
  component?: JsonObject;
  [setting: string]: string | number | boolean | null | JsonObject | undefined;
}

Try it live

The blocks the merchant arranged on the home page, in order, exactly as the API sends them.Try this: open a few blocks: each one carries its own settings at the top level, next to path.
Storefront canvas · en · LTR

Loading the home page blocks…

Controls
What a theme writes
import { useQuery } from '@tanstack/react-query';
import { home } from '@salla.sa/twilight-theme-engine/api/home';

export function HomeOutline() {
  const { data = [] } = useQuery(home.queries.components());

  return (
    <ol>
      {data.map((block, index) => (
        // Some paths start with "home.": registered components use the name after it.
        <li key={index}>{block.path.replace('home.', '')}</li>
      ))}
    </ol>
  );
}

Example

app/home/blocks.ts
import { home } from '@salla.sa/twilight-theme-engine/api/home';
import { getTwilightContext } from '@salla.sa/twilight-theme-engine/tanstack';

/** Only the blocks this theme can draw, named the way components are registered. */
export async function loadHomeBlocks(known: Set<string>) {
  const { queryClient } = getTwilightContext();
  const blocks = await queryClient.ensureQueryData(home.queries.components());

  return blocks
    .map((block) => ({ ...block, path: block.path.replace('home.', '') }))
    .filter((block) => known.has(block.path));
}

How it behaves

  • Endpoint: GET component/list, public; returns data ?? [].

  • The engine home loader runs queryClient.ensureQueryData(home.queries.components()) and rewrites each path with path.replace('home.', '') before looking the component up in the registry.

  • Settings sit at the top level of each block (title, products, slides…), not under component. packages/theme-engine/docs/HOME_COMPONENTS.md lists the fields of each block.

Gotchas

  • Only some paths carry the home. prefix. On the demo store home.enhanced-slider and home.brands do, while fixed-banner, fixed-products, store-features and featured-products do not. Compare names after removing the prefix, as the engine does, and register components under the bare name.

Related

registerHomeComponents

Tells the engine which component draws each home page block, by the block path the Salla API sends. Call it once at startup.

HomeComponentRenderer

Draws one home page block from its API data: finds its registered component, wraps it in an error boundary, and defers it until visible.

Source and docs