local-storefront 0.2.0 → 0.3.0-rc.2

package/docs/storefront.md

@@ -0,0 +1,251 @@
+# Storefront
+
+What you see when you open the local storefront in a browser, and the options that change it.
+
+```bash
+npx local-storefront serve --live-reload
+```
+
+Open <http://127.0.0.1:9292>. If that port is taken, local-storefront uses the next free one and
+prints the address.
+
+## Reload as you edit
+
+`--live-reload` reloads open pages as soon as you edit the theme or the data. The page listens
+on a WebSocket, and asks the server every 700 ms where a socket cannot be opened. It adds a
+script to the pages: leave it off for tests. Only HTML pages get it: a `{% layout none %}`
+template that writes JSON is left as it is.
+
+An edit of `assets/` needs no restart either, with or without `--live-reload`: a stylesheet, a
+script, an image, a `.css.liquid` or `.js.liquid` file, the bundle of the `{% stylesheet %}` and
+`{% javascript %}` tags, and the assets of a [theme app extension](#theme-app-extensions). The
+page links each file at a new `?v=` once it changes, as Shopify does, and the browser fetches
+it there. A file the theme loads without its `?v=` (a `url()` in a stylesheet, an `import` in a
+script) is kept a year by the browser, as from Shopify's CDN: link it with `asset_url`, or
+reload without the cache. `--live-reload` reloads the whole page when an asset changes; it does
+not swap a stylesheet in place.
+
+With `--live-reload`, a page with problems also shows a small panel: the errors of the store
+data, the Liquid errors of the page, and why a page is the 404 page. Its button closes it. The
+terminal has the same problems.
+
+The panel also has notes, which are not problems. A page that renders one of
+[lsf's default menus](data-format.md#lsfs-default-menus) gets a note: its links are lsf's,
+since the data has no menu with that handle. Without problems, the panel has a grey border
+instead of a red one.
+
+## Log in as a customer
+
+Open <http://127.0.0.1:9292/account>. The page lists the customers of your data: click one to
+be logged in as them, or "Nobody" to be logged out. Every account link of your theme leads to
+this page, because Shopify hosts customer accounts outside the theme.
+
+To start logged in:
+
+```bash
+npx local-storefront serve --customer default
+```
+
+`default` is the first customer of your data. You can also give an email, or `none`.
+
+A link can log a browser in too: `/__lsf/login?customer=jane.doe@example.com&return_to=/cart`.
+
+With `--app`, `/account` is the customer account of the app instead: the orders of the customer
+logged in, their profile, and the pages where the app's customer account UI extensions render.
+Logged out, it lists the customers of your data too. See
+[checkout](checkout.md#customer-account).
+
+Classic customer accounts are not simulated: the theme's `templates/customers` are never
+rendered, and its login and register forms lead to `/account` too. See the
+[data guide](data-format.md#logging-in).
+
+### B2B
+
+A customer with a company is a B2B customer: `customer.b2b?` is true, and
+`customer.current_company` and `customer.current_location` are filled. The account page lets
+you change location. Company prices (catalogs) are not simulated. How to write companies:
+[data guide](data-format.md#b2b-customers).
+
+## The password page
+
+Open <http://127.0.0.1:9292/password>. The password is `password`, or the `password` of the
+`shop` in your data. A wrong password stays on the page with the error. The storefront is
+never locked: nothing redirects to that page.
+
+## Images and videos
+
+`image_url` and `image_tag` point to your machine, which resizes and crops like Shopify's CDN,
+and sends each browser the lightest format it reads: AVIF, WebP, or the one of the file. An
+image with `preload: true` is preloaded through the `Link` header, as on Shopify.
+
+Put the files in `shopify-local/files/`. An image that is not there becomes a placeholder of
+the right size, marked with the header `x-lsf-placeholder: 1`.
+
+A video of `files/` (a `video` setting, or a metafield or a metaobject field that points to
+an `.mp4`) is a video object, with its sources and its poster, the `.jpg` of the same name.
+Videos are served in the parts a browser asks for, so they play in Safari and can be sought
+in.
+
+## What else is served as on Shopify
+
+- **Styles and scripts are minified**, with a source map, as Shopify minifies them: when that
+  makes the file lighter, and without merging declarations that cascade apart, such as
+  `translate` into `transform` ([the rules](compatibility.md#minification)). `--no-minify`
+  serves them as written.
+- **Responses are compressed** with Brotli or gzip, with Shopify's `Cache-Control`, so that an
+  audit of your theme sees what it would see on the store. `--no-compression` turns it off.
+- **Pages have Shopify's scripts:** the `Shopify` object, `Shopify.actions`,
+  `Shopify.loadFeatures`, the Customer Privacy API and `ShopifyAnalytics.meta`.
+- **The Ajax APIs a theme calls** answer as Shopify's do: cart, Section Rendering, predictive
+  search, recommendations, forms. The list: [testing](testing.md#what-the-server-answers).
+- **The app proxy of an app:** with `--app` and an `[app_proxy]` in `shopify.app.toml`,
+  `/apps/<subpath>` (or the `prefix` it names) is forwarded to the backend of the app, signed as
+  Shopify signs it, and a Liquid answer is rendered in the theme's layout. See the
+  [Admin API guide](admin.md#app-proxy).
+
+## Countries and markets in the URL
+
+A visitor's country comes from the URL as on a Shopify storefront, besides the localization form
+and `PUT /__lsf/session`:
+
+- **`?country=FR`** on any page picks a country the store sells to, for the rest of the session.
+  When the country's market is served under subfolders of its own, the answer is a `301` to the
+  same page there, the query kept: `/products/tee?country=BE` → `/en-be/products/tee?country=BE`,
+  in the page's language when the market offers it, else in the market's default.
+- **A market's subfolders**: a market with a `subfolder_suffix` (`"be"`, see
+  [localization](data-format.md#localization)) is served under `/<language>-<suffix>/`, one per
+  language of the market (`/en-be/`, `/fr-be/`; every language of the store when it lists no
+  `languages`). A subfolder in a language the market does not offer is not found, as on Shopify. A page there is in the visitor's country when the market has
+  it, else in the market's first country, in the language of the prefix; every link the theme
+  makes stays under it (`routes`, `request.locale.root_url`, the `root_url` of the languages,
+  `Shopify.routes.root`). A page at `/` is in the visitor's country when `/` serves it, else in
+  the shop's: a country picked under a subfolder does not follow the visitor to `/`.
+- **The localization form** (`{% form 'localization' %}`) sends the visitor to the same page on
+  the web presence of the country they picked: `country_code=BE` → `/en-be/...`, and back to `/`
+  for a country served there, in a language the country's market offers.
+- **The currency follows the country**: prices, the cart (`cart.currency`, `/cart.js`), the money
+  filters and the checkout are in the country's currency, at its market's rate or fixed prices
+  (see [localization](data-format.md#localization)), and `Shopify.currency` gives the currency
+  and the rate (`{"active":"EUR","rate":"0.92"}`).
+
+## Theme app extensions
+
+With `--app`, the theme renders the app blocks and app embed blocks of the app's theme app
+extensions, as Shopify does once the app is installed. An extension is a folder of the app
+whose `shopify.extension.toml` says `type = "theme"`, with `blocks/`, `snippets/`, `assets/`
+and `locales/`.
+
+```bash
+npx local-storefront serve --app ../my-app --live-reload
+```
+
+The `app:` line counts them: `(0 Functions, 0 UI extensions, 1 theme extension (2 app blocks,
+1 app embed block))`.
+
+### App blocks
+
+A JSON template or a section group names an app block by its type, as the theme editor writes
+it:
+
+```json
+"reviews": {
+  "type": "shopify://apps/product-reviews/blocks/reviews/5b1c7a52-2d0e-4c8a-9a3e-6f1d2b7c9e01",
+  "settings": { "heading": "Loved by customers" }
+}
+```
+
+`product-reviews` is the `handle` of `shopify.app.toml`, or its `name` as a handle. `reviews` is
+the file `blocks/reviews.liquid` of one of its extensions. The last part is the `uid` of the
+extension. A type copied from another store has another id: the block is found by its name all
+the same.
+
+The block renders where the theme renders blocks:
+
+- `{% render block %}`, for a block of `section.blocks` whose `block.type` is `@app`, as in Dawn;
+- `{% content_for 'blocks' %}`, in a section or a theme block that accepts `@app` blocks, as in
+  Horizon;
+- a section of type `apps`, which the theme editor adds around an app block: the theme's
+  `sections/apps.liquid`, or Shopify's own wrapper when the theme has none.
+
+Its output is wrapped as on Shopify, in `<div id="shopify-block-<id>" class="shopify-block
+shopify-app-block">`, with the `class` and the `tag` of its schema. Its Liquid reads:
+
+- `block.settings`, with the defaults of its schema; a `t:` default is read from the
+  extension's `locales/*.schema.json`;
+- `block.id`, `block.type` (`@app`), `section`, `closest`, and the objects of the page
+  (`product` on a product page);
+- `app.metafields`: the app-data metafields of the store data (`app.metafields`, below).
+
+In the Liquid of an extension, `{% render 'stars' %}` renders its `snippets/stars.liquid`,
+`asset_url` points to its `assets/` (served at `/cdn/extensions/<uid>/assets/`), and `t` reads
+its `locales/`, never the theme's. The `javascript` and the `stylesheet` of a schema load once
+per page, before `</head>`, when a block that names them renders. `enabled_on` and
+`disabled_on` keep a block out of templates and section groups; `available_if` keeps it out
+until its metafield is `true`.
+
+### App embed blocks
+
+An app embed block (`"target": "head"`, `"compliance_head"` or `"body"`) renders on every page
+where it is turned on: `compliance_head` then `head` before `</head>`, `body` before `</body>`.
+The theme editor turns one on in `config/settings_data.json`, under `current.blocks`, with
+`"disabled": false`. To turn one on without changing the theme, or to set the app-data
+metafields, write `app` in the store data:
+
+```json
+{
+  "app": {
+    "embeds": {
+      "chat-bubble": true,
+      "reviews-loader": { "settings": { "api_key": "test-key" } }
+    },
+    "metafields": { "reviews": { "badge_enabled": true } }
+  }
+}
+```
+
+An embed is named by its file in `blocks/`. `true` turns it on, with the settings of
+`config/settings_data.json` or its defaults; `false` turns it off; `{"settings": {...}}` turns
+it on with these. A test does it for its session alone with `PUT /__lsf/session` and
+`{"data": {"app": ...}}` ([testing](testing.md#data-for-one-test-only)).
+
+### When a block renders nothing
+
+lsf says why, once in the terminal and in the `X-LSF-Reason` header of the page: the app has no
+block of that name, the block is another app's, no app is served (`--app`), `enabled_on` leaves
+the page out, `available_if` is not `true`. An app embed block the theme turns on says so too
+when no app is served. When several blocks of a page render nothing, `X-LSF-Reason` gives them
+all: `3 reasons: … | … | …`. A Liquid error in a file of an extension is reported
+as the theme's are, with its path: `Liquid syntax error (extensions/reviews/snippets/stars line
+1): Unknown tag 'unknowntag'`.
+
+At start, `serve` prints the blocks the theme names that the app does not have
+(`app: warning: ...`, with the name it probably meant), and the blocks no template uses or the
+app embed blocks that are off (`app: note: ...`). The home page of the app
+(`/__lsf/checkouts`) lists its extensions and their blocks. `check --app ../my-app` checks the
+app blocks of the theme, and exits with `1` for one that renders nothing (a block the app does
+not have, one its `enabled_on` keeps out of the template). `app build` checks the extensions as
+Shopify does when it deploys them ([CLI reference](cli.md#app-build)).
+
+With `--live-reload`, open pages reload when a file of an extension changes. The Section
+Rendering API (`?sections=`) renders app blocks as the page does. What differs from Shopify is
+in [compatibility](compatibility.md#known-differences).
+
+## Feature previews
+
+Shopify tries changes on development stores before it ships them. A store turns them on in its
+list of feature previews. local-storefront renders what a live store renders, so a theme that
+uses a preview fails as it would there, and local-storefront says which preview to turn on:
+
+```bash
+npx local-storefront serve --preview liquid-july-26
+```
+
+`--preview` can be repeated, takes several names separated by commas, and is also read from
+`LSF_PREVIEW`. Every command accepts it.
+
+| Preview | Shopify's name | What it adds |
+|---|---|---|
+| `liquid-july-26` | Liquid July '26 changes | `{% block 'name' %}...{% endblock %}`, to call a theme block from a template or a layout; `{% partial 'name' %}...{% endpartial %}`, and `@shopify/partial-rendering` to refresh it. Shopify's [Skeleton theme](https://github.com/Shopify/skeleton-theme) needs it. |
+
+A preview can still change on Shopify's side. [Compatibility](compatibility.md) says what
+local-storefront does where Shopify has not said yet.

package/docs/strict-liquid.md

@@ -0,0 +1,178 @@
+# Strict Liquid
+
+Shopify is moving every store from its lenient Liquid parser to a strict one. A file with
+markup the strict parser rejects can no longer be uploaded:
+
+```text
+Liquid syntax error (line 12): Expected end_of_string but found pipe
+```
+
+`npx local-storefront check` finds that markup in your theme, and
+`npx local-storefront check --fix` rewrites it.
+
+## Find what the strict parser rejects
+
+```bash
+npx local-storefront check
+```
+
+```text
+snippets/card.liquid:1: Shopify's strict Liquid parser rejects this {% render %}: Expected end_of_string but found pipe
+  was: … alt: image.alt | default: shop.name
+  fix: … alt: image_alt
+  before it: assign image_alt = image.alt | default: shop.name
+  changes the output: `alt` gets `image.alt | default: shop.name`
+snippets/card.liquid:8: Shopify's strict Liquid parser rejects this {% when %}: Expected end_of_string but found id
+  was: 'collection' and collection.handle
+  fix: 'collection'
+  its body goes in: {% if collection.handle %}
+  changes the output: the body renders only when `collection.handle` is true
+2 files checked, 2 problems
+2 of them can be fixed: run again with `--fix`
+2 of the fixes change the output, where the code now does what it says: review the diff
+```
+
+Each problem gives the message Shopify gives, the markup, and the fix. `changes the output`
+marks the fixes that render something else than today. Every line of the report is described
+in the [CLI reference](cli.md#check).
+
+`npx local-storefront check` reads every `.liquid` file of `layout/`, `templates/`, `sections/`,
+`blocks/` and `snippets/`, and the `liquid` settings stored in JSON: a "Custom Liquid" section
+of a template, a section group, `config/settings_data.json`.
+
+The report lists unknown filters too:
+
+```text
+snippets/title.liquid:5: unknown filter `uppercas` (Shopify ignores unknown filters; this one is not implemented here)
+  hint: did you mean "upcase"?
+```
+
+Either it is a typo: Shopify skips a filter it does not know, and prints the value unchanged, so
+the page looks almost right. Fix the name: the `hint` gives it when a filter of Shopify is one or
+two letters away, has the same letters, or does what a filter of another template language
+does (`uppercase`). Or it is a filter of Shopify that local-storefront lacks:
+[report it](https://github.com/0xtlt/local-storefront/issues).
+
+## Fix it
+
+```bash
+npx local-storefront check --fix
+```
+
+Then review the diff before you push it:
+
+```bash
+git diff
+```
+
+A fix does one of two things.
+
+### What the code meant, where that is clear
+
+The lenient parser silently ignores what it does not understand. A theme can carry code for
+years that never did what it says. Where the intent is obvious, the fix makes the code do it:
+
+```liquid
+{% render 'image', alt: image.alt | default: shop.name %}
+```
+
+becomes
+
+```liquid
+{% assign image_alt = image.alt | default: shop.name -%}
+{% render 'image', alt: image_alt %}
+```
+
+The lenient parser never applied that filter. Now an image without alt text gets the shop's
+name. The `-%}` removes the line break the fix adds, so nothing else changes in the HTML.
+
+| Written | Fixed | What changes |
+|---|---|---|
+| `{% render 'card', on_sale: a and b %}` | A `{% liquid %}` block above the tag computes `true` or `false`, then `on_sale: card_on_sale` | `on_sale` is false when `b` is |
+| `{% assign label = ('X' \| downcase) %}` | `{% assign label = 'X' \| downcase %}` | `label` is `x`. The lenient parser read the variable `X`. |
+| `{% for i in items limit: 2 reversed %}` | `{% for i in items reversed limit: 2 %}` | The loop runs in reverse |
+| `{% if a = b %}` | `{% if a == b %}` | The condition is evaluated. It rendered an error. |
+| `{% when 'x' and y %}…` | `{% when 'x' %}{% if y %}…{% endif %}` | The body renders only when `y` is true |
+
+A `when` with `and`, in a `case` that has an `{% else %}`, meant the `else` to run when the
+condition is false. An `if` inside the `when` would not do that, so the `case` becomes
+`if`/`elsif`/`else`:
+
+```liquid
+{%- case template.name -%}
+  {%- when 'product' -%}P
+  {%- when 'collection' and collection.handle -%}C
+  {%- else -%}Z
+{%- endcase -%}
+```
+
+becomes
+
+```liquid
+{%- if template.name == 'product' -%}P
+  {%- elsif template.name == 'collection' and collection.handle -%}C
+  {%- else -%}Z
+{%- endif -%}
+```
+
+This happens only when the `when`s compare with distinct literals, since a `case` renders
+every `when` that matches and `if` only the first.
+
+### Today's output, everywhere else
+
+Where the intent is not clear, the fix keeps exactly what renders today:
+
+| Written | Fixed |
+|---|---|
+| `{{ product.title product.vendor }}` | `{{ product.title }}` |
+| `{{ 'hi' \| append, '!' }}` | `{{ 'hi' \| append: '!' }}` |
+| `{{ [key].title }}` | `{{ self[key].title }}` |
+
+## What a fix guarantees
+
+- **The strict parser accepts it.** Each rewritten file is parsed again before it is written.
+- **A fix that keeps the output is read the same by both parsers** as the original is read
+  today. These fixes were rendered by Shopify's reference implementation on 1,548 templates:
+  the HTML is identical.
+- **Nothing else in the file changes.** Arguments written one per line stay one per line, and
+  the tags around keep their `{%-` and `-%}`. In JSON, only the value of the setting changes,
+  with the escaping of the file (`<`, `\/`).
+- **A variable a fix adds gets a name the file does not use.** `image_alt` becomes
+  `image_alt_2` if the file already has an `image_alt`.
+- **A file is written only if it has not changed** since `npx local-storefront check` read it.
+
+## Fix by hand
+
+Some markup has no fix, and the report says why after `no automatic fix:`. Fix it by hand:
+
+| The report says | Write instead |
+|---|---|
+| `` `a.b` is not a name the strict parser reads `` | For `{% assign a.b = 1 %}`, a plain name: `{% assign a_b = 1 %}`, and read `a_b`. A theme cannot write into `settings` or into an object. |
+| `` `=<` is read as an operator, which renders an error today `` | The condition never worked: write the operator it meant (`<=`), or remove it. |
+| Another reason | Rewrite the markup so that `check` accepts it, then compare the page before and after: `npx local-storefront render <path>`, into a file each time, and `diff`. |
+
+## In CI
+
+```yaml
+- run: npx local-storefront check --format github
+```
+
+`npx local-storefront check` exits with `1` while a problem is left, so the build fails before
+Shopify refuses the upload. `--format github` shows each problem on its line of the pull
+request. It reads the files and renders none: an error at render time (a
+division by zero) needs `render --strict`. A complete workflow:
+[agents](agents.md#run-the-checks-in-ci); with browser tests: [testing](testing.md#in-ci).
+
+## How it is checked
+
+The rules come from Shopify's reference implementation, the `liquid` gem 5.14, in its
+`strict2` mode. They are checked against Shopify's test suite of the language: 6,314 specs,
+every rejection with the gem's message. Details:
+[compatibility](compatibility.md#shopifys-strict-liquid-parser).
+
+## From Rust
+
+The audit is in the `lsf-liquid` crate, in `lsf_liquid::strict2`: `audit` returns the findings
+of a template, `apply` writes the fixes that keep the output, and `apply_intents` writes what
+`npx local-storefront check --fix` writes. A tag of your own says how the strict parser reads it
+with `Environment::register_syntax`.