Tools and debugging

All commands run in your integration repository. Node.js 24 and Yarn 4 are required.

Developing against your live site

When the site already includes the loader, serve the integration locally and append ?_lbx_env=development to any page of your site:

• Bash
• Text

yarn dev    # serves the integration on https://localhost:8069

https://example.com/c/running-shoes?_lbx_env=development

The loader imports your local build instead of the published one, and a red banner says so. An edit shows on reload. Chrome asks once for permission to reach localhost from your site; allow it. If the dev server is not running, the loader falls back to production and an amber banner says so.

Set LBX_DEV_ORIGINS (comma-separated) to limit which sites may load from your dev server.

When the site does not include the loader yet, open it with the integration injected the way the tags in Installing on your site would:

yarn luma chrome                  # builds, opens the home page in Chrome
yarn luma chrome /c/running-shoes # another page
yarn luma chrome --dev            # from yarn dev: an edit shows on reload

It needs your storefront’s host in luma.config.mjs (below). Any Luigi’s Box scripts already on the site are blocked; nothing else about the site changes. --check prints what Luma did and exits; --help lists the rest.

yarn build writes the build to dist/, as a release would.

Checking an integration

Command	Checks
yarn luma a11y	WCAG 2.2 AA conformance of the integration’s widgets, by keyboard too
yarn luma parity	How closely Luma’s search and category UI matches your site’s own, component by component
yarn luma footprint	What Luma costs each kind of page: script size and round trips, main-thread and compile time, API requests, time until ready
yarn luma tasks	Main-thread tasks over a frame’s budget (16 ms at 4× CPU slowdown) while loading pages, filtering, appending, going Back and typing, by source line
yarn luma baseline	Nothing in integration/ is newer than Baseline Widely available. --built dist checks the build.

yarn luma lists every tool. A Luma update can add tools; they are available without changes to your repository. yarn luma tooling --write sets up a repository that predates them.

luma.config.mjs

The tools’ settings for your site. Every export is optional:

// Your storefront's host. The tools open it; LBX_HOST overrides it.
export const host = 'www.example.com';
// Pages the tools' scenarios use: a category page, a search, a product page, the search input.
export const fixtures = { category: '/c/running-shoes', query: 'shoes', product: '/p/sku-1001', input: 'input[name="q"]' };
// Pages footprint and tasks measure, as { label: path }.
export const perf = { pages: { home: '/', category: '/c/running-shoes', search: '/search?q=shoes' } };

Without host, the tools run on a neutral stub page. stubPage exports a page in your own markup and stylesheet to use instead.

Reading what Luma did

In the browser console, window.__lbx is Luma’s state on the page:

__lbx.version	The Luma version — dev from the dev server
__lbx.config	The configuration in effect, after every _init.ts ran
__lbx.health.errors	Errors Luma caught. Luma never throws into your page, so they appear here.
__lbx.health.timeline	What happened, in order, with timings: a listing held, shown or released, renders, prefetches, restores
__lbx.health.apiCalls	Requests made on this page

On a category page that shows your own listing, look at the timeline: a render with 0 results followed by a release means the category filter matched no products — a configuration or catalog question, not a failure to render.

To rule Luma out of a problem on your site, append ?_lbx_env=stop: the integration is off for that tab’s session.

See also

• Previews and releases — branch previews and releases
• Behaviour and fallbacks