---
title: Local Simulation
published: true
index: 0
---

# Local storefront previews

Use `local-storefront` with disposable fictional data only for an explicitly requested simulation, sample-data or offline preview. Ordinary local previews use Shopify development; missing Shopify access does not select simulation.

## Choose the target and execution host

Identify the authorized theme source, revision and changes. A live URL cannot reconstruct a theme. Request missing source; use a public reference theme only when requested and never as evidence of the user's store.

Reuse a preview only when theme/revision, dataset, task ownership and browser URL match. Otherwise copy the intended theme into a temporary workspace with separate runtime/data directories. Preserve source package files, unrelated processes and work; do not commit generated data. Follow target build instructions and authorization.

Verify native-package support, a persistent managed process and protected browser access. Browser and shell may run on different machines; localhost or `0.0.0.0` does not establish access or authentication. Use the host's protected preview mechanism, never an unauthenticated public tunnel for private source. Name missing capabilities; finite HTML output cannot replace interaction evidence.

## Prepare a disposable test store

Use the tested `0.1.16` release and confirm the platform binary with `lsf --version`. Replace these example paths with the task workspace. Install only there, outside StoreSkills and the original theme; keep the version fixed between baseline and retest.

```sh
npm install --prefix /tmp/store-preview/runtime --no-audit --no-fund --save-exact local-storefront@0.1.16
/tmp/store-preview/runtime/node_modules/.bin/lsf --version
/tmp/store-preview/runtime/node_modules/.bin/lsf init --theme /tmp/store-preview/theme --data /tmp/store-preview/data
/tmp/store-preview/runtime/node_modules/.bin/lsf validate --theme /tmp/store-preview/theme --data /tmp/store-preview/data --format json
/tmp/store-preview/runtime/node_modules/.bin/lsf check --theme /tmp/store-preview/theme --format json
```

Use the OS-appropriate launcher; npm supplies the native binary as an optional dependency. A missing binary is a platform/install blocker. With `npx`, specify `local-storefront@0.1.16`, never `npx lsf`, which resolves another package.

Use generated demo data or fictional products, variants, inventory, menus and collections; fictional customers only when needed. Consult the pinned CLI's `schema`/`docs` before adding fields. Keep production catalog, customer data and credentials out. Revalidate edits and diagnose errors by file/JSON pointer. Use `check` diagnostically, without `--fix` or formatting theme source.

## Start, inspect, and stop

Run interactive previews through the host's managed process facility:

```sh
/tmp/store-preview/runtime/node_modules/.bin/lsf serve --theme /tmp/store-preview/theme --data /tmp/store-preview/data --host 127.0.0.1 --port 0 --strict --live-reload
```

For repeatable captures, replace `--live-reload` with `--static --quiet` and restart after edits. Bind loopback locally; use another interface only when required by protected container routing.

Record process/session ownership, paths, version, revision and dataset. Read the actual address from readiness output. Verify `GET /__lsf/status` matches the selected theme/data without data errors, then open it in the intended browser. Select real handles from `lsf routes` or status output.

Inspect homepage, collection, product and cart at desktop/mobile widths, including relevant variants, anonymous cart/quantity controls, browser errors and Liquid diagnostics. Isolate or clear preview sessions between scenarios. Use `/__lsf/session` only against an explicitly identified disposable local preview.

Refresh only supplied authorized changes, reload/restart and retest exact affected routes. Keep requested interactive previews running when supported and report lifetime/stop instructions. Follow requested one-off QA cleanup; on failure, cancellation or stop, remove only owned processes, temporary access and files.

| Failure | Response |
| --- | --- |
| Port in use | Choose a free/dynamic port; preserve the listener. |
| Invalid data | Correct the named disposable field and revalidate. |
| Rendering/unsupported feature | Retain diagnostics and distinguish simulator limits from theme defects. |
| Browser unreachable | Check protected routing; record verification blocked if unresolved. |
| Process/host expired | Relaunch through supported lifecycle and reverify identity; discard stale readiness claims. |

## Evidence and report use

Map source/revision, dataset, emulator/version and browser origin to each tested route/state/viewport, expected content and observed interaction. A ready message, HTTP 200 or port is insufficient. Separate setup, rendering and interaction failures; recheck after source/data changes.

Compare equivalent local runs only. Synthetic media cannot prove production imagery, and local timing is lab evidence, not field performance, historical analytics or conversion rates.

The emulator lacks Shopify checkout, apps, discounts, taxes, shipping rates and B2B catalog pricing. Missing simulated capabilities are not store defects without independent evidence. Drift reports retain successful homepage/collection/product/cart images in one partial Finding with checkout blocked. Funnel rates and experiment results need real target-bound data.

Read-only audit, drift and performance reports consume an already prepared browser-reachable URL; they do not install packages, create data or start servers. Drift/performance do not require a repository. Glue needs a separate host-controlled setup capability outside evaluation; use an existing preview or record the blocker without bypassing guards.

## References

Use docs matching the pinned release; upstream main may describe newer behavior.

- [Package and release source](https://github.com/0xtlt/local-storefront)
- [Pinned release](https://github.com/0xtlt/local-storefront/releases/tag/v0.1.16)
- [CLI reference](https://github.com/0xtlt/local-storefront/blob/v0.1.16/docs/cli.md)
- [Synthetic data format](https://github.com/0xtlt/local-storefront/blob/v0.1.16/docs/data-format.md)
- [Control API and sessions](https://github.com/0xtlt/local-storefront/blob/v0.1.16/docs/control-api.md)
- [Compatibility limitations](https://github.com/0xtlt/local-storefront/blob/v0.1.16/docs/compatibility.md)