Luma

Luma is the browser framework a distribution repository builds on. It renders Luigi’s Box AI results into your existing storefront, in your markup and your CSS, without changes to your site’s code beyond a script tag in <head>.

It provides four widgets:

Widget	What it does	Surface it calls
Autocomplete	A dropdown under your search input, as the shopper types	search
Search results	Your search results page: results, facets, sorting, “show more”	search
Category pages	Your category listings, with the same controls	collection
Recommenders	Product strips on any page, and a popup after “add to cart”	recommender

Each widget is optional. A site without recommenders never downloads their code.

Luma also sends the analytics events your integration describes — page views, clicks, cart additions and purchases — read from its own widgets or from your dataLayer.

How it reaches your site

Luma is the @luigisbox/luma npm package. Your integration repository depends on it, holds your site’s configuration and templates in integration/, and builds them into the script your storefront loads:

1. Your site includes the loader script once — see Installing on your site.
2. The loader imports the current build of your integration.
3. Luma reads the configuration, decides which widgets apply to the current page, and renders them.

A push to main publishes a new build; the tag on your site does not change. See Previews and releases.

What Luma does to your page

• It adds, it never removes. Luma inserts its own elements and hides the ones it replaces with CSS. Your nodes stay in the DOM.
• It falls back to your site. If a request fails, a listing has not rendered within 4 seconds, a URL is not one the configuration accepts, the page is not HTTPS, or the browser lacks a required feature, your own UI is shown as if Luma were not there.
• It leaves navigation to your site. Your router keeps the URL and history. Luma does not rewrite your history entries.
• It works with your frontend stack. Plain server-rendered pages, React and Next.js, Remix and React Router 7, Vue and Nuxt, Angular, SvelteKit, Astro, Turbo and htmx, with no code change on your side.
• Your CSS wins. Luma’s own styles sit in a cascade layer, so any rule of yours or of the integration overrides them.

Behaviour and fallbacks covers these in detail.

Versions

Luma is pre-release. Until 1.0, a minor version (0.2.0) can change the integration API — configuration keys, template scope, the build — and a patch version (0.1.1) only fixes. A dependency range of ^0.1.0 takes fixes without breaking changes.

Your repository moves to a new Luma version when its package.json and yarn.lock change. Nothing updates on its own.

Browser support

Luma targets Baseline Widely available: Chrome and Edge 107, Firefox 104 and Safari 16 and later, desktop and mobile. Newer browser features are used where present and skipped where not. See Behaviour and fallbacks.

Next

Installing on your site	The tags your <head> needs, in order
The integration folder	Where configuration, hooks, templates and translations go
Templates	Rendering results in your own markup
Analytics	The events your integration sends, and where it reads them
Tools and debugging	Developing against your live site, and checking the result

See also

• Your first integration — creating the repository Luma lives in
• Surfaces and widgets