# Docs

- Guide: From first run to a finished theme

  - **Start**
  - [Overview](/twilight/react/start/what-is-a-theme): What a Salla React theme is, and what the engine does for you versus what you own.
  - [Frameworks](/twilight/react/start/frameworks): Which React frameworks a Twilight theme can run on, and which parts of your theme depend on the choice.
  - [Quick start](/twilight/react/start/quick-start): Create a theme, run it locally and change one thing.
  - [Project structure](/twilight/react/start/project-structure): The few files a theme owns and what each one does.
  - [How it works](/twilight/react/start/how-it-works): What happens between a customer typing an address and a rendered page.
  - [Build with AI](/twilight/react/start/build-with-ai): Give your coding assistant the Salla Partners agent kit and MCP, which also serve these docs, so it can find, inspect and create a theme for you.

  - **Pages and data**
  - [Routes and pages](/twilight/react/guide/routes-and-pages): How a page exists in your theme, and how to add one or take over a built-in one.
  - [Loading data](/twilight/react/guide/loading-data): Fetch store data in a route loader, and reuse it in components with TanStack Query.

  - **Look and structure**
  - [Layout and components](/twilight/react/guide/layout-and-components): The page frame around every route, and how to swap an engine component for your own.
  - [Hooks and slots](/twilight/react/guide/hooks-and-slots): Read store data with engine hooks, and inject your own content into the page with hook slots.
  - [Styling](/twilight/react/guide/styling): Tailwind and SCSS in a theme, the colour and font tokens the engine sets, and dark mode.

  - **Language and settings**
  - [Languages and RTL](/twilight/react/guide/languages-and-rtl): Translate your theme with useTranslation, locale files, and direction-safe layout.
  - [Settings](/twilight/react/guide/settings): Declare merchant settings in twilight.json and read them in your components.
  - [SEO and head](/twilight/react/guide/seo-and-head): Set page titles and meta tags, extend the engine's defaults, and redirect old URLs.

  - **Browser**
  - [Salla SDK and events](/twilight/react/guide/salla-sdk-and-events): Change cart and wishlist data in the browser with the Salla SDK, and react to its events safely.
