@decocms/blocks 8.10.0 → 8.11.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/v8/cli/index.d.ts +1 -0
- package/dist/v8/cli/index.d.ts.map +1 -1
- package/dist/v8/cli/index.js +1 -0
- package/dist/v8/cli/index.js.map +1 -1
- package/dist/v8/cli/run.d.ts +2 -0
- package/dist/v8/cli/run.d.ts.map +1 -1
- package/dist/v8/cli/run.js +30 -1
- package/dist/v8/cli/run.js.map +1 -1
- package/dist/v8/cli/skills.d.ts +25 -0
- package/dist/v8/cli/skills.d.ts.map +1 -0
- package/dist/v8/cli/skills.js +70 -0
- package/dist/v8/cli/skills.js.map +1 -0
- package/package.json +3 -2
- package/skills/deco-apps/SKILL.md +82 -0
- package/skills/deco-apps/references/algolia.md +51 -0
- package/skills/deco-apps/references/commerce-types.md +132 -0
- package/skills/deco-apps/references/instrumented-fetch.md +144 -0
- package/skills/deco-apps/references/magento.md +55 -0
- package/skills/deco-apps/references/messaging.md +76 -0
- package/skills/deco-apps/references/shopify.md +69 -0
- package/skills/deco-apps/references/vendored-loaders.md +135 -0
- package/skills/deco-apps/references/vtex-cookies-auth.md +146 -0
- package/skills/deco-apps/references/vtex.md +150 -0
- package/skills/deco-apps/references/wake.md +75 -0
- package/skills/deco-cms-schema/SKILL.md +80 -0
- package/skills/deco-cms-schema/references/annotations.md +147 -0
- package/skills/deco-cms-schema/references/content-hygiene.md +91 -0
- package/skills/deco-cms-schema/references/formats-and-widgets.md +112 -0
- package/skills/deco-cms-schema/references/shapes-that-break-the-form.md +165 -0
- package/skills/deco-cms-schema/references/types-to-fields.md +112 -0
- package/skills/deco-go-live/SKILL.md +127 -0
- package/skills/deco-go-live/references/content-releases.md +90 -0
- package/skills/deco-go-live/references/process.md +106 -0
- package/skills/deco-go-live/references/proxy-headers-checkout.md +139 -0
- package/skills/deco-go-live/references/qa-checklist-template.md +150 -0
- package/skills/deco-go-live/references/qa-inventory.md +120 -0
- package/skills/deco-go-live/references/react-spa.md +183 -0
- package/skills/deco-go-live/references/seo-analytics.md +114 -0
- package/skills/deco-go-live/references/traffic-ramp.md +87 -0
- package/skills/deco-go-live/references/worker-runtime.md +93 -0
- package/skills/deco-go-live/scripts/preflight.sh +221 -0
- package/skills/deco-images-media/SKILL.md +64 -0
- package/skills/deco-images-media/references/asset-upload.md +191 -0
- package/skills/deco-images-media/references/components-per-binding.md +167 -0
- package/skills/deco-images-media/references/providers-and-cdn.md +145 -0
- package/skills/deco-images-media/references/quality-and-lcp.md +93 -0
- package/skills/deco-images-media/references/troubleshooting.md +147 -0
- package/skills/deco-images-media/references/video.md +122 -0
- package/skills/deco-make-editable/SKILL.md +94 -0
- package/skills/deco-make-editable/references/a11y-and-e2e.md +104 -0
- package/skills/deco-make-editable/references/content-shapes.md +198 -0
- package/skills/deco-make-editable/references/from-figma.md +110 -0
- package/skills/deco-make-editable/references/i18n-fields.md +112 -0
- package/skills/deco-make-editable/references/inventory.md +79 -0
- package/skills/deco-make-editable/references/pixel-parity.md +175 -0
- package/skills/deco-make-editable/references/seeding-content.md +119 -0
- package/skills/deco-nextjs-site/SKILL.md +74 -0
- package/skills/deco-nextjs-site/references/caching.md +116 -0
- package/skills/deco-nextjs-site/references/metadata-seo.md +100 -0
- package/skills/deco-nextjs-site/references/proxy-and-drafts.md +177 -0
- package/skills/deco-nextjs-site/references/rendering.md +171 -0
- package/skills/deco-nextjs-site/references/setup.md +190 -0
- package/skills/deco-nextjs-site/references/studio-bridge.md +130 -0
- package/skills/deco-site-authoring/SKILL.md +75 -0
- package/skills/deco-site-authoring/references/lazy-blocks.md +155 -0
- package/skills/deco-site-authoring/references/loaders.md +192 -0
- package/skills/deco-site-authoring/references/pages.md +156 -0
- package/skills/deco-site-authoring/references/review-before-publish.md +95 -0
- package/skills/deco-site-authoring/references/sections.md +158 -0
- package/skills/deco-site-authoring/references/seo.md +116 -0
- package/skills/deco-site-workflow/SKILL.md +92 -0
- package/skills/deco-site-workflow/references/check.md +116 -0
- package/skills/deco-site-workflow/references/cli-reference.md +104 -0
- package/skills/deco-site-workflow/references/content-layout.md +93 -0
- package/skills/deco-site-workflow/references/content-sync.md +146 -0
- package/skills/deco-site-workflow/references/delivery.md +51 -0
- package/skills/deco-site-workflow/references/deploy.md +87 -0
- package/skills/deco-site-workflow/references/schema.md +173 -0
- package/skills/deco-site-workflow/references/serve-and-studio.md +138 -0
- package/skills/deco-storefront-caching/SKILL.md +67 -0
- package/skills/deco-storefront-caching/references/cache-keys.md +129 -0
- package/skills/deco-storefront-caching/references/case-study.md +82 -0
- package/skills/deco-storefront-caching/references/egress-traps.md +153 -0
- package/skills/deco-storefront-caching/references/nextjs.md +60 -0
- package/skills/deco-storefront-caching/references/perf-guardrails-e2e.md +123 -0
- package/skills/deco-storefront-caching/references/verification.md +136 -0
- package/skills/deco-storefront-caching/references/worker-page-cache.md +160 -0
- package/skills/deco-storefront-caching/scripts/html-anatomy.mjs +97 -0
- package/skills/deco-storefront-performance/SKILL.md +81 -0
- package/skills/deco-storefront-performance/references/cls-third-party.md +90 -0
- package/skills/deco-storefront-performance/references/hydration.md +116 -0
- package/skills/deco-storefront-performance/references/loaders-n-plus-1.md +107 -0
- package/skills/deco-storefront-performance/references/navigation-ux.md +130 -0
- package/skills/deco-storefront-performance/references/payload-trim.md +163 -0
- package/skills/deco-storefront-performance/references/render-location.md +152 -0
- package/skills/deco-storefront-performance/references/request-dedupe.md +147 -0
- package/skills/deco-storefront-performance/references/trace-reading.md +79 -0
- package/skills/deco-storefront-performance/references/worker-memory.md +176 -0
- package/skills/deco-tanstack-site/SKILL.md +68 -0
- package/skills/deco-tanstack-site/references/document-and-security.md +155 -0
- package/skills/deco-tanstack-site/references/router-and-navigation.md +137 -0
- package/skills/deco-tanstack-site/references/routes-and-pages.md +183 -0
- package/skills/deco-tanstack-site/references/server-functions.md +123 -0
- package/skills/deco-tanstack-site/references/setup.md +153 -0
- package/skills/deco-tanstack-site/references/worker-entry.md +152 -0
- package/skills/deco-v7-to-v8-migration/SKILL.md +122 -0
- package/skills/deco-v7-to-v8-migration/references/caching-and-privacy.md +10 -0
- package/skills/deco-v7-to-v8-migration/references/content.md +25 -0
- package/skills/deco-v7-to-v8-migration/references/editor-forms.md +27 -0
- package/skills/deco-v7-to-v8-migration/references/faststore.md +40 -0
- package/skills/deco-v7-to-v8-migration/references/framework-code.md +53 -0
- package/skills/deco-v7-to-v8-migration/references/hosted-releases.md +16 -0
- package/skills/deco-v7-to-v8-migration/references/import-map.md +81 -0
- package/skills/deco-v7-to-v8-migration/references/legacy-names.md +33 -0
- package/skills/deco-v7-to-v8-migration/references/manual-steps.md +10 -0
- package/skills/deco-v7-to-v8-migration/references/native-apps.md +43 -0
- package/skills/deco-v7-to-v8-migration/references/nextjs.md +19 -0
- package/skills/deco-v7-to-v8-migration/references/parity.md +66 -0
- package/skills/deco-v7-to-v8-migration/references/rendering.md +13 -0
- package/skills/deco-v7-to-v8-migration/references/running-the-script.md +29 -0
- package/skills/deco-v7-to-v8-migration/references/script-steps.md +13 -0
- package/skills/deco-v7-to-v8-migration/references/server-functions.md +15 -0
- package/skills/deco-v7-to-v8-migration/references/sibling-port.md +11 -0
- package/skills/deco-v7-to-v8-migration/references/site-code.md +15 -0
- package/skills/deco-v7-to-v8-migration/references/telemetry.md +10 -0
- package/skills/deco-v7-to-v8-migration/references/verify.md +20 -0
- package/skills/deco-v7-to-v8-migration/scripts/apps.ts +297 -0
- package/skills/deco-v7-to-v8-migration/scripts/asyncRendering.ts +73 -0
- package/skills/deco-v7-to-v8-migration/scripts/blockMap.ts +584 -0
- package/skills/deco-v7-to-v8-migration/scripts/ciSchemaCheck.ts +145 -0
- package/skills/deco-v7-to-v8-migration/scripts/compat.ts +357 -0
- package/skills/deco-v7-to-v8-migration/scripts/content.ts +121 -0
- package/skills/deco-v7-to-v8-migration/scripts/experiments.ts +81 -0
- package/skills/deco-v7-to-v8-migration/scripts/framework.ts +61 -0
- package/skills/deco-v7-to-v8-migration/scripts/imageCopy.ts +276 -0
- package/skills/deco-v7-to-v8-migration/scripts/imageModule.ts +285 -0
- package/skills/deco-v7-to-v8-migration/scripts/imports.ts +942 -0
- package/skills/deco-v7-to-v8-migration/scripts/invoke.ts +624 -0
- package/skills/deco-v7-to-v8-migration/scripts/legacyNames.ts +45 -0
- package/skills/deco-v7-to-v8-migration/scripts/main.ts +59 -0
- package/skills/deco-v7-to-v8-migration/scripts/matchers.ts +41 -0
- package/skills/deco-v7-to-v8-migration/scripts/migrate.ts +176 -0
- package/skills/deco-v7-to-v8-migration/scripts/redirects.ts +455 -0
- package/skills/deco-v7-to-v8-migration/scripts/report.ts +50 -0
- package/skills/deco-v7-to-v8-migration/scripts/scaffold.ts +1119 -0
- package/skills/deco-v7-to-v8-migration/scripts/secrets.ts +35 -0
- package/skills/deco-v7-to-v8-migration/scripts/sectionLoaders.ts +216 -0
- package/skills/deco-v7-to-v8-migration/scripts/siteSettings.ts +261 -0
- package/skills/deco-v7-to-v8-migration/scripts/stubs.ts +388 -0
- package/skills/deco-v7-to-v8-migration/scripts/tsconfig.json +7 -0
- package/skills/deco-v7-to-v8-migration/scripts/vendor.ts +249 -0
- package/skills/deco-v7-to-v8-migration/scripts/vtexInvoke.ts +240 -0
- package/skills/deco-v7-to-v8-migration/scripts/walk.ts +30 -0
- package/skills/deco-variants/SKILL.md +57 -0
- package/skills/deco-variants/references/caching-variants.md +63 -0
- package/skills/deco-variants/references/custom-matchers.md +83 -0
- package/skills/deco-variants/references/draft-preview.md +59 -0
- package/skills/deco-variants/references/experiments-and-campaigns.md +104 -0
- package/skills/deco-variants/references/multivariate.md +85 -0
- package/skills/deco-variants/references/v7-matchers.md +71 -0
- package/src/v8/cli/index.ts +1 -0
- package/src/v8/cli/run.ts +35 -1
- package/src/v8/cli/skills.ts +91 -0
|
@@ -0,0 +1,114 @@
|
|
|
1
|
+
# SEO, analytics and search parity
|
|
2
|
+
|
|
3
|
+
Analytics and SEO break **silently** at cutover: no error, no 5xx, just a
|
|
4
|
+
lower number in a dashboard days later. Compare with the old site, not with
|
|
5
|
+
expectations. On-page SEO (titles, canonical, JSON-LD) is written in
|
|
6
|
+
**deco-site-authoring**; this file is the go-live comparison.
|
|
7
|
+
|
|
8
|
+
## Tag manager timing
|
|
9
|
+
|
|
10
|
+
**What happened:** a performance change loaded the tag manager only on the
|
|
11
|
+
first user gesture. Shoppers reached checkout without the cookies its tags set
|
|
12
|
+
(an A/B tool, consent, affiliates, about 15 ad platforms). Orders per visitor
|
|
13
|
+
fell from 0.51% to 0.41%: **about 20% of orders**. Even ungated, the snippet
|
|
14
|
+
sat at 68% of the HTML and started at 2.2 to 2.7 s.
|
|
15
|
+
|
|
16
|
+
- Load the tag manager from `<head>`, as the old site did, with no gesture or idle gate. Accept the lab-score cost unless a conversion test says otherwise.
|
|
17
|
+
- Don't load the same script twice (eagerly and from a component).
|
|
18
|
+
- SPA: your own page-view event must fire again on client navigation. `DecoDocument` ships v7's `DECO.events` bus and `dataLayer`, and an observer that dispatches the events elements declare with `data-event` (on view, or on click with `data-event-trigger="click"`); it watches the DOM with a `MutationObserver`, so elements a navigation adds are covered.
|
|
19
|
+
- Send tracker payloads in the format the old site used. On one store `add_to_cart` was dropped silently (1 of 587 buyers tracked, against 635 of 679 before).
|
|
20
|
+
|
|
21
|
+
```bash
|
|
22
|
+
grep -rnE "requestIdleCallback|first.?interaction|pointerdown|onFirstGesture" src | grep -iE "gtm|tag|analytics"
|
|
23
|
+
curl -s "$CANDIDATE/" | grep -o "googletagmanager.com/gtm.js[^\"']*" | head -1
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
🧪 Playwright with no gesture: the tag-manager script is requested within
|
|
27
|
+
about 500 ms of the first byte, as on the old site. After the same journey on
|
|
28
|
+
both stacks, compare `document.cookie` names at checkout entry.
|
|
29
|
+
|
|
30
|
+
## Vendors that stop silently
|
|
31
|
+
|
|
32
|
+
| What happened | Fix |
|
|
33
|
+
|---|---|
|
|
34
|
+
| the analytics section was never rendered after the port (two stores) | render the tag manager in the root document; its `<noscript>` right after `<body>` |
|
|
35
|
+
| a vendor the old framework mounted on its own sent zero events, and A/B results were lost | mount every vendor explicitly in the root document |
|
|
36
|
+
| a vendor's `defer` script, while the vendor was down, held `DOMContentLoaded` for ~211 s | load third-party scripts `async` |
|
|
37
|
+
| UTMs did not reach the order form's marketing data | read, merge, write before checkout |
|
|
38
|
+
|
|
39
|
+
```bash
|
|
40
|
+
curl -s "$CANDIDATE/" | grep -oE "googletagmanager|<vendor-marker>" | sort | uniq -c
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
The day after go-live, check each vendor's own report against the same day
|
|
44
|
+
last week.
|
|
45
|
+
|
|
46
|
+
## Indexability and status codes
|
|
47
|
+
|
|
48
|
+
- **At ratio 0 the public host served `noindex` and `Disallow: /`** because the old site decided indexability from its own hostname. The v8 split handler sends `x-forwarded-host`; confirm the old site reads it. Check this **before** creating the route ([traffic-ramp.md](./traffic-ramp.md#traps)).
|
|
49
|
+
- Previews are `noindex` on purpose: any request with `?__draft=` (`off` included) or the draft cookie answers `X-Robots-Tag: noindex, nofollow`. A crawler never has the cookie, but a shared preview link does carry `?__draft=`.
|
|
50
|
+
- Soft 404s: a catch-all that renders "not found" with HTTP 200. On TanStack, a route sets the response's status with the `x-page-status` header (`PAGE_STATUS_HEADER`), which the worker turns into the status. A status set while rendering does not reach the response.
|
|
51
|
+
- A loader failure must not be cached as "not found": a page whose loader failed sets `x-deco-degraded` (`DEGRADED_HEADER`), and the example `pageCache` never stores it (**deco-storefront-caching**). Check that yours does the same.
|
|
52
|
+
- Pagination `rel=next/prev` and canonical lost in the port: compare the head of a listing's page 2 on both sides.
|
|
53
|
+
|
|
54
|
+
```bash
|
|
55
|
+
curl -s -A Googlebot "https://$HOST/robots.txt" | head
|
|
56
|
+
curl -s -A Googlebot "https://$HOST/" | grep -io '<meta[^>]*robots[^>]*>'
|
|
57
|
+
curl -sI "https://$HOST/" | grep -i x-robots-tag # nothing on a published page
|
|
58
|
+
for p in /category-that-does-not-exist /product-that-does-not-exist/p /blog; do
|
|
59
|
+
curl -s -o /dev/null -w "$p %{http_code}\n" "$CANDIDATE$p"; done # compare with the old site
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
## Redirect sweep
|
|
63
|
+
|
|
64
|
+
On v8 the routed redirects are the rules of the one saved block of type
|
|
65
|
+
`redirects` (`Redirects` by convention). The worker answers them before any
|
|
66
|
+
route. Rules from the old site behave differently in a few places:
|
|
67
|
+
|
|
68
|
+
- **Earlier rule wins.** For two rules with the same `from` (or two templates of one shape), routing keeps the earlier one. `deco check` does not flag duplicates inside the redirects block (it reports conflicts only between separate `redirect` blocks), so dedupe the list yourself. A CSV that relied on "last one wins" changes destinations; on one store reordering changed 88 of them.
|
|
69
|
+
- **Self-loops are dropped.** A rule whose `to` is the path its `from` matches is ignored.
|
|
70
|
+
- **Query-scoped sources match exactly.** `from: "/shoes?map=c"` matches only that exact query string and wins over a path-only `/shoes`.
|
|
71
|
+
- **The visitor's query string is carried over** unless the rule sets `discardQueryParameters`, so `gclid` survives.
|
|
72
|
+
- **A full URL in `from`** (`https://…`) never matches a request path. Rewrite it as a path or drop it.
|
|
73
|
+
- **Status:** `permanent: true` is 301, otherwise 307; `status` (301, 302, 307 or 308) wins.
|
|
74
|
+
- **Old block types are not routed.** `deco check` warns about v7 redirect blocks (`website/loaders/redirect.ts`, `website/loaders/redirects.ts`), per-rule `redirect` blocks and a second `redirects` block. Fold them into the one block.
|
|
75
|
+
|
|
76
|
+
```bash
|
|
77
|
+
deco check 2>&1 | grep -iE "redirect" # leftover v7 or extra redirect blocks
|
|
78
|
+
jq -r '.redirects[] | (.from // .redirect.from)' .deco/blocks/Redirects.json | sort | uniq -d # duplicate sources
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
Then sweep **every** rule against the old site in production (status and
|
|
82
|
+
final `Location`), not a sample:
|
|
83
|
+
|
|
84
|
+
```bash
|
|
85
|
+
jq -r '.. | objects | select(has("from") and has("to")) | .from' .deco/blocks/Redirects.json \
|
|
86
|
+
| grep -vE ':|\*' | while read -r from; do
|
|
87
|
+
a=$(curl -s -o /dev/null -w "%{http_code} %{redirect_url}" "$OLD$from")
|
|
88
|
+
b=$(curl -s -o /dev/null -w "%{http_code} %{redirect_url}" "$CANDIDATE$from")
|
|
89
|
+
[ "${a/$OLD/}" = "${b/$CANDIDATE/}" ] || echo "DIFF $from | $a | $b"
|
|
90
|
+
done
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
(Templates with `:name` or `*` are skipped by the `grep`; test a few by hand.)
|
|
94
|
+
|
|
95
|
+
## Sitemaps
|
|
96
|
+
|
|
97
|
+
- The old framework's sitemap handlers do not exist on v8. Serve the sitemap from a real route, or from `createDecoWorker({ routes })`. A static `public/sitemap.xml` left in the repo masks a missing route.
|
|
98
|
+
- Stream sitemap responses. `.text()` on the whole XML ran the worker out of memory on two stores.
|
|
99
|
+
|
|
100
|
+
```bash
|
|
101
|
+
curl -s "$CANDIDATE/sitemap.xml" | grep -o "<loc>[^<]*" | sed 's/<loc>//' | head -200 | while read -r u; do
|
|
102
|
+
curl -s -o /dev/null -w "%{http_code} $u\n" "$u"; done | grep -v "^200"
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
## Search and listing behavior
|
|
106
|
+
|
|
107
|
+
From one store's fixes after launch:
|
|
108
|
+
|
|
109
|
+
- A facet change must **delete `page`** and keep `q`, `sort` and other params. Filtering from page 2 returned 0 results.
|
|
110
|
+
- "Did you mean" only on a confirmed zero total of an unfiltered, first-page text search. Never rewrite filtered URLs.
|
|
111
|
+
- Autocomplete must query the **typed term**, and fall back to the top suggestion only when it is empty.
|
|
112
|
+
- Some search APIs reject large page sizes (one returned 400 above 50). Batch SKU lists, and filter out missing products after sorting: one missing SKU broke a whole wishlist.
|
|
113
|
+
- Total counts that include out-of-stock items while the grid shows only in-stock ones confuse pagination.
|
|
114
|
+
- Empty CMS rules render empty boxes. Guard empty text in code.
|
|
@@ -0,0 +1,87 @@
|
|
|
1
|
+
# Traffic ramp: splitting the host with the old site
|
|
2
|
+
|
|
3
|
+
During the ramp the new worker takes every request on the production host and
|
|
4
|
+
sends a share of visitors to the old origin. On a TanStack site this is
|
|
5
|
+
`abTestingRoutes` from `@decocms/compat-v7/tanstack/worker`, v7's
|
|
6
|
+
`withABTesting` as a `routes` handler for `createDecoWorker`.
|
|
7
|
+
|
|
8
|
+
```ts
|
|
9
|
+
// src/worker-entry.ts
|
|
10
|
+
import { abTestingRoutes } from "@decocms/compat-v7/tanstack/worker";
|
|
11
|
+
|
|
12
|
+
const abTesting = abTestingRoutes({
|
|
13
|
+
worker: () => worker,
|
|
14
|
+
kvBinding: "SITES_KV", // the default
|
|
15
|
+
shouldBypassAB: (_request, url) => isNewSiteOnly(url.pathname),
|
|
16
|
+
});
|
|
17
|
+
|
|
18
|
+
const worker = createDecoWorker({
|
|
19
|
+
// …
|
|
20
|
+
routes: async (request, env, ctx) => (await abTesting(request, env, ctx)) ?? siteRoutes(request),
|
|
21
|
+
});
|
|
22
|
+
export default worker;
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
## How a visitor gets a bucket
|
|
26
|
+
|
|
27
|
+
- The config is a KV entry under the request's **hostname**: `{ workerName, fallbackOrigin, abTest: { ratio } }`, with `ratio` from 0 to 1. Without the binding, without an entry for the host, or without `fallbackOrigin`, the handler returns `null` and the worker serves everyone.
|
|
28
|
+
- The bucket comes from, in order: the `?_deco_bucket=worker|fallback` override; the `_deco_bucket=<bucket>:<ratio %>` cookie, if it was set under the current ratio; the FNV-1a hash of `cf-connecting-ip` against the ratio (a random draw without that header).
|
|
29
|
+
- Every answer that goes through the split carries `x-deco-bucket` (a bypassed request does not). The cookie is set again when the bucket or the ratio changed, so changing the ratio re-draws everyone.
|
|
30
|
+
- The "worker" bucket is the worker called back, so it goes on to the site's other routes, its page cache and the page. If that call throws and `circuitBreaker` is on (the default), the visitor gets the old origin, tagged `fallback`.
|
|
31
|
+
- The "fallback" bucket gets `proxyToFallback`: the request goes to `fallbackOrigin` with `x-forwarded-host` set to the public host, redirects are not followed, and the old hostname is rewritten back to the public one in `Set-Cookie` domains, `Location`, and the text of 2xx bodies (streamed).
|
|
32
|
+
|
|
33
|
+
## Traps
|
|
34
|
+
|
|
35
|
+
**The worker answers some paths before the split.** `createDecoWorker` runs,
|
|
36
|
+
in this order: `/deco/_liveness`; a 404 for v7's admin paths (`/deco/*`,
|
|
37
|
+
`/live/*`, `/.decofile`); the CMS redirects; then `routes`. So:
|
|
38
|
+
|
|
39
|
+
- An old page served from the fallback bucket that calls `/live/invoke/...`, `/deco/render` or any other `/live/*` or `/deco/*` path on the same host gets a 404 from the worker. Those calls never reach the old origin. Test the fallback bucket's interactions (add to cart, partial loads, forms) at 0%, before any visitor is on it.
|
|
40
|
+
- The new site's redirects apply to both buckets. A rule meant for the new URL scheme also redirects visitors on the old site.
|
|
41
|
+
|
|
42
|
+
**`shouldBypassAB` reads backwards.** `true` means "serve from this worker,
|
|
43
|
+
skip the draw". Return `true` for routes that exist only on the new site
|
|
44
|
+
(headless login and account routes, the sitemap, the platform proxies the new
|
|
45
|
+
site owns). Leave shared proxies (checkout, `/api`) in the draw unless both
|
|
46
|
+
buckets can use the new site's proxy.
|
|
47
|
+
|
|
48
|
+
**Old-site responses leave like any route response.** The worker adds
|
|
49
|
+
`CDN-Cache-Control: no-store` when the old origin sets none. On an HTML
|
|
50
|
+
response it also adds each of its security headers the old origin did not
|
|
51
|
+
set, including `Cross-Origin-Opener-Policy: same-origin-allow-popups` and a
|
|
52
|
+
`Content-Security-Policy` with a `frame-ancestors` list. Diff the old site's headers through the worker
|
|
53
|
+
against the old site direct ([proxy-headers-checkout.md](./proxy-headers-checkout.md#header-diff-against-the-old-site)).
|
|
54
|
+
|
|
55
|
+
**Indexing at 0%.** The old site may decide `noindex` from its own hostname.
|
|
56
|
+
It receives `x-forwarded-host` with the public host; confirm it honors it.
|
|
57
|
+
Check `robots.txt` and the robots meta on the public host before you create the
|
|
58
|
+
route ([seo-analytics.md](./seo-analytics.md#indexability-and-status-codes)).
|
|
59
|
+
|
|
60
|
+
**Existing proxies.** Checkout, `/api`, media: test each in both buckets. On
|
|
61
|
+
one store the split broke proxies the site already had.
|
|
62
|
+
|
|
63
|
+
## Forcing a bucket
|
|
64
|
+
|
|
65
|
+
```bash
|
|
66
|
+
for b in worker fallback; do
|
|
67
|
+
for p in / /checkout/ /robots.txt /sitemap.xml; do
|
|
68
|
+
curl -s -o /dev/null -D - "https://$HOST$p?_deco_bucket=$b" \
|
|
69
|
+
| tr -d '\r' | awk -v b="$b" -v p="$p" '/^HTTP/{s=$2} tolower($1)=="x-deco-bucket:"{x=$2} END{print b, p, s, x}'
|
|
70
|
+
done
|
|
71
|
+
done
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
The override also sets the cookie, so a browser stays in the forced bucket
|
|
75
|
+
for the next pages. Clear `_deco_bucket` to get a fresh draw.
|
|
76
|
+
|
|
77
|
+
## Rollback
|
|
78
|
+
|
|
79
|
+
Set `abTest.ratio` to `0` in the host's KV entry: every visitor without a
|
|
80
|
+
current cookie draws `fallback`, and old cookies were set under another ratio,
|
|
81
|
+
so they draw again. If the split handler was removed from the code, rollback is
|
|
82
|
+
a code rollback instead; know which one you have.
|
|
83
|
+
|
|
84
|
+
## After 100%
|
|
85
|
+
|
|
86
|
+
Keep the handler at ratio 1 for a few days (a rollback is then one KV write),
|
|
87
|
+
then remove it and the KV entry in a normal deploy.
|
|
@@ -0,0 +1,93 @@
|
|
|
1
|
+
# Worker runtime: memory, shared state, deadlines, observability
|
|
2
|
+
|
|
3
|
+
A Worker isolate has **128 MB**, serves many requests at once, and can be
|
|
4
|
+
recycled at any time. Whatever was fine in a long-lived server process is a
|
|
5
|
+
risk here. These checks apply to a TanStack site behind `createDecoWorker`
|
|
6
|
+
from `@decocms/tanstack/worker`. On Next.js, see **deco-nextjs-site** for the
|
|
7
|
+
runtime it deploys to.
|
|
8
|
+
|
|
9
|
+
## Memory: 128 MB per isolate
|
|
10
|
+
|
|
11
|
+
What filled memory on storefronts that went live:
|
|
12
|
+
|
|
13
|
+
| Symptom | Root cause | Fix |
|
|
14
|
+
|---|---|---|
|
|
15
|
+
| `exceededMemory` at go-live (~147 MB resident) | the whole content (~9.6 MB of JSON, far more once parsed) in the bundle **and** a second copy loaded at runtime | one copy only. On v8, `createCMS({ site })` keeps content out of the bundle |
|
|
16
|
+
| OOM on one landing page | a block asked the commerce API for `count: 100`: an 11 MB response, ~90 MB of objects | cap counts in code (≤ 48) and include the cap in the cache key |
|
|
17
|
+
| OOM on the sitemap (two stores) | `await upstream.text()` and `replaceAll` on the whole XML | stream: `new Response(upstream.body)` or a `TransformStream` |
|
|
18
|
+
| Redirect table in memory (~18k rows) | the table bundled as code | keep it in the redirects block (content), not in a bundled module |
|
|
19
|
+
|
|
20
|
+
What v8 itself holds per isolate: hosted block bodies in an LRU bounded at
|
|
21
|
+
32 MB of JSON text (parsed objects take more), and the release index. Measure
|
|
22
|
+
the rest.
|
|
23
|
+
|
|
24
|
+
```bash
|
|
25
|
+
ls -la dist/server/ 2>/dev/null; find dist -name '*.js' -size +2M 2>/dev/null # anything big in the bundle?
|
|
26
|
+
grep -rnE "\.deco/blocks/[^\"']+\.json|blocks\.gen" src # content bundled into the worker
|
|
27
|
+
grep -rnE "\.text\(\)" src | grep -iE "sitemap|proxy|upstream" # large bodies buffered
|
|
28
|
+
grep -rhoE '"count":\s*[0-9]+' .deco/blocks | sort | uniq -c | sort -rn | head # big counts in content
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
Go-live gate: memory under about 80% of the limit during a load test on the
|
|
32
|
+
candidate. Raising the memory limit hides the cause; find what fills memory.
|
|
33
|
+
|
|
34
|
+
## Module-scope state leaks between users
|
|
35
|
+
|
|
36
|
+
One isolate serves many users at once. One store leaked **personal data**
|
|
37
|
+
because `new QueryClient()` sat at module scope in `src/router.tsx`.
|
|
38
|
+
|
|
39
|
+
```bash
|
|
40
|
+
grep -rn "new QueryClient" src/ # must be inside getRouter(), passed through createDecoRouter({ context })
|
|
41
|
+
grep -rnE "^(export )?(const|let) [a-zA-Z_]+ = new (Map|Set|WeakMap)\(" src/ | grep -v test
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
A module-level `Map` or cache may hold only data that is the same for every
|
|
45
|
+
user. Test with two session cookies against one warm isolate.
|
|
46
|
+
|
|
47
|
+
Workers also refuse random values at module scope ("Disallowed operation
|
|
48
|
+
called within global scope"). Draw them on the first request, as
|
|
49
|
+
`abTestingRoutes` does with its token.
|
|
50
|
+
|
|
51
|
+
## Deadlines on every await
|
|
52
|
+
|
|
53
|
+
Symptom: a 524 after about 100 s with ~1 ms of CPU (`outcome=canceled`).
|
|
54
|
+
|
|
55
|
+
| Cause | Fix |
|
|
56
|
+
|---|---|
|
|
57
|
+
| upstream fetch without a deadline | `createInstrumentedFetch` from `@decocms/blocks/fetch` can retry and break circuits (`retry`, `circuitBreaker`, both off unless set), but has no timeout of its own: pass `signal: AbortSignal.timeout(…)` per call (for example 20 s for data, longer for a proxied checkout) |
|
|
58
|
+
| site cache or KV read that stalls | race it against a short deadline; a timeout is a miss |
|
|
59
|
+
| a module-level single-flight map whose owner request went away | give joiners a deadline and drop the entry past it; keep the owner's work alive with `ctx.waitUntil` |
|
|
60
|
+
| background work that needs `env` | capture what it needs during the request |
|
|
61
|
+
|
|
62
|
+
The framework's own shared content fetches follow these rules: each has 10 s,
|
|
63
|
+
stays alive through the platform's `waitUntil` whoever started it, and a
|
|
64
|
+
request that joins one waits no longer than its deadline (then the next
|
|
65
|
+
request fetches again). The framework does this because on Workers a
|
|
66
|
+
request's I/O can stop with its response, so a fetch another request started
|
|
67
|
+
may never settle. Your own shared maps need the same deadlines.
|
|
68
|
+
|
|
69
|
+
```bash
|
|
70
|
+
grep -n "compatibility_date\|compatibility_flags" wrangler.jsonc
|
|
71
|
+
grep -rnE "AbortSignal\.timeout|signal:" src | wc -l # zero is a finding
|
|
72
|
+
grep -rn "createInstrumentedFetch" src
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
## Observability
|
|
76
|
+
|
|
77
|
+
You cannot see `exceededMemory`, `canceled` or the 524 pattern without it.
|
|
78
|
+
|
|
79
|
+
- [ ] Workers observability on in `wrangler.jsonc` (`"observability": { "enabled": true }`) and `wrangler tail` works against the candidate.
|
|
80
|
+
- [ ] The CMS telemetry on: `createCMS({ site, token })` or a `telemetry.endpoint`. Without either, the request metric and the upstream metric go nowhere ([content-releases.md](./content-releases.md#telemetry)).
|
|
81
|
+
- [ ] `telemetry.resource` sets `service.version` to the commit, so a code rollback is visible.
|
|
82
|
+
|
|
83
|
+
## Framework bumps
|
|
84
|
+
|
|
85
|
+
- Compare memory P50 and P99 before and after **every** `@decocms/*` bump. On v7 one minor bump added 27 MB.
|
|
86
|
+
- Bump all `@decocms/*` packages together, and check that one copy of each is installed (`bun pm ls | grep @decocms`, or your package manager's equivalent). Mixed versions run code the bump was not tested with.
|
|
87
|
+
- Re-run `deco schema` and `deco check` after a bump: the schema generator changes with the CLI.
|
|
88
|
+
|
|
89
|
+
## Portability and CI
|
|
90
|
+
|
|
91
|
+
- Keep platform bindings behind the site's own small interfaces, so the site can move to another runtime if a platform limit is hit.
|
|
92
|
+
- Do not hand out write access to the Worker's dashboard or CI: a commit there can bind another store's namespaces.
|
|
93
|
+
- Know how a content-only change reaches production: with `site`, a publish; without it, a deploy.
|
|
@@ -0,0 +1,221 @@
|
|
|
1
|
+
#!/usr/bin/env bash
|
|
2
|
+
# Read-only go-live preflight for a site on @decocms/blocks 8 (TanStack Start
|
|
3
|
+
# behind createDecoWorker; most repo checks also make sense on Next.js).
|
|
4
|
+
#
|
|
5
|
+
# Usage: preflight.sh <site-repo-dir> [candidate-url] [old-site-url]
|
|
6
|
+
# site-repo-dir the site repo (static checks)
|
|
7
|
+
# candidate-url https://host serving the new site (HTTP checks)
|
|
8
|
+
# old-site-url https://host serving the old site (header diff)
|
|
9
|
+
# Env: CHECKOUT_PATH (default /checkout/)
|
|
10
|
+
#
|
|
11
|
+
# Prints PASS / WARN / FAIL per check and never writes anything. It runs no
|
|
12
|
+
# deco command: run `deco schema --check` and `deco check` yourself.
|
|
13
|
+
# Browser-only checks (marked 🧪 in SKILL.md) are not covered.
|
|
14
|
+
|
|
15
|
+
set -u
|
|
16
|
+
REPO="${1:?usage: preflight.sh <site-repo-dir> [candidate-url] [old-site-url]}"
|
|
17
|
+
CAND="${2:-}"; CAND="${CAND%/}"
|
|
18
|
+
OLD="${3:-}"; OLD="${OLD%/}"
|
|
19
|
+
CHECKOUT="${CHECKOUT_PATH:-/checkout/}"
|
|
20
|
+
UA="Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/139.0 Safari/537.36"
|
|
21
|
+
|
|
22
|
+
fails=0; warns=0
|
|
23
|
+
pass() { printf ' \033[32mPASS\033[0m %s\n' "$1"; }
|
|
24
|
+
warn() { printf ' \033[33mWARN\033[0m %s\n' "$1"; warns=$((warns + 1)); }
|
|
25
|
+
fail() { printf ' \033[31mFAIL\033[0m %s\n' "$1"; fails=$((fails + 1)); }
|
|
26
|
+
show() { sed 's/^/ /' | head -n "${1:-5}"; }
|
|
27
|
+
section() { printf '\n== %s\n' "$1"; }
|
|
28
|
+
|
|
29
|
+
SRC="$REPO/src"
|
|
30
|
+
[ -d "$SRC" ] || SRC="$REPO"
|
|
31
|
+
# grep the site's source, skipping generated, vendored and test files and comment lines
|
|
32
|
+
g() {
|
|
33
|
+
grep -rnE "$@" --include='*.ts' --include='*.tsx' --include='*.js' --include='*.mjs' \
|
|
34
|
+
--exclude-dir=node_modules --exclude-dir=dist --exclude-dir=.deco --exclude-dir=.git \
|
|
35
|
+
--exclude-dir=.output --exclude-dir=.next \
|
|
36
|
+
--exclude='*.gen.ts' --exclude='*.test.*' --exclude='*.spec.*' "$SRC" 2>/dev/null |
|
|
37
|
+
grep -vE '^[^:]+:[0-9]+:\s*(//|\*|/\*)'
|
|
38
|
+
}
|
|
39
|
+
|
|
40
|
+
WRANGLER=""
|
|
41
|
+
for f in wrangler.jsonc wrangler.json wrangler.toml; do [ -f "$REPO/$f" ] && WRANGLER="$REPO/$f" && break; done
|
|
42
|
+
|
|
43
|
+
section "Packages and content (references/content-releases.md)"
|
|
44
|
+
|
|
45
|
+
if [ -f "$REPO/package.json" ]; then
|
|
46
|
+
v=$(grep -oE '"@decocms/blocks"\s*:\s*"[^"]+"' "$REPO/package.json" | head -1)
|
|
47
|
+
case "$v" in
|
|
48
|
+
*'"^8'* | *'"8'* | *'"~8'* | *'workspace:'*) pass "@decocms/blocks: ${v#*: }" ;;
|
|
49
|
+
"") fail "@decocms/blocks is not a dependency" ;;
|
|
50
|
+
*) warn "@decocms/blocks ${v#*: }: this skill is for v8" ;;
|
|
51
|
+
esac
|
|
52
|
+
fi
|
|
53
|
+
|
|
54
|
+
hits=$(g 'createDecoWorkerEntry|@decocms/start|registerSections|registerCachePattern|createCachedLoader|/deco/invoke|DECO_FAST_DEPLOY')
|
|
55
|
+
if [ -z "$hits" ]; then pass "no v7 runtime APIs in source"
|
|
56
|
+
else fail "v7 APIs left in source (see deco-v7-to-v8-migration)"; echo "$hits" | show 8; fi
|
|
57
|
+
|
|
58
|
+
if [ -f "$REPO/.deco/schema.gen.json" ]; then
|
|
59
|
+
if grep -qE '"blocksMajor"\s*:\s*8' "$REPO/.deco/schema.gen.json"; then pass 'schema.gen.json has "blocksMajor": 8'
|
|
60
|
+
else fail 'schema.gen.json lacks "blocksMajor": 8: Studio edits the site as v7 and deco check fails'; fi
|
|
61
|
+
else warn "no .deco/schema.gen.json: run deco schema and commit it"; fi
|
|
62
|
+
|
|
63
|
+
files=$(g 'createCMS(<[^>]*>)?\(' | cut -d: -f1 | sort -u)
|
|
64
|
+
if [ -z "$files" ]; then warn "createCMS not found in source"
|
|
65
|
+
else
|
|
66
|
+
# the createCMS({ ... }) call itself, comments dropped
|
|
67
|
+
call=$(for f in $files; do awk '/createCMS(<[^>]*>)?\(/{f=1} f{sub(/\/\/.*/, ""); print} f&&/\}\)/{f=0}' "$f"; done)
|
|
68
|
+
if echo "$call" | grep -qE '(^|[^A-Za-z_.])site\s*[:,}]'; then pass "createCMS has site: releases come from the CDN"
|
|
69
|
+
else warn "createCMS without site: content is bundled and every content change needs a deploy"; fi
|
|
70
|
+
fi
|
|
71
|
+
|
|
72
|
+
hits=$(g "\.deco/blocks/[^\"']+\.json")
|
|
73
|
+
[ -z "$hits" ] && pass "no direct imports of .deco/blocks/*.json" ||
|
|
74
|
+
{ warn "direct imports of saved blocks: a publish never reaches them"; echo "$hits" | show; }
|
|
75
|
+
|
|
76
|
+
section "Worker runtime (references/worker-runtime.md)"
|
|
77
|
+
|
|
78
|
+
if g 'createDecoWorker(<[^>]*>)?\(' >/dev/null; then pass "createDecoWorker in source"
|
|
79
|
+
else warn "no createDecoWorker in source (fine on Next.js; on TanStack the worker features are missing)"; fi
|
|
80
|
+
|
|
81
|
+
hits=$(g 'new QueryClient\(')
|
|
82
|
+
if [ -z "$hits" ]; then pass "no QueryClient"
|
|
83
|
+
elif echo "$hits" | grep -q 'router.tsx' && awk '/getRouter/{f=1} f&&/new QueryClient\(/{found=1} END{exit !found}' "$SRC/router.tsx" 2>/dev/null; then
|
|
84
|
+
pass "new QueryClient() appears after getRouter in router.tsx (confirm it is not at module scope)"
|
|
85
|
+
else fail "new QueryClient() possibly at module scope: it leaks data between users"; echo "$hits" | show; fi
|
|
86
|
+
|
|
87
|
+
hits=$(g '^(export )?(const|let) [A-Za-z_]+ = new (Map|Set)\(')
|
|
88
|
+
[ -z "$hits" ] && pass "no module-level Map/Set" ||
|
|
89
|
+
{ warn "module-level Map/Set: must hold only data that is the same for every user, with deadlines on shared promises"; echo "$hits" | show; }
|
|
90
|
+
|
|
91
|
+
if [ -n "$WRANGLER" ]; then
|
|
92
|
+
if grep -qE '"?observability"?' "$WRANGLER" && grep -A2 -E '"?observability"?' "$WRANGLER" | grep -q 'true'; then
|
|
93
|
+
pass "Workers observability enabled"
|
|
94
|
+
else warn "observability not enabled in $(basename "$WRANGLER"): exceededMemory and canceled are invisible"; fi
|
|
95
|
+
mem=$(grep -oE '"?memory_mb"?\s*[:=]\s*[0-9]+' "$WRANGLER")
|
|
96
|
+
[ -n "$mem" ] && warn "custom memory limit ($mem): a stopgap; find what fills memory"
|
|
97
|
+
fi
|
|
98
|
+
|
|
99
|
+
hits=$(g '\.text\(\)' | grep -iE 'sitemap|proxy|upstream|checkout')
|
|
100
|
+
[ -z "$hits" ] && pass "no .text() buffering in sitemap/proxy code" ||
|
|
101
|
+
{ warn "large responses buffered with .text(): stream them"; echo "$hits" | show; }
|
|
102
|
+
|
|
103
|
+
n=$(g 'AbortSignal\.timeout' | wc -l | tr -d ' ')
|
|
104
|
+
[ "$n" = "0" ] && warn "no AbortSignal.timeout in source: upstream fetches have no deadline" || pass "$n upstream deadline(s) (AbortSignal.timeout)"
|
|
105
|
+
|
|
106
|
+
if g 'telemetry\s*:|token\s*:' | grep -q .; then pass "telemetry options present (confirm token or endpoint is set in production)"
|
|
107
|
+
else warn "no telemetry option seen: request and upstream metrics go nowhere"; fi
|
|
108
|
+
|
|
109
|
+
section "Cache (deco-storefront-caching)"
|
|
110
|
+
|
|
111
|
+
if g 'pageCache' >/dev/null; then pass "pageCache passed to the worker"
|
|
112
|
+
else warn "no pageCache: every request renders (fine only if a CDN in front caches pages)"; fi
|
|
113
|
+
|
|
114
|
+
hits=$(g '\.catch\(\(\)\s*=>\s*(null|undefined|\[\])\)' | grep -viE 'cache\.(match|put|delete)')
|
|
115
|
+
[ -z "$hits" ] && pass "no errors swallowed to null" ||
|
|
116
|
+
{ warn "errors swallowed to null: may be cached as not-found or out-of-stock (use DEGRADED_HEADER)"; echo "$hits" | show; }
|
|
117
|
+
|
|
118
|
+
section "Traffic split (references/traffic-ramp.md)"
|
|
119
|
+
if g 'abTestingRoutes' >/dev/null; then
|
|
120
|
+
pass "abTestingRoutes in use: test both buckets with ?_deco_bucket=worker|fallback"
|
|
121
|
+
g 'shouldBypassAB' >/dev/null || warn "no shouldBypassAB: routes only the new site has will be split too"
|
|
122
|
+
else pass "no traffic split handler (skip if the cutover is a straight switch)"; fi
|
|
123
|
+
|
|
124
|
+
section "React / Fresh leftovers (references/react-spa.md)"
|
|
125
|
+
|
|
126
|
+
hits=$(g 'window\.STOREFRONT|window\.addToCart|hx-(post|get|on|trigger)')
|
|
127
|
+
[ -z "$hits" ] && pass "no Fresh global SDK / htmx leftovers" || { fail "Fresh/htmx leftovers"; echo "$hits" | show 10; }
|
|
128
|
+
|
|
129
|
+
hits=$(g 'on[A-Z][a-zA-Z]+=\{useScript')
|
|
130
|
+
[ -z "$hits" ] && pass "no on*={useScript(...)} handlers" || { fail "an event handler receives a string from useScript"; echo "$hits" | show; }
|
|
131
|
+
|
|
132
|
+
n=$(g 'useScript\(|useScriptAsDataURI\(' | cut -d: -f1 | sort -u | wc -l | tr -d ' ')
|
|
133
|
+
[ "$n" = "0" ] || warn "$n file(s) with useScript/useScriptAsDataURI: test each by SPA click; prefer inlineScript"
|
|
134
|
+
|
|
135
|
+
if ls "$REPO"/eslint.config.* "$REPO"/.eslintrc* "$REPO"/biome.json* >/dev/null 2>&1 &&
|
|
136
|
+
grep -qE 'rules-of-hooks|useHookAtTopLevel' "$REPO"/eslint.config.* "$REPO"/.eslintrc* "$REPO"/biome.json* 2>/dev/null; then
|
|
137
|
+
pass "hook-order lint configured"
|
|
138
|
+
else warn "no rules-of-hooks (ESLint) or useHookAtTopLevel (Biome): hooks after an early return cause React #310"; fi
|
|
139
|
+
|
|
140
|
+
g 'preloadError' >/dev/null && pass "stale-chunk handler present" ||
|
|
141
|
+
warn "no vite:preloadError handler: open tabs break after each deploy"
|
|
142
|
+
|
|
143
|
+
if g 'createDecoRouter(<[^>]*>)?\(' >/dev/null && ! g 'defaultPreload' >/dev/null; then
|
|
144
|
+
warn "createDecoRouter with the default defaultPreload \"intent\": measure the payload a hover fetches"
|
|
145
|
+
fi
|
|
146
|
+
|
|
147
|
+
section "Analytics (references/seo-analytics.md)"
|
|
148
|
+
g 'googletagmanager|GoogleTagManager|gtm\.js' >/dev/null && pass "tag manager referenced in source" ||
|
|
149
|
+
warn "tag manager not referenced in source (injected elsewhere? not mounted?)"
|
|
150
|
+
hits=$(g 'requestIdleCallback|firstInteraction|onFirstGesture' | grep -iE 'gtm|tag|analytic')
|
|
151
|
+
[ -z "$hits" ] && pass "no gesture/idle gate around tags" ||
|
|
152
|
+
{ fail "tag manager gated behind a gesture or idle (about 20% of orders lost on one store)"; echo "$hits" | show; }
|
|
153
|
+
[ -f "$REPO/public/sitemap.xml" ] && warn "static public/sitemap.xml: it may mask a missing sitemap route"
|
|
154
|
+
|
|
155
|
+
if [ -n "$CAND" ]; then
|
|
156
|
+
section "HTTP: candidate $CAND"
|
|
157
|
+
cc() { curl -s -m 20 -A "$UA" "$@"; }
|
|
158
|
+
code() { cc -o /dev/null -w '%{http_code}' "$@"; }
|
|
159
|
+
# final status, skipping 103 Early Hints
|
|
160
|
+
status() { grep -E '^HTTP/' | grep -v ' 103' | tail -1 | awk '{print $2}'; }
|
|
161
|
+
|
|
162
|
+
[ "$(cc "$CAND/deco/_liveness")" = "OK" ] && pass "/deco/_liveness → OK (createDecoWorker in front)" ||
|
|
163
|
+
warn "/deco/_liveness did not answer OK (not behind createDecoWorker?)"
|
|
164
|
+
c=$(code "$CAND/live/_meta")
|
|
165
|
+
[ "$c" = "404" ] && pass "v7 admin path /live/_meta → 404" || warn "/live/_meta → $c (expected 404 from the worker)"
|
|
166
|
+
|
|
167
|
+
c=$(code "$CAND/")
|
|
168
|
+
[ "$c" = "200" ] && pass "/ → 200" || fail "/ → $c"
|
|
169
|
+
|
|
170
|
+
# the first-visit visitor cookie, the split cookie and Cloudflare's own are expected
|
|
171
|
+
h=$(cc -o /dev/null -D - "$CAND/" | tr -d '\r')
|
|
172
|
+
sc=$(echo "$h" | grep -i '^set-cookie:' | grep -viE '^set-cookie: *(deco_segment|_deco_bucket|__cf_bm|_cfuvid|cf_clearance)=')
|
|
173
|
+
[ -z "$sc" ] && pass "anonymous / sets no cookie besides deco_segment" ||
|
|
174
|
+
{ warn "anonymous / sets other cookies: a page cache must not store it"; echo "$sc" | cut -c1-90 | show; }
|
|
175
|
+
echo "$h" | grep -qi '^x-robots-tag:.*noindex' && fail "/ sends X-Robots-Tag noindex" || pass "/ has no X-Robots-Tag noindex"
|
|
176
|
+
xc=$(cc -o /dev/null -D - "$CAND/" | tr -d '\r' | grep -iE '^(x-cache|cf-cache-status):' | tr '\n' ' ')
|
|
177
|
+
echo "$xc" | grep -qi 'hit' && pass "2nd request: $xc" || warn "2nd request not a HIT: ${xc:-no cache header}"
|
|
178
|
+
|
|
179
|
+
h=$(cc -o /dev/null -D - "$CAND/?__draft=off" | tr -d '\r')
|
|
180
|
+
if echo "$h" | grep -qi '^cache-control: *max-age=0, no-cache, must-revalidate' && echo "$h" | grep -qi '^x-robots-tag:.*noindex'; then
|
|
181
|
+
pass "?__draft= preview answers no-cache and noindex"
|
|
182
|
+
else warn "?__draft=off did not answer the preview headers (worker not in front?)"; fi
|
|
183
|
+
|
|
184
|
+
h=$(cc -o /dev/null -D - -H 'If-Modified-Since: Tue, 20 Oct 2026 00:00:00 GMT' -H 'If-None-Match: "x"' "$CAND$CHECKOUT" | tr -d '\r')
|
|
185
|
+
c=$(echo "$h" | status)
|
|
186
|
+
if [ "$c" = "304" ]; then fail "$CHECKOUT answers 304 to validators: stale checkout from the browser cache"
|
|
187
|
+
elif echo "$h" | grep -qiE '^(last-modified|etag):'; then warn "$CHECKOUT sends Last-Modified/ETag: the browser will revalidate"
|
|
188
|
+
else pass "$CHECKOUT → $c without validators"; fi
|
|
189
|
+
coop=$(echo "$h" | grep -i '^cross-origin-opener-policy:' | cut -d: -f2- | xargs)
|
|
190
|
+
[ -n "$coop" ] && warn "$CHECKOUT sends Cross-Origin-Opener-Policy: $coop (compare with the old site)"
|
|
191
|
+
|
|
192
|
+
loops=""
|
|
193
|
+
for p in '/%7Bx%7D' '/x%7B' '/%5Bx%5D' '/%7Cx' '/%5Ex' '/%60x'; do
|
|
194
|
+
n=$(cc -o /dev/null -L --max-redirs 10 -w '%{num_redirects}' "$CAND$p")
|
|
195
|
+
[ "${n:-0}" -ge 5 ] && loops="$loops ${p};"
|
|
196
|
+
done
|
|
197
|
+
[ -z "$loops" ] && pass "no redirect loops on encoded paths" || fail "redirect loop (5+ hops) on:$loops"
|
|
198
|
+
|
|
199
|
+
robots=$(cc "$CAND/robots.txt")
|
|
200
|
+
echo "$robots" | grep -qE '^Disallow:\s*/\s*$' && fail "robots.txt has Disallow: /" || pass "robots.txt does not block everything"
|
|
201
|
+
cc "$CAND/" | grep -qiE '<meta[^>]+robots[^>]+noindex' && fail "home has meta noindex" || pass "home indexable"
|
|
202
|
+
cc "$CAND/" | grep -q 'googletagmanager.com' && pass "tag manager in home HTML" || warn "tag manager not in home HTML (host-gated? injected late?)"
|
|
203
|
+
|
|
204
|
+
c=$(code "$CAND/this-page-should-not-exist-$RANDOM")
|
|
205
|
+
[ "$c" = "404" ] && pass "missing page → 404" || fail "missing page → $c (soft 404)"
|
|
206
|
+
|
|
207
|
+
if [ -n "$OLD" ]; then
|
|
208
|
+
section "Header diff: old $OLD × candidate"
|
|
209
|
+
for p in / "$CHECKOUT"; do
|
|
210
|
+
for hdr in cross-origin-opener-policy cross-origin-embedder-policy content-security-policy permissions-policy x-frame-options referrer-policy strict-transport-security; do
|
|
211
|
+
a=$(curl -s -m 20 -A "$UA" -o /dev/null -D - "$OLD$p" | tr -d '\r' | grep -i "^$hdr:" | cut -d: -f2- | xargs)
|
|
212
|
+
b=$(cc -o /dev/null -D - "$CAND$p" | tr -d '\r' | grep -i "^$hdr:" | cut -d: -f2- | xargs)
|
|
213
|
+
[ "$a" = "$b" ] || warn "$p $hdr: old='${a:-<none>}' candidate='${b:-<none>}'"
|
|
214
|
+
done
|
|
215
|
+
done
|
|
216
|
+
pass "header diff done (differences listed above, if any)"
|
|
217
|
+
fi
|
|
218
|
+
fi
|
|
219
|
+
|
|
220
|
+
printf '\n%s FAIL, %s WARN. Also run: deco schema --check && deco check. Browser checks (🧪) are in SKILL.md.\n' "$fails" "$warns"
|
|
221
|
+
[ "$fails" = "0" ]
|
|
@@ -0,0 +1,64 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: deco-images-media
|
|
3
|
+
description: "Images and video on @decocms/blocks 8 sites. Covers @decocms/blocks/image (createImageUrl, ImageProvider, decoCdn with domain, quality, sources and legacyHosts; srcSet and preloadLink), platform providers listed before decoCdn (vtexCatalog and the other @decocms/apps-vtex/image providers, shopifyCdn from @decocms/apps-shopify/image), Image, Picture, Source and ImageUrlProvider from @decocms/tanstack/react, createDecoImageLoader for next/image from @decocms/nextjs/image-loader, quality tiers, sizes and LCP preload, video served by the Deco media host (audio stripped unless ?muted=false) with a plain <video>, and the v8 asset upload endpoint plus the procedure for moving assets to a new host and rewriting their URLs in .deco/blocks. Load it when images are blurry, slow, oversized or broken, when wiring images on a new v8 site, when a video has no sound, or for an asset migration."
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Images and media on v8 sites
|
|
7
|
+
|
|
8
|
+
A v8 site builds **one `ImageUrl`** from a list of providers and hands it to its
|
|
9
|
+
binding. Every resized URL on the site comes from that one function. Most image
|
|
10
|
+
bugs on v8 come from three places: the provider list (a source no provider
|
|
11
|
+
matches is passed through at full size), the quality tier the Deco CDN is asked
|
|
12
|
+
for, and an uploaded source that is smaller than the slot needs.
|
|
13
|
+
|
|
14
|
+
```ts
|
|
15
|
+
// src/imageUrl.ts — one per site
|
|
16
|
+
import { createImageUrl, decoCdn } from "@decocms/blocks/image";
|
|
17
|
+
import { vtexCatalog } from "@decocms/apps-vtex/image";
|
|
18
|
+
|
|
19
|
+
export const imageUrl = createImageUrl({
|
|
20
|
+
providers: [vtexCatalog(), decoCdn({ sources: "all", quality: "high" })],
|
|
21
|
+
});
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
Providers are tried in order. The first one whose `match(src)` is true and whose
|
|
25
|
+
`format` returns a URL wins. Empty `src` gives `""`; `data:` URIs and sources
|
|
26
|
+
no provider matches come back unchanged.
|
|
27
|
+
|
|
28
|
+
## When to load what
|
|
29
|
+
|
|
30
|
+
| Reference | Load it when |
|
|
31
|
+
|---|---|
|
|
32
|
+
| [`providers-and-cdn.md`](./references/providers-and-cdn.md) | Writing `imageUrl`, choosing `decoCdn` options, adding a VTEX or Shopify provider, writing a provider for another platform, CSP `img-src` |
|
|
33
|
+
| [`components-per-binding.md`](./references/components-per-binding.md) | Rendering images: `Image`/`Picture`/`Source` on TanStack, the next/image loader on Next.js, `srcSet`/`preloadLink` anywhere else; image fields in section props |
|
|
34
|
+
| [`quality-and-lcp.md`](./references/quality-and-lcp.md) | Picking quality tiers, per-image quality, `sizes`, preloading the LCP image |
|
|
35
|
+
| [`troubleshooting.md`](./references/troubleshooting.md) | Images are soft, pixelated, too heavy, 404/508, not resized, or shift the layout |
|
|
36
|
+
| [`video.md`](./references/video.md) | A video has no sound, autoplay does not start, or you are adding a video field |
|
|
37
|
+
| [`asset-upload.md`](./references/asset-upload.md) | Uploads from the site editor, or moving assets off an old host and rewriting URLs in `.deco/blocks` |
|
|
38
|
+
|
|
39
|
+
## Rules that hold everywhere
|
|
40
|
+
|
|
41
|
+
- **One `ImageUrl` per site.** v7's `registerImageCdnDomain` and
|
|
42
|
+
`registerImageQuality` are gone. Their values are now `decoCdn({ domain, quality })`.
|
|
43
|
+
- **Platform providers go before `decoCdn`.** A provider with `sources: "all"`
|
|
44
|
+
matches every source, so anything listed after it never runs.
|
|
45
|
+
- **`decoCdn()` with no `sources` only resizes Deco-hosted URLs.** Other hosts
|
|
46
|
+
pass through at full size. The TanStack default (`DECO_IMAGE_URL`) uses
|
|
47
|
+
`sources: "all"`.
|
|
48
|
+
- **Quality on the Deco CDN is a tier name.** It ignores numbers.
|
|
49
|
+
- **Set `width` and `height`** on every image, so the browser reserves the box.
|
|
50
|
+
- **Preload one image per page**, the LCP one. Preloading more images makes them
|
|
51
|
+
compete for bandwidth.
|
|
52
|
+
- **Never send a video through `ImageUrl`.** `decoCdn` builds an `/image?…` URL
|
|
53
|
+
and drops the source's query string, `?muted=false` included.
|
|
54
|
+
|
|
55
|
+
## Related skills
|
|
56
|
+
|
|
57
|
+
- `deco-tanstack-site` and `deco-nextjs-site`: where the binding is wired (root
|
|
58
|
+
document, `next.config`, CSP).
|
|
59
|
+
- `deco-cms-schema`: field annotations and help text editors see.
|
|
60
|
+
- `deco-site-workflow`: `deco pull`, `diff`, `push --draft`, `check`, `publish`.
|
|
61
|
+
- `deco-storefront-performance`: LCP and CLS beyond images.
|
|
62
|
+
- `deco-v7-to-v8-migration`: moving a v7 image helper to `createImageUrl`.
|
|
63
|
+
- `image-optimizer` (decocms/skills): generic HTML image practice (`srcset`,
|
|
64
|
+
`sizes`, `fetchpriority`, formats).
|