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

TwilightBundles

componentAdvancedbrowserlive demo

Watches the page for Twilight bundle elements and loads Salla's bundles runtime the first time one appears; mounted on every page.

import { TwilightBundles } from '@salla.sa/twilight-theme-engine/tracking';

In plain words

Twilight bundles are components a merchant installs from outside the theme. They need a script from Salla to work, but most pages have none, so loading it everywhere would waste time.

TwilightBundles watches the page, and only when a bundle element shows up does it add that script. It draws nothing, and the engine already renders it on every page.

Signature

function TwilightBundles(): null

Try it live

TwilightBundles is already running on this page. It watches for bundle elements and loads the bundles runtime only when one appears.Try this: inspect: the observer is installed, and with no bundle element on this page the runtime script was never added.
Storefront canvas · en · LTR
Runs in the browser…
What a theme writes
import { TwilightBundles } from '@salla.sa/twilight-theme-engine/tracking';

// TwilightProvider already renders it at body:end on every page.
// A second instance does nothing once the runtime script is on the page.
export function Bundles() {
  return <TwilightBundles />;
}

Example

app/components/Bundles.tsx
import { TwilightBundles } from '@salla.sa/twilight-theme-engine/tracking';

// TwilightProvider already renders this at body:end on every page.
export function Bundles() {
  return <TwilightBundles />;
}

How it behaves

  • In an effect it starts a MutationObserver on document.body (kept on window.twilightBundlesObserver). When a salla-custom-component element is added, or one is already there, it adds <script type="module" id="twilight-bundles-assets"> loading twilight-bundles.js (the latest build) from cdn.assets.salla.network, then disconnects the observer.

  • The default body:end handler renders it on every page (priority 100). BundleComponent is what puts such elements on the home page.

Gotchas

  • The observer looks only at the nodes that were added, not inside them. A bundle element that arrives inside a newly inserted wrapper (a section rendered in one go) is missed, and the runtime never loads. BundleComponent avoids this by rendering its element one render after mounting, into a wrapper already on the page; render your own bundle elements the same way.

  • If the script is already on the page when it mounts, it returns without installing an observer, so a second instance does nothing.

  • Its source comment says it uses an import map for Lit; it adds none.

Related

BundleComponent

Hosts a home block that comes from an installed Twilight bundle (a component built outside the theme), rendered in the browser only.

registerDefaultHooks

Registers the engine's built-in slot handlers (GTM, bundles, store closed, fast checkout, price quote, pre-order); importing the hooks module already runs it.

Source and docs