- Engine: Layouts, slots, data, hooks and components
  - [Overview](/twilight/react/engine): The hooks and components the theme engine ships, and how they fit together in your theme.

  - **Layouts**
  - [Layouts overview](/twilight/react/layouts): The page frames the engine ships, which ones you can replace, and how.
  - [MasterLayout](/twilight/react/layouts/master-layout): The default page frame: header, main content, footer and the global login, offer and scope modals.
  - [CustomerLayout](/twilight/react/layouts/customer-layout): The frame around every account page, with a breadcrumb, a sidebar menu and the page title.
  - [Header and footer](/twilight/react/layouts/header-and-footer): The Header, Footer, PageAdvertisements, Copyright and WidgetHead pieces of the master layout, and the slots you can fill.

  - **Slots**
  - [Slots overview](/twilight/react/slots): Every named slot the engine renders, where it sits on each page, and how to fill it from theme code or an installed app.
  - [Page frame slots](/twilight/react/slots/page-frame): Slots that wrap every page - the head, body, header and footer.
  - [Home and catalog slots](/twilight/react/slots/home-and-catalog): Where the home page, product list, brands page and not-found page expose slots, and what each one receives.
  - [Product page slots](/twilight/react/slots/product-page): Where the product page exposes slots around the details, add-to-cart form and related products, and what each one receives.
  - [Cart and checkout slots](/twilight/react/slots/cart-and-checkout): Where the cart page, its order summary and the thank-you page expose slots, and what each one receives.
  - [Account slots](/twilight/react/slots/account): Every slot on the customer account pages, where it renders, and what context it passes.
  - [Blog slots](/twilight/react/slots/blog): Every slot on the blog index, article, category, tag and author pages, with where it renders and what it passes.

  - **Data**
  - [Data overview](/twilight/react/data): Which hook or loader gives you the store, theme, product, user and cart objects, and the rules for reading them safely.
  - [Store data](/twilight/react/data/store): Every field of the store object returned by useStore and useTwilight().store, with real example values from a demo store.
  - [Theme data](/twilight/react/data/theme): Every field of the theme object that useTheme and useTwilight().theme return, with real values from a live store.
  - [Product data](/twilight/react/data/product): Every field of the Product object that useProduct, ProductCard and the product page hand you, with real example values.
  - [User data](/twilight/react/data/user): The signed-in customer's profile from useUser(), its fields, and what you get for a guest.
  - [Cart data](/twilight/react/data/cart): The cart object with its items, options, totals, coupon and free-shipping bar, and how to read and change it.
  - [Shared types](/twilight/react/data/shared-types): The small objects that the other data pages reuse, such as Money, Category, Brand, MenuItem, Language and paginated results.

  - **Hooks**
  - [HookSlot](/twilight/react/hooks/hook-slot): Mark a place in a layout or page where handlers, installed apps and your own code can add content.
  - [useAsyncFn](/twilight/react/hooks/use-async-fn): Wrap an async function to get loading, error and result state, ignoring results of outdated calls.
  - [useHook](/twilight/react/hooks/use-hook): Register a component-scoped handler that renders content inside a named HookSlot.
  - [useMoney](/twilight/react/hooks/use-money): Format prices with the store's currency symbol, number style and price settings.
  - [useProduct](/twilight/react/hooks/use-product): Keep a product object live: it updates its price and stock when the customer picks options, and can be reloaded.
  - [useStore](/twilight/react/hooks/use-store): Read the current store's name, logo, settings and other data, and re-read it from the Salla SDK on demand.
  - [useTheme](/twilight/react/hooks/use-theme): Read the theme's colours, font, settings and text direction.
  - [useTranslation](/twilight/react/hooks/use-translation): Translate text with a fallback and read the current language and direction.
  - [useWishlist](/twilight/react/hooks/use-wishlist): Read and change the customer's wishlist, shared across every component on the page.
  - [useUser](/twilight/react/hooks/use-user): Read the signed-in customer's profile and tell guests from signed-in customers.
  - [useCoupon](/twilight/react/hooks/use-coupon): Apply or remove a cart coupon through the Salla SDK, with loading and error state.
  - [useBreadcrumbs](/twilight/react/hooks/use-breadcrumbs): Get the breadcrumb trail for the current page, with a fallback when the page has none.
  - [useOpeningHours](/twilight/react/hooks/use-opening-hours): Tell whether the store is open right now and when it opens next, from the store's opening-hours setting.
  - [useGtm](/twilight/react/hooks/use-gtm): Push Google Tag Manager ecommerce events (product views, add to cart, purchase) to the data layer.
  - [Navigation and page detection](/twilight/react/hooks/navigation): Navigate from code, read the current location and route id, and stop a loader with redirect, notFound or unauthorized.
  - [useDocumentClass](/twilight/react/hooks/use-document-class): Set classes and attributes on the html and body elements for a page, and clean them up when the page changes.

  - **Components**
  - [Drawer](/twilight/react/components/drawer): A side panel that opens on the start edge of the screen, for menus and filters.
  - [Image](/twilight/react/components/image): An image that lazy-loads, resizes through the CDN and reserves space to avoid layout shift.
  - [Link](/twilight/react/components/link): A router-aware link that moves between theme pages without a full page reload.
  - [Modal](/twilight/react/components/modal): A dialog with a backdrop, Escape to close, focus return and body scroll lock.
  - [ProductCard](/twilight/react/components/product-card): The product tile used in grids and sliders, with price, badges, wishlist and add-to-cart.
  - [toast](/twilight/react/components/toast): Show short messages to the customer, such as success, error and loading notices.
  - [Skeletons](/twilight/react/components/skeleton): Placeholder screens shown while a page's data loads, and how to choose or replace them.

  - **Web components**
  - [Web components overview](/twilight/react/web-components): Every salla-* web component the storefront can use, with its properties, events, methods and slots.

  - **Interface**

  - **Products**

  - **Cart and offers**

  - **Orders**

  - **Reviews**

  - **Account and loyalty**

  - **Form fields**

  - **Store and platform**
