Previews and releases

Accepted branch pushes are built. Where that build ends up depends on which branch you pushed.

Push to	What happens
Any branch	Built, and loadable on your site at ?_lbx_env=<branch>
main	Built, tested, and — if the tests pass — published as what your site loads

Accepted files

Repositories accept integration source: JavaScript (.js, .mjs, .cjs), TypeScript (.ts, .tsx), JSX, Vue, CSS, SCSS, Sass, JSON, YAML, and Markdown. The root files .gitignore, .nvmrc, and yarn.lock are also accepted, along with .gitkeep files. Files must be UTF-8 text, at most 2 MiB each. Binary media, archives, unsupported file types, symbolic links, and submodules are rejected. JavaScript files must parse successfully without being executed.

Dependencies are not committed: the build installs what package.json declares, at the versions yarn.lock pins, from the npm registry. Luma is the @luigisbox/luma package. Commit yarn.lock whenever package.json changes, or the build fails.

Validation covers newly introduced commits as well as the branch or tag tip. Adding a forbidden file and removing it in a later commit of the same push still rejects the entire push. Remove it from the commits being pushed before retrying. Tags must refer to commits; custom refs and tags pointing to files or trees are not accepted.

A push may update at most 128 refs and introduce at most 256 commits. Validation is limited to 20,000 tree entries and 32 MiB of inspected object content. A push that exceeds a limit is rejected without updating any refs.

Published builds may contain only JavaScript (.js, .mjs) and CSS (.css). HTML pages, JSON, source maps, fonts, images, videos, and downloads are not published. Host media and fonts separately and reference their URLs from the integration. Publication rejects the complete build if any output fails these checks, including files generated during the build.

A build may contain at most 1,000 files, with a 2 MiB limit per file and a 20 MiB total limit. Output paths use ASCII letters, digits, underscores, hyphens and dots, with each segment starting with a letter, digit or underscore. Symbolic links, hard links, and special files are rejected.

These checks restrict file hosting; they do not assess the meaning of code, comments, strings, or encoded content. They apply to new pushes and publications and do not remove previously published files.

Previewing a branch

Append the branch name to any page on your site:

https://example.com/search?q=running+shoes&_lbx_env=search-widget

The choice persists for the rest of that tab’s session, so you can navigate the site normally after setting it once. A new tab loads production again.

Two reserved values:

Value	Effect
development	Load from your local yarn dev server — see Tools and debugging
stop	Turn the integration off entirely for this session

Use stop to establish whether a problem is yours or the integration’s: it removes the integration from the page without touching a deployment.

If a branch’s build cannot be loaded, the loader falls back to production and says so in the browser console rather than leaving the page with no integration at all.

Previews run on the real site, with real markup and real catalog data; there is no staging copy of your storefront to keep in sync.

Releasing

main is production. A push to it — normally a merge — is built, checked by an automated testing agent that exercises the integration against your live pages, and published if that passes. Nobody approves it in between; merging is the release decision.

The published script is served from the repository’s loader_script_url, which never changes. Your site embeds it once and every subsequent release replaces what it serves.

<script async src="https://cdn.eu1.luigisbox.ai/b/lbdr_8w3k2p/loader.js"></script>

src is the repository’s loader_script_url. Read it from the repository record rather than assembling it — see Repositories API. The publishable key and the channel are part of the integration’s configuration, not the tag. For the full <head> — the early-hold snippet and connection hints that keep your own listing from flashing — see Installing on your site.

A working habit

Work on a branch, not on main. A testing branch exists from the start for work in progress that is not ready for its own branch.

The sequence:

1. Branch from main.
2. Push, and look at the preview URL on the pages that matter — including the ones you did not touch.
3. Have whoever owns the storefront look at the same URL.
4. Merge.

Rolling back

A release is a commit on main, so a rollback is a git operation: revert the merge and push. That builds and republishes the previous state.

Revert rather than force-push, so the history records what was live and when.

See also

• Your first integration — getting to the first preview
• Repositories API — reading a repository’s URLs and state
• Distribution