local-storefront 0.2.0 → 0.3.0-rc.2

package/docs/formatting.md

@@ -0,0 +1,119 @@
+# Formatting
+
+`npx local-storefront fmt` formats Liquid files the way [Prettier](https://prettier.io) does
+with Shopify's Liquid plugin (`@shopify/prettier-plugin-liquid`). Neither is needed:
+local-storefront does it itself, and Shopify's Horizon theme, some 280 files, takes about a
+fifth of a second.
+
+## Format the theme
+
+```bash
+npx local-storefront fmt
+```
+
+Formats every `.liquid` file of the theme: Liquid, HTML, the JSON of `{% schema %}`, the CSS
+of `<style>`, `{% style %}` and `{% stylesheet %}`, and the JavaScript of `<script>` and
+`{% javascript %}`. A theme that Prettier has formatted comes out unchanged.
+
+Format some files only:
+
+```bash
+npx local-storefront fmt sections/header.liquid snippets
+```
+
+Format the files you changed since the last commit, staged or not, and the new ones:
+
+```bash
+npx local-storefront fmt $(git diff --name-only --diff-filter=d HEAD; git ls-files --others --exclude-standard)
+```
+
+`git diff` leaves out the new files that are not staged: `git ls-files --others` adds them.
+`--diff-filter=d` leaves out deleted files, which `fmt` could not read. With nothing changed,
+the list is empty and `fmt` formats the whole theme.
+
+A file named on its own is formatted if it is a `.liquid` file that `.prettierignore` does not
+name, as Prettier does: the other files of that list are left alone.
+
+## Check in CI
+
+```bash
+npx local-storefront fmt --check
+```
+
+Writes nothing. Lists the files that are not formatted, and exits with `1` if there are any.
+
+## From an editor
+
+```bash
+npx local-storefront fmt --stdin --stdin-filepath sections/header.liquid < sections/header.liquid
+```
+
+Reads the source from the standard input and prints it formatted. `--stdin-filepath` gives
+the configuration and the `.prettierignore` of that file; an ignored file is printed as it is.
+
+## Configuration
+
+Your Prettier configuration applies. It is looked for as Prettier looks for it: from the folder
+of each file, up. These files are read:
+
+- `.prettierrc` (JSON or YAML), `.prettierrc.json`, `.prettierrc.yaml`, `.prettierrc.yml`;
+- the `prettier` key of `package.json`;
+- their `overrides`;
+- `.editorconfig`;
+- `.prettierignore`, the nearest one from the theme folder up.
+
+A configuration written in JavaScript (`prettier.config.js`) cannot be read:
+`npx local-storefront fmt` says so, and the files of its folder get the default options, as
+Prettier's search stops there too.
+
+To set an option from the command line, under the name Prettier gives it:
+
+```bash
+npx local-storefront fmt -o printWidth=100 -o singleQuote=true
+```
+
+It wins over the configuration files. `--no-config` ignores the files.
+
+### Options
+
+| Prettier option | Default | What it changes |
+|---|---|---|
+| `printWidth` | `120` | The width lines are kept under. |
+| `tabWidth` | `2` | Spaces per level of indentation. |
+| `useTabs` | `false` | Indents with tabs. |
+| `endOfLine` | `lf` | `lf`, `crlf`, `cr`, or `auto` for what the file uses. |
+| `singleQuote` | `false` | Single quotes around HTML attributes. |
+| `liquidSingleQuote` | `true` | Single quotes around the strings of Liquid. |
+| `embeddedSingleQuote` | `true` | Single quotes in the CSS and the JavaScript of `<style>`, `<script>` and the `{% style %}`, `{% stylesheet %}` and `{% javascript %}` tags. |
+| `bracketSameLine` | `false` | Puts the `>` of a tag at the end of its last attribute. |
+| `singleAttributePerLine` | `false` | One attribute per line as soon as a tag has two. |
+| `htmlWhitespaceSensitivity` | `css` | Where whitespace may be added or removed: `css`, `strict`, `ignore`. |
+| `captureWhitespaceSensitivity` | `strict` | `ignore` formats what a `{% capture %}` holds. |
+| `singleLineLinkTags` | `false` | Keeps `<link>` tags on one line. |
+| `indentSchema` | `false` | Indents the JSON of `{% schema %}`. |
+| `liquidDocParamDash` | `true` | A dash between a `@param` of `{% doc %}` and its description. |
+| `embeddedLanguageFormatting` | `auto` | `off` leaves JSON, CSS and JavaScript as they are written. |
+| `semi` | `true` | A semicolon at the end of each statement of JavaScript. |
+| `jsxSingleQuote` | `false` | Single quotes around the attributes of JSX. |
+| `quoteProps` | `as-needed` | Quotes around the keys of objects: `as-needed`, `consistent`, `preserve`. |
+| `trailingComma` | `all` | A comma after the last item of a list on several lines: `all`, `es5`, `none`. |
+| `bracketSpacing` | `true` | Spaces inside the braces of an object, in JavaScript and JSON. |
+| `objectWrap` | `preserve` | `collapse` puts an object on one line when it fits, even if it started on several. |
+| `arrowParens` | `always` | Parentheses around the only parameter of an arrow function: `always`, `avoid`. |
+| `experimentalOperatorPosition` | `end` | `start` begins a broken line with its operator. |
+
+Other options of Prettier are ignored in a configuration file.
+
+## Safety
+
+- A file is replaced in one step, with its permissions: an interrupted run leaves no
+  half-written template, and a read-only file is not replaced.
+- In a folder, `node_modules`, `.git`, links to folders and what `.prettierignore` names are
+  left out.
+- A file or a folder that cannot be read, written or formatted is reported, the others are
+  formatted all the same, and the command exits with `2`.
+
+## What differs from Prettier
+
+How the output is compared with Prettier's, and the few things it does not format:
+[compatibility](compatibility.md#formatting).

package/docs/performance.md

@@ -0,0 +1,267 @@
+# Performance
+
+Two tools to make a page faster: render times on every response, and the profile of one page.
+Both measure local-storefront on your machine, not Shopify. Use them to compare: before and
+after a change, one section with another. To see what a page would cost Shopify, profile it in
+[points](#what-the-page-would-cost-shopify).
+
+> **Find the slow snippet**
+>
+> 1. `npx local-storefront profile <path>`: read "Slowest on their own", the files that take
+>    the most time. Skip `render`, the page as a whole.
+> 2. `npx local-storefront profile <path> --lines`: the line, inside that file
+>    (`snippets/product-media:40`).
+> 3. `npx local-storefront profile <path> --points --lines`: what that line would cost Shopify,
+>    such as a loop over `collections` or a metafield read for each product of a loop.
+
+## Profile a page
+
+```bash
+npx local-storefront profile /collections/all
+```
+
+```text
+/collections/all · template collection · 2.502 ms
+The render in the middle of 15, which took from 2.325 to 2.901 ms.
+Times are in ms, for all the calls of a row. "own" leaves out what is under the row.
+
+   total      own  calls
+   2.502    0.201      1  render
+   1.510    0.005      1    templates/collection.json
+   1.464    0.029      1      section template--8034641070597__main
+   1.435    0.031      1        sections/main-collection
+   0.921    0.021      8          block product-card
+   0.900    0.031      8            blocks/_product-card
+   0.495    0.010      8              block card-gallery
+   0.485    0.022      8                blocks/_product-card-gallery
+   0.398    0.112      8                  snippets/card-gallery
+   0.122    0.122     15                    snippets/product-media
+
+Slowest on their own:
+
+     own  calls
+   0.201      1  render
+   0.191     12  snippets/list-filter
+   0.115     15  snippets/product-media
+```
+
+Each row is under the row that rendered it: a section, its file, its blocks, their snippets.
+
+- `total` is the time of the row and of everything under it.
+- `own` is the time of the row alone.
+- `calls` is how many times it was rendered. Both times are for all the calls.
+- `section <id>` and `block <key>` are a section and a block as the template places them:
+  reading their settings, then their file, which is the row under them.
+- `render` is the page as a whole. Its own time is the work outside the theme's files, such as
+  setting up the objects of the page: no file accounts for it. Skip it and read the files.
+
+The page is rendered 3 times first, so that reading the files does not count. The profile is
+the one of the render in the middle, by how long they took.
+
+### The slow line of a file
+
+```bash
+npx local-storefront profile /collections/all --lines
+```
+
+Rows such as `snippets/product-media:40` appear: a tag or an output, by its line. Timing each
+one makes the render slower: compare the rows with each other.
+
+### In the browser
+
+With the server running, the same report is a page:
+
+```text
+http://127.0.0.1:9292/__lsf/profile?path=/collections/all
+```
+
+It profiles the page as your session sees it: its cart, its customer. Add `html=1` for a
+flame graph:
+
+```text
+http://127.0.0.1:9292/__lsf/profile?path=/collections/all&html=1
+```
+
+This is speedscope, the viewer `shopify theme profile` opens. local-storefront embeds it:
+nothing is fetched from the internet. The name of the profile, at the top, switches between time
+and points. The status page (`/__lsf`) links every page to its profiles.
+
+Without a server, write the flame graph to a file and drop it on <https://www.speedscope.app>:
+
+```bash
+npx local-storefront profile /collections/all --json > profile.json
+```
+
+### Options
+
+| Option | In the URL | What it does |
+|---|---|---|
+| `--points` | `points=1` | Counts in points instead of time. In the flame graph, starts on points. |
+| `--cost <kind>=<points>,...` | `cost=<kind>=<points>,...` | Changes what a kind of thing costs. |
+| | `html=1` | Shows the flame graph. |
+| `--lines` | `lines=1` | Adds every tag and every output, by file and line. Points do not change. |
+| `--all` | `all=1` | Shows every row. Without it, what took less than a hundredth of the render is summed up as `... 3 more`. |
+| `--runs <n>` | `runs=<n>` | Renders the page `n` times. Default: 15. |
+| `--section-id <id>` | `section_id=<id>` | Profiles one section alone. |
+| `--json` | `format=speedscope` | Gives the file of the flame graph instead of the report. It holds both profiles. |
+
+## What the page would cost Shopify
+
+local-storefront loads a product or a metafield in no time. A Shopify storefront does not: a
+page that is fast here can be slow there. `--points` counts what the page asks for, instead of
+the time it takes:
+
+```bash
+npx local-storefront profile /collections/all --points
+```
+
+```text
+/collections/all · template collection · 15566 points
+Points are a model of what the page costs a Shopify storefront, not a measure:
+what they are made of is at the end. They are the same at every render.
+Points are for all the calls of a row. "own" leaves out what is under the row.
+
+   total      own  calls
+   15566        0      1  render
+   11566        0      1    templates/collection.json
+   11261        0      1      section template--8034641070597__main
+   11261      870      1        sections/main-collection
+    6877        0      8          block product-card
+    6877      112      8            blocks/_product-card
+
+Costliest on their own:
+
+     own  calls
+    1520     12  snippets/list-filter
+    1276     33  snippets/spacing-style
+
+What the points are made of:
+
+  points   count   each
+   14246   14246      1  liquid      A tag or an output rendered.
+     800       8    100  product     A product loaded.
+     220      22     10  variant     A variant loaded.
+     100       1    100  collection  A collection loaded.
+     200       2    100  menu        A menu loaded.
+```
+
+The report is the same tree, in points, then the costliest rows on their own. A row has the
+points of everything that happened under it: a snippet that reads a metafield of 50 products
+has the points of 50 metafields.
+
+| Kind | Points | Charged for |
+|---|---|---|
+| `liquid` | 1 | A tag or an output rendered. |
+| `product` | 100 | A product loaded. |
+| `variant` | 10 | A variant loaded. |
+| `collection` | 100 | A collection loaded. |
+| `metafield` | 100 | A metafield read. |
+| `metaobject` | 100 | A metaobject loaded. |
+| `page` | 100 | A page loaded. |
+| `blog` | 100 | A blog loaded. |
+| `article` | 100 | An article loaded. |
+| `menu` | 100 | A menu loaded. |
+| `search` | 1000 | A search, a predictive search or the recommendations of a product. |
+
+- **Points are a model, not a measure.** Shopify does not publish what it spends on what. The
+  unit is a tag rendered, and what a store has to fetch is taken to weigh as much as 100
+  tags. Read the counts first: they are facts. The points only weigh them.
+- What is loaded counts once per page, however many times the templates read it. A product in
+  a loop counts once per product.
+- A metafield that does not exist counts too: the store looks for it all the same.
+- Points are the same at every render and on every machine, so a test can compare them.
+
+To change the costs, for example after comparing with `shopify theme profile` on your store:
+
+```bash
+npx local-storefront profile /collections/all --points --cost product=300,metafield=50
+```
+
+## Render times
+
+Every response says how long the server took, in the `Server-Timing` header, as Shopify does:
+
+```text
+server-timing: processing;dur=3.09, render;dur=2.507, template;dur=1.27, layout;dur=0.986, compress;dur=0.53
+```
+
+In Chrome: DevTools, Network, click the page, Timing. The times are under "Server Timing".
+
+To see each section and each block too:
+
+```bash
+npx local-storefront serve --timings
+```
+
+```text
+section;dur=1.922;desc="main-collection template--8034641070597__main"
+block;dur=0.636;desc="- filters"
+block;dur=1.123;desc="- _product-card product-card x8"
+block;dur=0.611;desc="- - _product-card-gallery card-gallery x8"
+```
+
+A block comes under its section, with one dash per level. `x8` means it was rendered 8 times,
+and the time is the time of all 8.
+
+In a test:
+
+```ts
+const response = await page.goto('/');
+const timing = response.headers()['server-timing'];
+```
+
+### Many requests
+
+Start from zero:
+
+```bash
+curl -X DELETE http://127.0.0.1:9292/__lsf/timings
+```
+
+Load your pages, then read the totals:
+
+```bash
+curl http://127.0.0.1:9292/__lsf/timings
+```
+
+```json
+{
+  "templates": [
+    { "template": "collection", "count": 2000, "total": 5792.9, "mean": 2.896, "p50": 2.851, "p95": 3.31, "min": 2.308, "max": 7.495 }
+  ],
+  "sections": [
+    { "id": "template--8034641070597__main", "type": "main-collection", "count": 2000, "total": 3455.621, "mean": 1.728, "p50": 1.688, "p95": 1.982, "min": 1.281, "max": 5.537 }
+  ],
+  "blocks": [
+    { "id": "A1456318a0478e95__product-card", "type": "_product-card", "section": "template--8034641070597__main", "count": 16000, "total": 2196.216, "mean": 0.137, "p50": 0.12, "p95": 0.223, "min": 0.064, "max": 2.549 }
+  ]
+}
+```
+
+What took the most time in all comes first. A block counts once each time it is rendered: 8
+product cards on 2000 pages are 16000. `p50` and `p95` are within 2% of the exact value.
+
+### Entries of `Server-Timing`
+
+Times are in milliseconds.
+
+| Entry | Meaning |
+|---|---|
+| `processing` | Everything the server did for the request. Shopify uses the same name. |
+| `render` | Rendering the Liquid of a page or of sections. |
+| `template` | The template of the page: what goes into `content_for_layout`. |
+| `layout` | The layout around it, with its header and its footer. |
+| `section` | One section, with `--timings`. Its description is its type, then its id: the one of `#shopify-section-<id>`. |
+| `block` | One theme block, with `--timings`. Its description is a dash per level, its type, its key in the template, then `x<n>` when it was rendered more than once. |
+| `omitted` | Only on a page with hundreds of blocks: how many of the fastest ones the header leaves out. `/__lsf/timings` has them all. |
+| `compress` | Compressing the response. |
+| `throttle` | The delay of `--throttle`. It is not part of `processing`. |
+
+- A time includes what is inside: a section is part of `template` or of `layout`, a block is
+  part of its section, and of the block it is in.
+- Only theme blocks are timed: the files of `blocks/`, rendered with `content_for`. Blocks
+  that a section writes itself, in a loop over `section.blocks`, are part of the section.
+- `/__lsf/timings` counts pages by template, sections and blocks by id. Sections and blocks
+  count wherever they are rendered: in a page, alone, or in a cart response. The id of a
+  block is the one of `#shopify-block-<id>` the first time it renders, and ends with its key:
+  the renders after it (`<id>-1`, `<id>-2`, as on Shopify) count under it.

package/docs/quickstart-admin-api.md

@@ -0,0 +1,211 @@
+# Quickstart: an Admin API backend
+
+From the backend of a Shopify app to a local GraphQL Admin API (2026-10) it queries, webhooks it
+receives, and a test that runs in CI. No development store, no tunnel. This page needs no theme
+and no React: a sync job, a worker or any server works the same way.
+
+## 1. Start lsf for the app
+
+lsf reads the app's `shopify.app.toml`: the client id, the scopes the token gets, and the
+webhook subscriptions.
+
+```toml
+client_id = "0123456789abcdef0123456789abcdef"
+handle = "my-backend"
+application_url = "https://my-app.trycloudflare.com"
+
+[access_scopes]
+scopes = "read_products,write_products,read_orders"
+
+[webhooks]
+api_version = "2026-10"
+
+  [[webhooks.subscriptions]]
+  topics = ["products/create", "app/uninstalled"]
+  uri = "/webhooks"
+```
+
+The token gets these scopes and no others, as on Shopify: with `read_orders` alone, an order
+reads, but its `customer` (`read_customers`), its returns (`read_returns`) and its fulfillment
+orders (`read_merchant_managed_fulfillment_orders`) answer `ACCESS_DENIED`, which names the scope
+to add. Add the scopes your backend reads, then restart lsf or call `POST /__lsf/admin/install`.
+
+It signs webhooks with the client secret: `SHOPIFY_API_SECRET` of the environment or of the
+app's `.env`, where `shopify app env pull` writes it. In the app's folder:
+
+```bash
+npm install --save-dev local-storefront
+npx local-storefront serve --app . --only admin --app-url http://localhost:3000
+```
+
+```text
+app:    . (no extensions: the Admin API, webhooks and the app proxy)
+data:   built-in demo store (the `init` command writes an editable copy)
+serving: admin
+admin:  http://127.0.0.1:9292/admin/api/2026-10/graphql.json
+        X-Shopify-Access-Token: shpat_…   (shop: local-supply-co.myshopify.com)
+        client secret: from SHOPIFY_API_SECRET of ./.env
+        GraphiQL: http://127.0.0.1:9292/__lsf/graphiql   (queries in the browser, the token filled in)
+webhooks: 2 subscriptions of shopify.app.toml → http://localhost:3000
+embedded: http://127.0.0.1:9292/admin/apps/my-backend   (the app in lsf's admin; …)
+ready:  http://127.0.0.1:9292/   (status and control API: http://127.0.0.1:9292/__lsf)
+```
+
+`--only admin` serves the Admin API alone. `--app-url` is where your backend listens: webhooks
+go there, and nowhere off this machine. `app dev --app . --app-url …` serves the app's checkout
+too.
+
+What the Admin API creates lives in memory: a restart of lsf puts every shop back to the store
+data. The tokens survive it: the backend's stored sessions keep working.
+
+## 2. Query it
+
+The token is printed, and is the same every run for this app: a test can hard-code it.
+`GET /__lsf/admin` gives it too, as `shops[0].token`.
+
+```bash
+curl -s http://127.0.0.1:9292/admin/api/2026-10/graphql.json \
+  -H 'Content-Type: application/json' -H "X-Shopify-Access-Token: $TOKEN" \
+  -d '{"query": "{ shop { name } }"}'
+```
+
+With `@shopify/admin-api-client`, which always builds an `https://` URL, rewrite the URL in its
+fetch. The same code talks to Shopify when `LSF_URL` is not set:
+
+```js
+// query.mjs
+import { createAdminApiClient } from "@shopify/admin-api-client";
+
+const lsf = process.env.LSF_URL; // http://127.0.0.1:9292
+const client = createAdminApiClient({
+  storeDomain: "local-supply-co.myshopify.com",
+  apiVersion: "2026-10",
+  accessToken: process.env.SHOPIFY_ACCESS_TOKEN,
+  customFetchApi: lsf
+    ? (url, init) => fetch(String(url).replace(/^https:\/\/[^/]+/, lsf), init)
+    : fetch,
+});
+
+const { data } = await client.request(`{ products(first: 3) { nodes { title } } }`);
+console.log(data.products.nodes);
+```
+
+```bash
+LSF_URL=http://127.0.0.1:9292 SHOPIFY_ACCESS_TOKEN=shpat_… node query.mjs
+```
+
+<http://127.0.0.1:9292/__lsf/graphiql> is a query editor with the token and the schema's docs,
+offline. Ruby, Python and the React Router package: [point the backend at
+lsf](admin.md#point-the-backend-at-lsf).
+
+## 3. Receive webhooks
+
+A mutation sends its webhooks to `--app-url`, signed as Shopify signs them. Check the HMAC on the
+raw bytes of the body:
+
+```js
+// receiver.mjs: node --env-file=.env receiver.mjs
+import { createServer } from "node:http";
+import { createHmac, timingSafeEqual } from "node:crypto";
+
+createServer(async (req, res) => {
+  const chunks = [];
+  for await (const chunk of req) chunks.push(chunk);
+  const body = Buffer.concat(chunks);
+  const digest = createHmac("sha256", process.env.SHOPIFY_API_SECRET).update(body).digest();
+  const header = Buffer.from(req.headers["x-shopify-hmac-sha256"] ?? "", "base64");
+  if (header.length !== digest.length || !timingSafeEqual(header, digest)) {
+    return res.writeHead(401).end();
+  }
+  console.log(req.headers["x-shopify-topic"], JSON.parse(body).id);
+  res.writeHead(200).end();
+}).listen(Number(process.env.PORT ?? 3000));
+```
+
+A `productCreate` now prints `products/create 8397442660771`. To send one without a mutation:
+
+```bash
+npx local-storefront app webhook trigger --topic app/uninstalled --app-url http://localhost:3000
+```
+
+`GET /__lsf/webhooks` lists every delivery, with what the backend answered. A `401` there names
+the secret lsf signed with.
+
+## 4. Write a test
+
+Reset the shop before each test, read `last` before the action, and wait for the webhook it sends:
+
+```js
+// test/products.test.mjs: node --test
+import { test, beforeEach } from "node:test";
+import assert from "node:assert/strict";
+
+const LSF = process.env.LSF_URL ?? "http://127.0.0.1:9292";
+const lsf = (method, path, body) =>
+  fetch(LSF + path, { method, body: body && JSON.stringify(body) }).then((r) => r.json());
+
+beforeEach(() => lsf("DELETE", "/__lsf/admin")); // every shop back to the store data
+
+test("productCreate sends products/create", async () => {
+  const { shops } = await lsf("GET", "/__lsf/admin");
+  const { last } = await lsf("GET", "/__lsf/webhooks"); // the newest delivery so far
+
+  const answer = await fetch(`${LSF}/admin/api/2026-10/graphql.json`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json", "X-Shopify-Access-Token": shops[0].token },
+    body: JSON.stringify({ query: `mutation { productCreate(product: {title: "Mug"}) { product { id } } }` }),
+  }).then((r) => r.json());
+  const id = answer.data.productCreate.product.id;
+
+  const { deliveries } = await lsf("GET", `/__lsf/webhooks?topic=products/create&since=${last}&wait=1`);
+  assert.equal(deliveries[0].resource, id);
+  assert.equal(deliveries[0].state, "delivered"); // the receiver checked the HMAC
+});
+```
+
+`DELETE /__lsf/admin` puts every shop back to the store data: records, clock, outbox and tokens.
+It revokes the tokens the backend got by token exchange or OAuth; the printed one keeps working.
+Tests that run in parallel each take a shop of their own (`POST /__lsf/admin/shops`):
+[a shop per test](admin.md#a-shop-per-test).
+
+## 5. Move the clock
+
+```bash
+curl -X POST http://127.0.0.1:9292/__lsf/admin/clock -d '{"advance": "31d"}'
+```
+
+The shop's time moves on and stays there: payment schedules come due, checkouts are abandoned,
+app subscriptions renew, each with its webhooks. `DELETE /__lsf/admin` puts the clock back.
+
+## 6. Run it in CI
+
+```yaml
+# .github/workflows/backend.yml
+name: backend
+on: [push, pull_request]
+jobs:
+  backend:
+    runs-on: ubuntu-latest
+    env:
+      SHOPIFY_API_SECRET: test-secret # lsf signs with it, the receiver checks with it
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-node@v7
+        with:
+          node-version: 24
+          cache: npm
+      - run: npm ci
+      - run: |
+          npx local-storefront serve --app . --only admin --app-url http://localhost:3000 --static --quiet &
+          node receiver.mjs &
+          until curl -sf http://127.0.0.1:9292/__lsf/status > /dev/null; do sleep 0.2; done
+          node --test
+```
+
+## Next
+
+- [Admin API](admin.md): the libraries, tokens and OAuth, webhooks, a shop per test, orders from
+  the checkout, billing, the app proxy, API versions.
+- [Admin API reference](admin-reference.md): what each mutation does, and what lsf leaves out.
+- [Control API](control-api.md#apps-checkout-and-admin-api): every `/__lsf/admin` endpoint.
+- [Quickstart: a public app](quickstart-app.md), for the React Router template.