- Routes: The built-in storefront pages
  - [Overview](/twilight/react/routes): Every built-in storefront page, its URL, its route file and where to read about it.
  - [Add a custom route](/twilight/react/routes/add-a-custom-route): Serve a new URL from your theme, with data, a title, a loading state and a locale-aware path.

  - **Storefront**
  - [Home](/twilight/react/routes/home): The storefront landing page, built from the blocks the merchant arranges in the dashboard.
  - [Cart](/twilight/react/routes/cart): The shopping cart page with line items, offers, coupon and the order summary.
  - [Search](/twilight/react/routes/search): Product search results for the keyword in the `q` query parameter.
  - [Products](/twilight/react/routes/products): The latest products, best sellers, offers or the customer's order-again list, picked by `?source=`.

  - **Catalog**
  - [Product page](/twilight/react/routes/product): The single product page, with its URL, params, route file and the edge cases around unknown products.
  - [Category page](/twilight/react/routes/category): The product listing for one category, with sorting, filters and infinite scroll.
  - [Brand products page](/twilight/react/routes/brand-products): The SEO short URL for a brand, which redirects to the brand page.
  - [Tag page](/twilight/react/routes/tag): Products that carry one tag, reachable from both the slug URL and the short /tags URL.
  - [Custom page](/twilight/react/routes/custom-page): A static content page the merchant creates in the dashboard, such as About us or Terms.
  - [Brands page](/twilight/react/routes/brands): The index of every brand in the store, grouped by first letter.
  - [Brand page](/twilight/react/routes/brand): The product listing for one brand, with the brand banner and logo.

  - **Blog**
  - [Blog](/twilight/react/routes/blog): The blog home page, with a slider of featured articles, a category sidebar and the latest articles.
  - [Blog article](/twilight/react/routes/blog-article): A single blog article with its author, tags, likes, comments and related articles.
  - [Blog category](/twilight/react/routes/blog-category): The articles of one blog category, with a sidebar of all categories and load-more on scroll.
  - [Blog tag](/twilight/react/routes/blog-tag): The articles carrying one blog tag, with a sidebar of categories and load-more on scroll.
  - [Blog author](/twilight/react/routes/blog-author): The articles written by one author, with a sidebar of categories and load-more on scroll.

  - **Account**
  - [Account](/twilight/react/routes/account): The shared /account layout that frames every signed-in page, and how a child page shapes it.
  - [Account profile](/twilight/react/routes/account-profile): The signed-in customer's profile page with the profile form, verification and notification settings.
  - [Account wishlist](/twilight/react/routes/account-wishlist): The signed-in customer's saved products, with paging and sharing.
  - [Account wallet](/twilight/react/routes/account-wallet): The signed-in customer's wallet balance and transaction history.
  - [Account notifications](/twilight/react/routes/account-notifications): The signed-in customer's list of store notifications.
  - [Account settings](/twilight/react/routes/account-settings): The signed-in customer's settings page, with the Salla user settings widget.
  - [Account orders](/twilight/react/routes/account-orders): The signed-in customer's order history, filterable by status.
  - [Account order](/twilight/react/routes/account-order): One order of the signed-in customer, with items, totals, shipping and payment details.
  - [Pending orders](/twilight/react/routes/pending-orders): Two redirect routes that send the customer to the orders list filtered to orders waiting for payment.
  - [Logout](/twilight/react/routes/logout): The page the Salla SDK sends the browser to after sign-out; it clears the token cookie and goes home.

  - **More**
  - [Loyalty](/twilight/react/routes/loyalty): The loyalty programme page that explains how customers earn and spend points.
  - [Testimonials](/twilight/react/routes/testimonials): The page that lists customer reviews of the store with a sort control.
  - [Product reviews](/twilight/react/routes/reviews): The page that lists shoppers' reviews of the store's products, which store menus link to.
  - [Thank you](/twilight/react/routes/thank-you): The order confirmation page shown after a successful checkout.
  - [SEO redirects](/twilight/react/routes/seo-redirects): How the engine keeps deprecated and old URLs working, so customers and search rankings are not lost.
  - [Not-found page](/twilight/react/routes/not-found): The page shown when no route matches or a loader says the thing does not exist.
