---
title: Tools and debugging
description: Develop an integration against your live site, check its accessibility, parity and performance with yarn luma, and read what Luma did on a page.
slug: luma/tools
docKind: guide
hub: luigisbox-ai
---

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
yarn dev    # serves the integration on https://localhost:8069
```

```text
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](/luma/installing/) would:

```bash
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:

```js
// 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](/distribution/previews-and-releases/) — branch previews and releases
- [Behaviour and fallbacks](/luma/behaviour/)