local-storefront 0.1.18 → 0.3.0-rc.1

package/README.md

@@ -1,8 +1,9 @@
 # local-storefront
 
-Run a Shopify theme on your machine, without Shopify. Its command, local-storefront, serves a
-theme rendered from JSON store data instead of the Shopify API: no network, no rate limit, and
-each test gets exactly the catalog, cart and customer it asks for.
+Run Shopify themes and Shopify apps on your machine, without Shopify. From your theme, your app
+and JSON store data, local-storefront serves the storefront, the checkout of your app and a local
+GraphQL Admin API. There is no development store, no network and no rate limit, and each test
+gets exactly the catalog, cart and customer it asks for.
 
 ```bash
 npm install --save-dev local-storefront
@@ -18,10 +19,12 @@ Inside the `scripts` of `package.json`, `local-storefront serve` is enough.
 | Command | What it does |
 |---|---|
 | `npx local-storefront serve` | Serves the theme at <http://127.0.0.1:9292>. |
-| `npx local-storefront validate` | Checks the store data. |
+| `npx local-storefront validate` | Checks the store data and the checkout scenarios, with or without a theme. |
 | `npx local-storefront check --fix` | Fixes what Shopify's strict Liquid parser rejects. |
 | `npx local-storefront fmt` | Formats Liquid files as Prettier does. |
 | `npx local-storefront profile <path>` | Shows what makes a page slow. |
+| `npx local-storefront app dev --app <dir>` | Serves a Shopify app: its checkout, where its Functions run and its UI extensions show, and the Admin API of its backend. |
+| `npx local-storefront app check --app <dir>` | Runs the app's checkout scenarios and checks what each must look like, for CI. |
 
 With Playwright:
 
@@ -30,16 +33,18 @@ With Playwright:
 import { defineConfig } from '@playwright/test';
 
 export default defineConfig({
-  use: { baseURL: 'http://127.0.0.1:9292' },
+  // A port of its own, so that a local run never reuses your dev server.
+  use: { baseURL: 'http://127.0.0.1:9393' },
   webServer: {
-    command: 'npx local-storefront serve --port 9292 --static --quiet --strict',
-    url: 'http://127.0.0.1:9292/__lsf/status',
+    command: 'npx local-storefront serve --port 9393 --static --quiet --strict',
+    url: 'http://127.0.0.1:9393/__lsf/status',
     reuseExistingServer: !process.env.CI,
   },
 });
 ```
 
-This package only contains a launcher. The local-storefront binary comes from a platform package
-that npm installs alongside it: macOS, Linux and Windows, on x64 and arm64.
+This package holds a launcher and the docs. The local-storefront binary comes from a platform
+package that npm installs alongside it: macOS, Linux and Windows, on x64 and arm64.
 
-Documentation: <https://github.com/0xtlt/local-storefront>
+The docs of this version are in the package: `node_modules/local-storefront/docs/`, listed by
+`node_modules/local-storefront/llms.txt`. Online: <https://github.com/0xtlt/local-storefront>

package/bin/lsf.js

@@ -26,7 +26,10 @@ try {
   process.exit(1);
 }
 
-const child = spawn(binary, process.argv.slice(2), { stdio: 'inherit' });
+// Installed with npm, the command is `npx local-storefront`, not `lsf`: the hints of the binary
+// (`build it with \`lsf app build …\``) say what to type.
+const env = { ...process.env, LSF_COMMAND: process.env.LSF_COMMAND || 'npx local-storefront' };
+const child = spawn(binary, process.argv.slice(2), { stdio: 'inherit', env });
 
 // A runner that stops this process (Playwright's webServer, a CI step) must stop the server.
 const signals = ['SIGINT', 'SIGTERM', 'SIGHUP'];

package/docs/README.md

@@ -0,0 +1,59 @@
+# Documentation
+
+local-storefront runs a Shopify theme, and the checkout and the Admin API of an app, on your
+machine, without Shopify, from JSON store data.
+
+## Get started
+
+In your theme folder:
+
+```bash
+npm install --save-dev local-storefront
+npx local-storefront serve        # http://127.0.0.1:9292, with a demo store
+npx local-storefront init         # writes shopify-local/, the store data to edit
+```
+
+Write `npx local-storefront`, not `npx lsf`: `lsf` is another package on npm. Other ways to
+install (mise, a binary, from source):
+[the project's README](https://github.com/0xtlt/local-storefront#other-ways-to-install).
+
+## Start here
+
+One page each, from the first command to a test in CI.
+
+| Quickstart | For |
+|---|---|
+| [A theme](quickstart-theme.md) | Serving a theme, writing store data, `validate`, `check`, a Playwright test. |
+| [Functions](quickstart-functions.md) | Running an app's Functions and checkout UI extensions: scenarios, `expect`, `app check` in CI. |
+| [An Admin API backend](quickstart-admin-api.md) | A backend against the local Admin API: the token, a first query, webhooks, resets, the clock. |
+| [A public app](quickstart-app.md) | The React Router template end to end: the embedded admin, Events, billing, a theme app extension, the app proxy. |
+
+## Guides
+
+One task each, from the first command to the details.
+
+| Guide | For |
+|---|---|
+| [Data format](data-format.md) | Writing the store data: products, customers, menus, metafields. |
+| [Testing](testing.md) | End-to-end tests: sessions, per-test data, slow networks, CI. |
+| [Strict Liquid](strict-liquid.md) | Finding and fixing what Shopify's strict Liquid parser rejects. |
+| [Formatting](formatting.md) | Formatting Liquid files as Prettier does. |
+| [Performance](performance.md) | Profiling a page, in time or in what it would cost Shopify. |
+| [Checkout](checkout.md) | Running the Functions and the checkout UI extensions of a Shopify app. |
+| [Admin API](admin.md) | Pointing the backend of an app at the local Admin API, its OAuth and its webhooks; previewing its embedded pages in a local admin, with a local App Bridge. |
+| [Storefront](storefront.md) | The storefront in a browser: accounts, password page, images, previews, the theme app extensions of an app. |
+| [Agents](agents.md) | Driving local-storefront from an AI agent or a script. |
+
+## Reference
+
+| Reference | For |
+|---|---|
+| [CLI](cli.md) | Every command, option, exit code and output format. |
+| [Control API](control-api.md) | The `/__lsf` endpoints, sessions and response headers. |
+| [Admin API reference](admin-reference.md) | What the local Admin API simulates, family by family: queries, mutations, webhooks, and what it leaves out. |
+| [Fields](data-reference.md) | Every field of the store data, generated from its JSON Schema. |
+| [Compatibility](compatibility.md) | What matches Shopify, how it is checked, and the known differences. |
+
+## Contributing
+
+[Architecture](architecture.md): how the code is organised, how to develop and how to release.