- APIs: The shared HTTP client and every API module
  - [Overview](/twilight/react/api): What the shared API client is, why every request should go through it, and how to make a request in a loader, a component or directly.
  - [Client reference](/twilight/react/api/client): The clients the engine exports, with the headers `api` sets on each request and its timeout and retry numbers.
  - [Authentication and scope](/twilight/react/api/authentication-and-scope): How each request learns who the customer is and which store, branch and theme version it is for, and what that means for your query keys.
  - [Errors, timeouts and retries](/twilight/react/api/errors-timeouts-and-retries): What a failed request looks like, what the client retries on its own, and how to handle failures in loaders and components.
  - [Write your own endpoint](/twilight/react/api/write-your-own-endpoint): Build a theme-side API module on top of the shared client, with a typed function and a query whose cache key is correct.

  - **Catalog**
  - [product](/twilight/react/api/modules/product): Fetch one product with its details, or a cursor-paged list of products from any source (latest, offers, category, search and more).
  - [category](/twilight/react/api/modules/category): Fetch one product category or the whole category tree of the store.
  - [brand](/twilight/react/api/modules/brands): Fetch a page of the brands directory, or a single brand.
  - [home](/twilight/react/api/modules/home): Fetch the list of home page components that the store merchant arranged.
  - [page](/twilight/react/api/modules/page): Fetch one custom store page (such as "About us") by its slug.
  - [menu](/twilight/react/api/modules/menu): Fetch the store's header and footer navigation menus in the current language.
  - [blog](/twilight/react/api/modules/blog): Fetch the blog overview, filtered article lists and single articles.

  - **Shopping**
  - [cart](/twilight/react/api/modules/cart): Read one shopping cart by id, with its loyalty and gift information folded in.
  - [wishlist](/twilight/react/api/modules/wishlist): List the products the customer saved to their wishlist, using page numbers rather than cursors.
  - [order](/twilight/react/api/modules/order): List the customer's orders, read one order with its shipments and ratings, and load the checkout thank-you data.

  - **Customer**
  - [user](/twilight/react/api/modules/user): Read the signed-in customer's profile, or get null for a guest.
  - [profile](/twilight/react/api/modules/profile): Deletes the customer's account and saves a single account preference.
  - [wallet](/twilight/react/api/modules/wallet): Read the customer's wallet balance and a page of their wallet transactions.
  - [loyalty](/twilight/react/api/modules/loyalty): Reads the store's loyalty program and the signed-in customer's points balance.
  - [notification](/twilight/react/api/modules/notification): Lists the customer's account notifications and marks them as read.

  - **Store**
  - [store](/twilight/react/api/modules/store): Loads the store's settings (store info, theme, languages, currencies, payments and more) in one request.
  - [translations](/twilight/react/api/modules/translations): Fetches the platform's translation messages for one language from the CDN, and the merchant's own wording for it.
  - [advertisement](/twilight/react/api/modules/advertisement): Reads the merchant's announcement bars and picks the ones a page shows.
  - [apps](/twilight/react/api/modules/apps): Reads the snippets (scripts and HTML) and per-app settings of the apps installed on the store.
- Local development: Create, run and link a theme with the Salla CLI
  - [Overview](/twilight/react/local-development): Go from nothing installed to a theme running against your own store and published.
  - [Prerequisites](/twilight/react/local-development/prerequisites): The tools a theme needs and how to check them with salla theme doctor.
  - [Create a theme](/twilight/react/local-development/create-a-theme): What salla theme create asks, writes and runs, and how to skip the questions.
  - [Run it locally](/twilight/react/local-development/run-locally): Start the dev server with salla theme dev, and what the options and the first render do.

  - **Connect to Salla**
  - [Link a store](/twilight/react/local-development/link-a-store): Choose which Salla store your local theme renders, with --store, .env or a URL.
  - [Theme editor](/twilight/react/local-development/theme-editor): Open the merchant theme editor around your local dev server with salla theme dev --editor.
  - [Publish](/twilight/react/local-development/publish): Push your theme to its repository and submit it for review with salla theme publish.

  - **Reference**
  - [CLI commands](/twilight/react/local-development/cli-commands): Every salla theme command for a React theme, with its options.
  - [twilightReact](/twilight/react/local-development/vite-plugin): The Vite plugin that sets up routes, rendering, translations and the local server for a Twilight theme.
  - [Troubleshooting](/twilight/react/local-development/troubleshooting): Symptoms, causes and fixes for common problems when running a theme locally.
- Recipes: Task-first how-tos
  - [Overview](/twilight/react/recipes): Short, copy-ready answers to "how do I do X in my theme".
  - [Add content to a slot](/twilight/react/recipes/add-content-to-a-slot): Inject your own UI at a named point in the engine's pages without forking them.
  - [Replace the product card](/twilight/react/recipes/replace-the-product-card): Use your own product card in every list, slider and grid the engine renders.
  - [Fork a built-in route](/twilight/react/recipes/fork-a-built-in-route): Keep the engine's loader, head and skeleton for a page, but render your own component.
  - [Add a home block](/twilight/react/recipes/add-a-home-block): Create a section merchants can add to the home page and render it from your theme.
  - [Add a page](/twilight/react/recipes/add-a-page): Serve a brand-new URL, such as /faq, from your theme.
  - [Add translation keys](/twilight/react/recipes/add-translation-keys): Add Arabic and English strings to your theme and use them in components.
  - [React to cart events](/twilight/react/recipes/react-to-cart-events): Run code when the cart changes by subscribing to Salla SDK events.
  - [Track page views](/twilight/react/recipes/track-page-views): Send a page view on every navigation, including client-side ones.