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

What a theme is, and what the engine does for you

Beginner8 min

A theme is a small app you own; the engine supplies its pages, data loading and the connection to Salla.

When a shopper opens a Salla store, what they see is drawn by a theme. A React theme is a small web application: a folder of files that you own and publish.

You do not write most of a storefront yourself. The product page, the cart, the blog, loading the store's data, and talking to Salla already exist in the engine, an npm package named @salla.sa/twilight-theme-engine. Your theme plugs into it and changes what it needs to change.

Three parts, one page

Step through what happens between a shopper typing an address and a working page. Press Next step, or pick a number. The Advanced switch in the top bar changes the captions to the engine's own terms.

Your themefiles you owntwilightReact()vite.config.tsRoute filesapp/routes/*.tsxThe enginenpm packageBrowsera shopper opens /ar/cartServerrenders the HTMLSalla APIstore dataSalla SDKwindow.Salla

1. You own a small folder of files

A theme is a folder: a few setup files, your own components, your translations, and twilight.json, which lists the settings a merchant can change in the Salla dashboard.

In engine terms

The hand-written files are vite.config.ts (twilightReact()), app/start.ts (request middleware), app/router.tsx (createRouter() and registrations), app/routes/__root.tsx (createTwilightRootRoute() and TwilightProvider), app/routes.ts (your own routes), locales/*.json and twilight.json.

The files you own

These excerpts come from the reference theme (Raed) in this repository, shortened. Pick a file to see what it is for, and whether you ever touch it.

Set up once

Turns the folder into a theme. twilightReact() sets up the server runtime, the page routes and your translations.

vite.config.ts
import { defineConfig } from 'vite';
import { twilightReact } from '@salla.sa/twilight-theme-engine/vite';

export default defineConfig(async () => ({
  plugins: [...(await twilightReact({ localesDir: './locales' }))],
}));

What the engine does for you

  • Every storefront page: home, product, product lists, search, cart, blog, brands, loyalty and the customer account, each as a ready-made route module.
  • Data: it loads the store settings and translations once per request, and gives you typed functions for products, categories, menus and more.
  • Rendering: pages are rendered on the server, then made interactive in the browser, with the language in the address and right-to-left layout handled.
  • Building blocks: components such as ProductCard, the cart summary and the home-page blocks, and hooks such as useStore and useMoney.
  • The Salla SDK: it starts the SDK in the browser and keeps logins in step with the server.
  • Ways in: hook slots to add content, a registry to replace components, and your own routes to replace whole pages.
In engine terms
Check yourself

You want the cart page to look different. What do you do?