@salla.sa / twilight-theme-engine

Salla React主题背后的SDK它提供了店面路由、组件、钩子和API 客户端，以及主题组成的Vite插件-所以主题是一个小应用程序，而不是一个分支 店面。

建造的 TanStack开始，在边缘进行服务器渲染。

安装

你通常不会自己安装这个 salla theme create --type react 搭建一个主题 这已经取决于它了。

pnpm add @salla.sa/twilight-theme-engine

对等依赖被固定到 波浪字符范围 （~1.166.2 用于 @tanstack/*， vite ^8.1.5， react ^19.2.4）. 发动机的 dist 参考文献 @tanstack/react-start 内部，如此漂泊 在运行时被测试的次要程序之外破坏SSR。让安装程序警告你，而不是强迫你 决议。

里面有什么？

文档

面向主题的指南驻留在 暮光之城网站 -从 开始跟踪 或者是 体系结构概述.

引擎内部深度潜水开始 docs/ 在这里:

子系统指出: src/api/README.md， src/vite/README.md， tests/README.md.

使用

将引擎连接到主题中

两个文件可以做到这一点。 app/start.ts 安装请求中间件：

import { createStart } from '@tanstack/react-start';
import { twilightMiddleware, earlyHintsMiddleware } from '@salla.sa/twilight-theme-engine/tanstack';

export const startInstance = createStart(() => {
  return {
    requestMiddleware: [twilightMiddleware(), earlyHintsMiddleware()],
  };
});

app/routes/__root.tsx 构建根路由并呈现提供程序：

import { TwilightProvider } from '@salla.sa/twilight-theme-engine';
import { createTwilightRootRoute } from '@salla.sa/twilight-theme-engine/tanstack';
import themeTranslations from 'virtual:twilight/theme-translations';

export const Route = createTwilightRootRoute()({ shellComponent: RootComponent });

<TwilightProvider> 接受捆绑 translations (加上可选的 debug， skeleton， onReady， onError）. 存储、区域设置和用户是 不 道具——中间件解决它们 每个请求。

组件注册表

import { registry, Component } from '@salla.sa/twilight-theme-engine';

registry.register('product:card', ProductCard);
registry.override('product:card', MyProductCard);

<Component name="product:card" product={product} />;

键是 结肠-分隔，引擎只能解析其中的三个： product:card, home:* 块(通过 registerHomeComponents()), account:layout-pending。覆盖任何 其他名称是静默的no-op -其他所有内容都直接导入。

钩槽

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

defineHooks({
  'body:start': () => <AnnouncementBar />,
  'product:form.end': ({ product }) => <TrustBadges product={product} />,
});

<HookSlot name="product:form.end" context={{ product }} />;

存储、主题和用户

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

function MyComponent() {
  const store = useStore();
  const { color, font, settings, isRTL } = useTheme();
  const { user } = useTwilight();

  const isDark = settings?.footer_is_dark ?? false;
}

设置是一个普通对象——用 ?. 和你自己的默认值。没有 settings.get().

翻译

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

function MyComponent() {
  const { t, locale, isRTL } = useTranslation();

  return (
    <>
      <h1>{t('pages.cart.title')}</h1>
      <p>{t('pages.products.sold_times', { count: 5 })}</p>
    </>
  );
}

useTranslation() 返回 react-i18next的 t， i18n, ready，加上区域信息 （locale， direction， isRTL， isLTR， languageName）. 这个 /i18n 子路径也导出 I18nProvider， FALLBACK_LOCALE， SUPPORTED_LOCALES， RTL_LOCALES， isLocale, getLanguageInfo.

金钱及资产

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

function ProductPrice({ product }) {
  const { format } = useMoney(); // also: parse, isValid
  const { cdn } = useAsset(); // also: asset, isPlaceholder

  return (
    <div>
      <img src={cdn(product.image.url, 400)} alt="" loading="lazy" />
      <p>{format(product.price)}</p>
    </div>
  );
}

format() 返回一个 ReactNode （不是字符串）——它将货币符号呈现为标记。

导入路径

引擎有~90个子路径导出。从最窄的包中导入，这样包就会很小：

// Core — provider, registry, context
import {
  TwilightProvider,
  useTwilight,
  registry,
  Component,
} from '@salla.sa/twilight-theme-engine';

// Hooks — one subpath each
import { useStore } from '@salla.sa/twilight-theme-engine/hooks/useStore';
import { useMoney } from '@salla.sa/twilight-theme-engine/hooks/useMoney';

// i18n
import { useTranslation, I18nProvider } from '@salla.sa/twilight-theme-engine/i18n';

// Components — grouped by domain
import { Link } from '@salla.sa/twilight-theme-engine/common';
import { Header, Footer } from '@salla.sa/twilight-theme-engine/layout';
import { CartItem, CartSummary } from '@salla.sa/twilight-theme-engine/cart';
import { ProductCard } from '@salla.sa/twilight-theme-engine/product';

// Routes
import { Home, DefaultHomeComponents } from '@salla.sa/twilight-theme-engine/routes/home';

// API clients — for loaders
import { store } from '@salla.sa/twilight-theme-engine/api/store';

// TanStack integration
import { createRouter, createTwilightRootRoute } from '@salla.sa/twilight-theme-engine/tanstack';

// Types
import type { Store, Theme, Product } from '@salla.sa/twilight-theme-engine/types';

权威列表是 exports 领域的 package.json。从来没有深刻含义 成 dist/ -这些路径不是公共API的一部分。

开发

从repo根目录：

pnpm --filter @salla.sa/twilight-theme-engine build          # tsup + tsc + dts stubs
pnpm --filter @salla.sa/twilight-theme-engine test
pnpm --filter @salla.sa/twilight-theme-engine test:coverage
pnpm --filter @salla.sa/twilight-theme-engine typecheck

主题消耗 dist/,所以 在运行或类型检查主题之前构建引擎。

添加新的公共导出意味着添加子路径 exports ——否则消费者就不能 达到它。通过安装独立的Tania来验证更改的发布是否有效 （为什么）。

测试惯例，包括ssr -vs-浏览器的划分 tests/README.md.

许可证

麻省理工学院