> ## Documentation Index
> Fetch the complete documentation index at: https://topten.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Local Development

> Set up the Live Product Insights app locally: prerequisites, running the dev server, theme preview, demo data scripts, and the developer gotchas that cost the most time.

## Prerequisites

* **Node.js** `>=20.19 <22` or `>=22.12` (enforced via `engine-strict`; other versions are refused).
* **Shopify CLI** installed and authenticated (`shopify app dev` prompts for login on first use).
* **A development store** you can install the app on.

## Install and run

```bash theme={null}
npm install
npm run dev
```

`npm run dev` starts the Shopify CLI, which in turn runs the app's own chain:

1. `prisma generate` — regenerate the Prisma client.
2. `prisma migrate deploy` — apply pending migrations to the SQLite database.
3. `react-router dev` — the application server.

When the CLI banner appears, note three things: the **admin preview URL** (opens the app inside your development store's admin), the **theme app extension preview** (a local `127.0.0.1:9293` URL), and the **theme editor link** for your store. The app port is chosen dynamically on each boot, so read it from the banner rather than assuming a fixed port.

## Secrets and environment

The project intentionally has **no committed `.env` with app secrets**. The Shopify CLI injects `SHOPIFY_API_KEY`, `SHOPIFY_API_SECRET`, `SCOPES`, and `SHOPIFY_APP_URL` into the dev process at runtime. Only `DATABASE_URL` (a local SQLite file path) exists in `.env`.

For scripted tests that need real signing secrets (proxy HMAC, webhook HMAC), pipe them from the CLI without persisting them:

```bash theme={null}
npx shopify app env show
```

Treat the output as shell-only: never write it to a file, a log, or a screenshot.

## Theme preview

The theme app extension (tracker + counter) renders through the CLI's local theme preview at `127.0.0.1:9293` while `shopify app dev` runs. The blocks must still be enabled in the store's theme — see [Theme setup](https://topten.mintlify.site/getting-started/theme-setup.md). Until the extension has been deployed at least once, the local preview may render the host theme without the blocks; the store-domain theme editor preview is the reliable surface during development.

## Demo and tooling scripts

All scripts live in `scripts/` and are development/QA utilities — none are part of the runtime.

| Script | Purpose | Notes |
| - | - | - |
| `seed-demo-data.js` | Seed realistic demo activity for demos/screenshots | Refuses to run without `LPI_DEMO_SEED=1`; idempotent (upserts); targets the shop's real synced products rather than inventing products |
| `topup-demo-presence.js` | Refresh live-presence heartbeats from recent demo views | Same env gate. Needed because active-viewer presence **intentionally decays within minutes** — re-run right before a demo |
| `sync-real-data.js` | Replace demo data with real data | Wipes the shop's analytics, syncs the catalog, backfills order history, rebuilds rollups |

> [!WARNING]
>
> Demo seeding and real-data syncing both write to the same SQLite database as your dev server. Run them while the server is stopped, or expect the dashboard numbers to move under you.

## Developer gotchas

> [accordion] The dev server 'wedge': CLI alive, every route 404
>
> The most common false alarm. The Shopify CLI process keeps running while the application server inside it has died — every route (admin, proxy, webhooks) returns 404. Verify with a status check against the app port shown in the CLI banner; `404` means wedged. Fix: stop `shopify app dev` completely and start it again.

> [accordion] Tunnel aborts on restart
>
> The quick tunnel occasionally aborts with a transient error when the dev server restarts. Simply starting the dev server again usually resolves it.

> [accordion] Expired CLI credentials in non-interactive shells
>
> Re-authentication requires a browser prompt. If your CLI session has expired, `shopify app dev` fails from background shells and scripts — re-authenticate in an interactive terminal first.

> [accordion] `shopify app config link` can drop the app proxy
>
> Re-linking app configuration can regenerate the config file without the `[app_proxy]` block. Storefront tracking silently breaks (requests never reach the app). Always re-check that the block is present after linking, and restart the dev server so the proxy URL re-registers.

> [accordion] Disable the scheduler
>
> The in-process cron (insights, order sync, rollups, retention, billing checks) starts on the first admin page load. Set `SCHEDULER_DISABLED=1` to keep it off — useful when seeding data or running tests against a predictable database.

> [accordion] Tests use the dev database
>
> Integration suites share the dev SQLite file. Fixture shops and cleanup make this safe, but don't point `DATABASE_URL` at data you care about — see [Testing](https://topten.mintlify.site/development/testing.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.