registerHomeComponents, DefaultHomeComponents, registerHomeComponentConfig

In plain words

Signature

function registerHomeComponents(
  components?: Record<string, AnyHomeComponent | null>,   // default: DefaultHomeComponents
  prefix?: string                                         // default: 'home:'
): void;

const DefaultHomeComponents: Record<string, AnyHomeComponent | null>;
// fixed-banner, photos-slider, testimonial, store-features, youtube, square-photos,
// fixed-products, products-slider, parallax-background,
// featured-products:style1, featured-products:style2, featured-products:style3, bundle-component

function registerHomeComponentConfig(config: Record<string, HomeComponentConfig>): void;

type HomeComponentConfig = {
  height?: string;                                         // reserved before the block mounts
  className?: string | ((data: HomeComponentData) => string);
  id?: string | ((data: HomeComponentData) => string);
  placeholder?: React.ReactNode;
};

type AnyHomeComponent = React.ComponentType<{ data: any; priority?: boolean }>;
type HomeComponentsProps = { data: HomeComponentData & { position?: number; [key: string]: unknown } };

Example

import { createRouter } from '@salla.sa/twilight-theme-engine/tanstack';
import {
  DefaultHomeComponents,
  registerHomeComponents,
  registerHomeComponentConfig,
} from '@salla.sa/twilight-theme-engine/routes/home';
import { EnhancedSlider } from './components/home';
import { routeTree } from './routeTree.gen';

registerHomeComponents({
  ...DefaultHomeComponents,
  'enhanced-slider': EnhancedSlider,
});

registerHomeComponentConfig({
  'enhanced-slider': { height: '520px', className: 's-block s-block--enhanced-slider' },
});

export function getRouter() {
  return createRouter(routeTree);
}

How it behaves

• Same declarations as /components/home: importing from either path registers into the one engine registry.

• Each entry is registered as home:<path>. The renderer tries home:<path>:<view_style> first, then home:<path>, which is why the featured-products defaults are keyed featured-products:style1 to style3.

• registerHomeComponentConfig merges by path: a later call replaces a path's whole entry. For a path it covers, a theme's entry replaces the engine's built-in one; without either, the block reserves 400px and its wrapper class is s-block s-block--<path>.

• A null value is skipped, not unregistered: { ...DefaultHomeComponents, youtube: null } leaves youtube out of that call, but a component registered for it earlier stays.

Gotchas

• Not called for you: without registerHomeComponents, the Home page draws no blocks.

• Call both at module scope in app/router.tsx, not inside a component, so the server and the browser have the registrations before the first render.

• AnyHomeComponent declares a priority prop, but HomeComponentRenderer never sets it: it passes priority inside data (data.priority, true for the first three blocks). Read data.priority in your block to load its first image eagerly (packages/theme-engine/src/components/home/HomePageRenderer.tsx).

Related

Source and docs

• Engine source: packages/theme-engine/src/components/home/register.ts
• packages/theme-engine/docs/HOME_COMPONENTS.md — Registering Custom Components