@decocms/blocks 8.10.0 โ 8.12.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/index.d.ts +1 -1
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js.map +1 -1
- package/dist/protocol/conformance/blockMetaVectors.json +80 -0
- package/dist/protocol/index.d.ts +5 -2
- package/dist/protocol/index.d.ts.map +1 -1
- package/dist/protocol/index.js +5 -2
- package/dist/protocol/index.js.map +1 -1
- package/dist/v8/blockMeta.d.ts +33 -4
- package/dist/v8/blockMeta.d.ts.map +1 -1
- package/dist/v8/blockMeta.js +70 -13
- package/dist/v8/blockMeta.js.map +1 -1
- 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/dist/v8/client.d.ts +6 -4
- package/dist/v8/client.d.ts.map +1 -1
- package/dist/v8/client.js +26 -70
- package/dist/v8/client.js.map +1 -1
- package/dist/v8/cms.d.ts.map +1 -1
- package/dist/v8/cms.js +1 -2
- package/dist/v8/cms.js.map +1 -1
- package/dist/v8/contentIndex.d.ts +18 -7
- package/dist/v8/contentIndex.d.ts.map +1 -1
- package/dist/v8/contentIndex.js +46 -17
- package/dist/v8/contentIndex.js.map +1 -1
- package/dist/v8/draftChanges.d.ts.map +1 -1
- package/dist/v8/draftChanges.js +4 -1
- package/dist/v8/draftChanges.js.map +1 -1
- package/dist/v8/index.d.ts +1 -1
- package/dist/v8/index.d.ts.map +1 -1
- package/dist/v8/remoteLoader.d.ts +4 -2
- package/dist/v8/remoteLoader.d.ts.map +1 -1
- package/dist/v8/remoteLoader.js +13 -3
- package/dist/v8/remoteLoader.js.map +1 -1
- package/dist/v8/types.d.ts +47 -7
- package/dist/v8/types.d.ts.map +1 -1
- 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 +203 -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 +172 -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 +158 -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 +101 -0
- package/skills/deco-site-workflow/references/check.md +116 -0
- package/skills/deco-site-workflow/references/cli-reference.md +106 -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 +123 -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 +23 -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/checkContentReads.ts +32 -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/contentReads.ts +157 -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 +180 -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/index.ts +1 -1
- package/src/protocol/conformance/blockMetaVectors.json +80 -0
- package/src/protocol/index.ts +8 -1
- package/src/v8/blockMeta.ts +75 -11
- package/src/v8/cli/index.ts +1 -0
- package/src/v8/cli/run.ts +35 -1
- package/src/v8/cli/skills.ts +91 -0
- package/src/v8/client.ts +32 -77
- package/src/v8/cms.ts +1 -2
- package/src/v8/contentIndex.ts +49 -19
- package/src/v8/draftChanges.ts +5 -1
- package/src/v8/index.ts +1 -1
- package/src/v8/remoteLoader.ts +13 -3
- package/src/v8/types.ts +48 -7
|
@@ -0,0 +1,139 @@
|
|
|
1
|
+
# Proxy, headers and checkout
|
|
2
|
+
|
|
3
|
+
The worker sits in front of everything: store pages, a proxied checkout,
|
|
4
|
+
`/api`, media and, during the ramp, the old site. A header the new stack adds
|
|
5
|
+
or a proxy that behaves differently shows up as lost conversion, not as an
|
|
6
|
+
error. Always compare with the old site.
|
|
7
|
+
|
|
8
|
+
On v8 the framework ships no commerce proxy. A proxied checkout is the site's
|
|
9
|
+
own code in `createDecoWorker({ routes })`. What the worker does to every
|
|
10
|
+
response on the way out still applies to it:
|
|
11
|
+
|
|
12
|
+
- On an HTML response, it sets each of its security headers **only when the response has none**: `X-Content-Type-Options`, `Referrer-Policy`, `Permissions-Policy`, `X-XSS-Protection`, `Strict-Transport-Security`, `Cross-Origin-Opener-Policy: same-origin-allow-popups`, and a `Content-Security-Policy`: the site's `csp` option with Studio's origins added, or, with no `csp`, only a `frame-ancestors` listing Studio's origins. So a proxied page that sends no CSP of its own can then be framed only by Studio (no `X-Frame-Options` is sent).
|
|
13
|
+
- It sets `CDN-Cache-Control: no-store` on any response that names none.
|
|
14
|
+
- It keeps one `Set-Cookie` per cookie (name, Domain and Path).
|
|
15
|
+
- A `routes` response gets no `preload` hints.
|
|
16
|
+
|
|
17
|
+
## Header diff against the old site
|
|
18
|
+
|
|
19
|
+
**What happened:** the v7 TanStack worker sent `Cross-Origin-Opener-Policy:
|
|
20
|
+
same-origin-allow-popups` on all HTML; the proxied checkout had none and the
|
|
21
|
+
old Fresh site never sent COOP. Every store โ checkout navigation switched
|
|
22
|
+
browsing-context group: popups lost `window.opener`, `window.name` was wiped,
|
|
23
|
+
and WebKit reset its timing clock. v8 sends the same default.
|
|
24
|
+
|
|
25
|
+
Fix: set the header yourself on the responses that must not carry it. The
|
|
26
|
+
worker never overwrites a header the response already has.
|
|
27
|
+
|
|
28
|
+
```ts
|
|
29
|
+
// in your routes proxy, on the proxied checkout's response
|
|
30
|
+
const out = new Response(upstream.body, upstream);
|
|
31
|
+
out.headers.set("Cross-Origin-Opener-Policy", "unsafe-none");
|
|
32
|
+
return out;
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
For pages the app renders, set it in the route's `headers` (they reach the document response). If the
|
|
36
|
+
old site sent no COOP anywhere, decide it once for the whole site.
|
|
37
|
+
|
|
38
|
+
```bash
|
|
39
|
+
for host in "$OLD" "$CANDIDATE"; do
|
|
40
|
+
for p in / /checkout/; do
|
|
41
|
+
echo "== $host$p"
|
|
42
|
+
curl -sI -A "Mozilla/5.0 Chrome/139" "$host$p" \
|
|
43
|
+
| grep -iE "cross-origin|content-security|permissions-policy|x-frame|referrer-policy|strict-transport"
|
|
44
|
+
done
|
|
45
|
+
done
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
Any header the new stack adds that the old one did not is a parity risk on
|
|
49
|
+
same-origin navigations to proxied pages. The CSP is also the site's: pass it
|
|
50
|
+
as `createDecoWorker({ csp: { enforce, reportOnly, frameAncestors } })`
|
|
51
|
+
(**deco-tanstack-site**). Start with `reportOnly` if the old site had none.
|
|
52
|
+
|
|
53
|
+
## Checkout HTML, 304 and bfcache
|
|
54
|
+
|
|
55
|
+
**What happened (two rounds):**
|
|
56
|
+
|
|
57
|
+
1. A proxy forced `private, no-store` on the checkout HTML, so it was never restored from bfcache. "Back" reloaded in 3 to 10 s, lost the coupon or card, and fired the tag-manager steps again.
|
|
58
|
+
2. Relaxing it to `private, no-cache, max-age=0, must-revalidate` made the browser store the HTML **with the platform's `Last-Modified`**. The next visit sent `If-Modified-Since`, the proxy passed it on, the platform answered 304, and the browser rendered a stale checkout. Anonymous conversion dropped from 28.8% to 23.8%.
|
|
59
|
+
|
|
60
|
+
Fix: on `GET` of the checkout paths, strip `If-Modified-Since` and
|
|
61
|
+
`If-None-Match` before proxying, and delete `Last-Modified` and `ETag` from the
|
|
62
|
+
checkout HTML. Keep `CDN-Cache-Control: no-store` (the worker's default).
|
|
63
|
+
|
|
64
|
+
```bash
|
|
65
|
+
curl -sD- -o /dev/null -A "Mozilla/5.0 Chrome/139" \
|
|
66
|
+
-H "If-Modified-Since: Tue, 20 Oct 2026 00:00:00 GMT" "$CANDIDATE/checkout/" \
|
|
67
|
+
| grep -iE "^HTTP|last-modified|etag|cache-control"
|
|
68
|
+
# expect 200, no Last-Modified, no ETag
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
๐งช bfcache: DevTools โ Application โ Back/forward cache on the checkout, **on
|
|
72
|
+
a deployed preview**. A dev server's proxy may bypass the worker. In the
|
|
73
|
+
browser, `performance.getEntriesByType('navigation')[0].transferSize` of about
|
|
74
|
+
300 bytes means a 304 was reused.
|
|
75
|
+
|
|
76
|
+
Large proxied bodies: stream them (`new Response(upstream.body, upstream)`);
|
|
77
|
+
never `await upstream.text()` on a whole page ([worker-runtime.md](./worker-runtime.md#memory-128-mb-per-isolate)).
|
|
78
|
+
|
|
79
|
+
## Third-party checkout scripts
|
|
80
|
+
|
|
81
|
+
**What happened:** an inline shim fixed a JS error in a store's custom
|
|
82
|
+
checkout script. Unblocking that code path made a broken call post
|
|
83
|
+
`marketingData` and **remove the coupon**, and an order-form patch made a
|
|
84
|
+
payment guard swallow "place order". The old site never reached that code,
|
|
85
|
+
because the error stopped it first.
|
|
86
|
+
|
|
87
|
+
- Errors that also happen on the old site may be load-bearing. In checkout, parity beats correctness.
|
|
88
|
+
- Byte-compare the proxied checkout HTML, old against new, and list every injected inline script. Put each injection behind a flag you can turn off.
|
|
89
|
+
- Measure payment-method pick โ transaction on both stacks before blaming the migration.
|
|
90
|
+
- A third party that posts the order form's marketing data replaces the whole object. Read, merge, then write, so UTMs and your own tags survive.
|
|
91
|
+
- Never `<link rel=prefetch>` a third-party script that the next page loads with `crossorigin`. A cache mismatch stopped one checkout from mounting for about 2 hours.
|
|
92
|
+
- Store cart and checkout must share the same order-form cookie.
|
|
93
|
+
|
|
94
|
+
```bash
|
|
95
|
+
strip() { sed -E 's/[0-9a-f]{8,}//g; s/[0-9]{10,}//g'; }
|
|
96
|
+
diff <(curl -s "$OLD/checkout/" | strip) <(curl -s "$CANDIDATE/checkout/" | strip) | head -50
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
## Bugs that only exist on the real host
|
|
100
|
+
|
|
101
|
+
Previews on a `workers.dev` or preview domain miss them.
|
|
102
|
+
|
|
103
|
+
| Symptom | Root cause |
|
|
104
|
+
|---|---|
|
|
105
|
+
| server-side calls to `https://www.<domain>` hit the old site | a Worker's fetch to its own public hostname does not run the Worker again; it goes to the zone's origin |
|
|
106
|
+
| tags or analytics behave differently in production | tags gated on the hostname |
|
|
107
|
+
| a Studio draft link shows the release on the real host | once a release carries `previewHosts` (Studio writes them), drafts preview only on those hosts plus `createCMS({ preview: { hosts } })`; any other host gets the release |
|
|
108
|
+
|
|
109
|
+
```bash
|
|
110
|
+
grep -rn "https://www\.<domain>" src # server-side self-fetch, host checks
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
For every hit of the domain in `src/`, ask: what changes when the host **is**
|
|
114
|
+
this one? Test with the production `Host` before the route goes live.
|
|
115
|
+
|
|
116
|
+
## Self-redirect loop on encoded paths
|
|
117
|
+
|
|
118
|
+
**What happened on v7 TanStack sites:** the router compared the request's
|
|
119
|
+
path with the one it would build and redirected on a mismatch. Braces were not
|
|
120
|
+
re-encoded, so `/{x}` โ 307 `/{x}` โ the browser re-encodes โ loop
|
|
121
|
+
(`ERR_TOO_MANY_REDIRECTS`, ~17k 307s a day from one login modal's
|
|
122
|
+
`<img src="{{qRCodeUrl}}">`). The v8 worker adds no guard for this. If the
|
|
123
|
+
fuzz below loops, answer such paths with a 404 in `routes`, before the router.
|
|
124
|
+
|
|
125
|
+
```bash
|
|
126
|
+
for p in '/%7Bx%7D' '/x%7B' '/foo-%7Bx%7D-1/p' '/%5Bx%5D' '/%7Cx' '/%5Ex' '/a%20b'; do
|
|
127
|
+
curl -s -o /dev/null -L --max-redirs 10 -A "Mozilla/5.0 Chrome/139" \
|
|
128
|
+
-w "$p %{http_code} hops=%{num_redirects}\n" "$CANDIDATE$p"
|
|
129
|
+
done # 5 or more hops (or curl error 47) is a loop
|
|
130
|
+
```
|
|
131
|
+
|
|
132
|
+
It is not only braces: `^` also looped on one store. Fuzz every character the
|
|
133
|
+
router may decode and not re-encode.
|
|
134
|
+
|
|
135
|
+
## Requests the worker answers itself
|
|
136
|
+
|
|
137
|
+
- `/deco/_liveness` answers `OK`. Use it for uptime checks, not `/`.
|
|
138
|
+
- `/deco/*`, `/live/*` and `/.decofile` answer 404 (v7's admin paths). Old tooling or monitors that call them see 404s; update them. During a ramp this also affects the old site ([traffic-ramp.md](./traffic-ramp.md#traps)).
|
|
139
|
+
- A page request with `Authorization` answers `Cache-Control: private, no-cache, no-store, must-revalidate`, whatever the app set.
|
|
@@ -0,0 +1,150 @@
|
|
|
1
|
+
# QA checklist template
|
|
2
|
+
|
|
3
|
+
Fill this from the [inventory](./qa-inventory.md). Keep only the sections the
|
|
4
|
+
site has, put a real file and a real URL in each row, and add a row for every
|
|
5
|
+
site-specific block the template doesn't cover. Mark the purchase path (home โ
|
|
6
|
+
listing โ product โ cart โ checkout) as P0.
|
|
7
|
+
|
|
8
|
+
Record PASS / FAIL / N/A per row. "Not checked" is not N/A.
|
|
9
|
+
|
|
10
|
+
Test every interactive row twice: after a full load (F5) and after reaching
|
|
11
|
+
the page by a **SPA click** ([react-spa.md](./react-spa.md)).
|
|
12
|
+
|
|
13
|
+
## A. Build and content
|
|
14
|
+
|
|
15
|
+
| # | Test | How to verify | Where |
|
|
16
|
+
|---|---|---|---|
|
|
17
|
+
| A1 | Build succeeds | the site's build script exits 0 | `vite.config.ts` / `next.config.*` |
|
|
18
|
+
| A2 | Schema is current | `deco schema --check` exits 0 | `.deco/schema.gen.json` |
|
|
19
|
+
| A3 | Content fits the schema | `deco check` (and `--draft=<name>` for the draft under test): 0 errors | `.deco/blocks` |
|
|
20
|
+
| A4 | Every saved block type exists | `deco check` reports no `no saved block or block type` | `.deco/index.ts` |
|
|
21
|
+
| A5 | Dev server starts clean | no errors in the terminal or the browser console | worker entry, root route |
|
|
22
|
+
|
|
23
|
+
## B. Page loads (one row per route template)
|
|
24
|
+
|
|
25
|
+
| # | Test | How to verify | Route |
|
|
26
|
+
|---|---|---|---|
|
|
27
|
+
| B1 | Home renders every section | visual check, console clean | `/` |
|
|
28
|
+
| B2 | Listing renders the product grid | a real category URL | catch-all |
|
|
29
|
+
| B3 | Product page renders every section | a real product URL, one with and one without optional blocks | catch-all |
|
|
30
|
+
| B4 | Search renders results and the empty state | a real term, then nonsense | catch-all or search route |
|
|
31
|
+
| B5 | Institutional pages render | one per template | catch-all |
|
|
32
|
+
| B6 | Not found is a real 404 | `curl -o /dev/null -w '%{http_code}'` on a made-up path โ 404 | catch-all |
|
|
33
|
+
| B7 | A lazy section loads and its fallback is sane | throttle the network; scroll to it | lazy blocks |
|
|
34
|
+
|
|
35
|
+
## C. Header
|
|
36
|
+
|
|
37
|
+
| # | Test | How to verify |
|
|
38
|
+
|---|---|---|
|
|
39
|
+
| C1 | Announcement bar renders (and rotates, if it does) | visual |
|
|
40
|
+
| C2 | Menu opens on mobile, closes on Escape and on the overlay | click, key, click |
|
|
41
|
+
| C3 | Mega-menu opens on hover on desktop | hover each top item |
|
|
42
|
+
| C4 | Search opens, suggests the **typed** term, submits | type a product name |
|
|
43
|
+
| C5 | Minicart opens; the badge counts items | add an item |
|
|
44
|
+
| C6 | Login or account entry works | click it, signed out and signed in |
|
|
45
|
+
|
|
46
|
+
## D. Sliders and carousels (one row per instance)
|
|
47
|
+
|
|
48
|
+
| # | Test | How to verify |
|
|
49
|
+
|---|---|---|
|
|
50
|
+
| D1 | Previous and next work | click the arrows |
|
|
51
|
+
| D2 | Dots work | click the dots |
|
|
52
|
+
| D3 | Autoplay advances, if configured | wait one interval |
|
|
53
|
+
| D4 | Listeners are cleaned up | navigate away and back 3ร; listener count stays flat |
|
|
54
|
+
|
|
55
|
+
## E. Product page
|
|
56
|
+
|
|
57
|
+
| # | Test | How to verify |
|
|
58
|
+
|---|---|---|
|
|
59
|
+
| E1 | Gallery loads; zoom works | click or hover the main image |
|
|
60
|
+
| E2 | Variant picker changes the SKU, price and URL, and stays on the site | pick each dimension |
|
|
61
|
+
| E3 | Product โ product by SPA click shows the new product's images at once | click a related product |
|
|
62
|
+
| E4 | Buy button adds the item, shows a loading state, opens the minicart | click once; double click adds once |
|
|
63
|
+
| E5 | Shipping estimate returns options; the URL doesn't change | enter a postal code |
|
|
64
|
+
| E6 | Out-of-stock state shows; buy button disabled | an unavailable SKU |
|
|
65
|
+
| E7 | Reviews, recommendations, wishlist, share render or fail quietly | each block present on the page |
|
|
66
|
+
| E8 | Breadcrumb links work | click each item |
|
|
67
|
+
|
|
68
|
+
## F. Cart
|
|
69
|
+
|
|
70
|
+
| # | Test | How to verify |
|
|
71
|
+
|---|---|---|
|
|
72
|
+
| F1 | Items show image, name, price, quantity | add two different items |
|
|
73
|
+
| F2 | Quantity change and remove update the total | +, โ, remove |
|
|
74
|
+
| F3 | Coupon applies and survives a reload | a valid and an invalid code |
|
|
75
|
+
| F4 | Free-shipping progress updates | add items near the threshold |
|
|
76
|
+
| F5 | **Change quantity, then go to checkout within 300 ms**: checkout shows the new quantity | WebKit and Chromium |
|
|
77
|
+
| F6 | Checkout button reaches checkout with the same cart | compare the order form |
|
|
78
|
+
|
|
79
|
+
## G. Listing and search
|
|
80
|
+
|
|
81
|
+
| # | Test | How to verify |
|
|
82
|
+
|---|---|---|
|
|
83
|
+
| G1 | Filters apply; from page 2 they reset to page 1 | apply a filter on page 2 |
|
|
84
|
+
| G2 | Sort reorders and keeps the filters | change sort with a filter on |
|
|
85
|
+
| G3 | Pagination or "load more" works and keeps `q` and `sort` | page 2, 3 |
|
|
86
|
+
| G4 | Price range filter works | slider or inputs |
|
|
87
|
+
| G5 | Empty result shows the fallback | a nonsense term |
|
|
88
|
+
| G6 | Cards link to the product; discount flags render | click, visual |
|
|
89
|
+
| G7 | Title, description, canonical and `rel=next/prev` match the old site | view source on page 1 and 2 |
|
|
90
|
+
|
|
91
|
+
## H. Modals and drawers
|
|
92
|
+
|
|
93
|
+
One row per drawer or modal in the inventory: it opens, closes on Escape,
|
|
94
|
+
closes on the overlay and on its close button, and opens again after a SPA
|
|
95
|
+
navigation.
|
|
96
|
+
|
|
97
|
+
## I. Footer
|
|
98
|
+
|
|
99
|
+
| # | Test | How to verify |
|
|
100
|
+
|---|---|---|
|
|
101
|
+
| I1 | Newsletter submits and shows success and error | a valid and an invalid email |
|
|
102
|
+
| I2 | Links, social icons and payment icons render | visual; links open the right targets |
|
|
103
|
+
| I3 | Back-to-top works | click |
|
|
104
|
+
|
|
105
|
+
## J. Content editing (Studio)
|
|
106
|
+
|
|
107
|
+
| # | Test | How to verify |
|
|
108
|
+
|---|---|---|
|
|
109
|
+
| J1 | Each block type in use has a usable form | open one of each in Studio (**deco-cms-schema**) |
|
|
110
|
+
| J2 | A draft previews on the hosts editors use | `deco drafts url <name>` โ the page shows the draft |
|
|
111
|
+
| J3 | A preview is never cached | the draft response has `Cache-Control: max-age=0, no-cache, must-revalidate` and `X-Robots-Tag: noindex, nofollow` |
|
|
112
|
+
| J4 | A publish reaches the live site within about a minute | publish a small change; reload |
|
|
113
|
+
| J5 | Each running test and campaign renders both sides | preview links with `__test` / `__campaign` (**deco-variants**) |
|
|
114
|
+
|
|
115
|
+
## K. Analytics
|
|
116
|
+
|
|
117
|
+
| # | Test | How to verify |
|
|
118
|
+
|---|---|---|
|
|
119
|
+
| K1 | Tag manager loads from `<head>` without a gesture | network panel, no interaction |
|
|
120
|
+
| K2 | Page view fires on load **and** on SPA navigation | `dataLayer` after a click |
|
|
121
|
+
| K3 | `view_item`, `select_item`, `add_to_cart` fire with the old payload shape | compare with the old site |
|
|
122
|
+
| K4 | Every vendor in the inventory receives events | its own dashboard the next day |
|
|
123
|
+
|
|
124
|
+
## L. Console and network health
|
|
125
|
+
|
|
126
|
+
| # | Test | What to look for |
|
|
127
|
+
|---|---|---|
|
|
128
|
+
| L1 | No hydration errors | React #418, #423, #425; "did not match" warnings |
|
|
129
|
+
| L2 | No hook-order errors | React #310 on product โ product |
|
|
130
|
+
| L3 | No `Cannot read properties of undefined` | a loader result without a guard |
|
|
131
|
+
| L4 | No 404 on `/assets/*` after a deploy | keep a tab open across a deploy |
|
|
132
|
+
| L5 | No duplicate upstream calls per page | the server log or `http.client.request.duration` per provider (**deco-storefront-performance**) |
|
|
133
|
+
|
|
134
|
+
## M. Performance and cache sanity
|
|
135
|
+
|
|
136
|
+
| # | Test | How to verify |
|
|
137
|
+
|---|---|---|
|
|
138
|
+
| M1 | Browser heap stays flat over 10 SPA navigations | DevTools Memory |
|
|
139
|
+
| M2 | Minicart open/close 10ร leaves the heap flat | heap snapshots before and after |
|
|
140
|
+
| M3 | Anonymous pages send no `Set-Cookie` except the first-visit `deco_segment` | `curl -sI` without cookies |
|
|
141
|
+
| M4 | The second anonymous request is a cache hit | `X-Cache: HIT` from the site's page cache (**deco-storefront-caching**) |
|
|
142
|
+
| M5 | Lazy sections load their chunk only when needed | network panel while scrolling |
|
|
143
|
+
|
|
144
|
+
## Adapting it
|
|
145
|
+
|
|
146
|
+
1. Remove the sections the site doesn't have.
|
|
147
|
+
2. Add a section per site-specific feature (configurators, calculators, store locators, wizards): open, use, result, error.
|
|
148
|
+
3. Swap platform rows (cart, checkout, shipping) for the site's commerce platform.
|
|
149
|
+
4. Add rows for bugs found in earlier rounds.
|
|
150
|
+
5. For end-to-end purchase tests that run in CI, see the **ecommerce-qa** skill in decocms/storefront-skills (the `@decocms/qa` engine). Its stack detection was written for older sites; check it recognizes a v8 site before relying on it.
|
|
@@ -0,0 +1,120 @@
|
|
|
1
|
+
# QA inventory: what this site actually has
|
|
2
|
+
|
|
3
|
+
A QA checklist is only useful when it is scoped to the site: no rows for
|
|
4
|
+
features it doesn't have, and a row for every block, route and interaction it
|
|
5
|
+
does have. Build the inventory first, then fill
|
|
6
|
+
[qa-checklist-template.md](./qa-checklist-template.md) from it.
|
|
7
|
+
|
|
8
|
+
Run everything from the site root (the folder that holds `.deco/`). Pull
|
|
9
|
+
production content first so `.deco/blocks` matches what is live:
|
|
10
|
+
|
|
11
|
+
```bash
|
|
12
|
+
deco pull # production into .deco/blocks (see deco-site-workflow)
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
## 1. Health: schema and content
|
|
16
|
+
|
|
17
|
+
```bash
|
|
18
|
+
deco schema --check # .deco/schema.gen.json is up to date with the block types
|
|
19
|
+
deco check # production content against the schema: 0 errors
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
Every error here is a page that renders wrong. Fix them before QA starts, or
|
|
23
|
+
list them as known issues.
|
|
24
|
+
|
|
25
|
+
## 2. Block types (the block map)
|
|
26
|
+
|
|
27
|
+
`.deco/index.ts` (or `.tsx`) exports the block map, the types `deco schema` turns into
|
|
28
|
+
Studio forms. Each key is a block type editors can pick.
|
|
29
|
+
|
|
30
|
+
```bash
|
|
31
|
+
sed -n '1,200p' .deco/index.ts* # read the map and where each entry comes from
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
Then count which types the content really uses. Types in the map that no
|
|
35
|
+
saved block uses need no QA row; types used everywhere need one per place.
|
|
36
|
+
|
|
37
|
+
```bash
|
|
38
|
+
jq -r '.. | objects | .["__resolveType"]? // empty' .deco/blocks/*.json | sort | uniq -c | sort -rn
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
## 3. Pages and routes
|
|
42
|
+
|
|
43
|
+
Each saved page block has a `path` (a literal, `:name` segments, or a
|
|
44
|
+
trailing `*`). The site's catch-all route matches a URL against them with
|
|
45
|
+
`matchRoute`; other routes are the framework's own (TanStack `src/routes/`,
|
|
46
|
+
Next.js `app/`).
|
|
47
|
+
|
|
48
|
+
```bash
|
|
49
|
+
jq -r 'select(.path) | "\(.path)\t\(input_filename | split("/") | last)"' .deco/blocks/*.json | sort
|
|
50
|
+
ls src/routes 2>/dev/null; find app -name 'page.tsx' 2>/dev/null
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
For each template, pick one real URL (a real product slug, a real category)
|
|
54
|
+
for the checklist. Add the page types every store has even if the template is
|
|
55
|
+
generic: home, listing, product, search, not found, institutional.
|
|
56
|
+
|
|
57
|
+
## 4. Redirects, experiments, campaigns
|
|
58
|
+
|
|
59
|
+
```bash
|
|
60
|
+
jq '.redirects | length' .deco/blocks/Redirects.json 2>/dev/null # rules to sweep
|
|
61
|
+
jq . .deco/blocks/experiments.json .deco/blocks/campaigns.json 2>/dev/null # the saved blocks every test and campaign rule reads
|
|
62
|
+
grep -rl '"multivariate"' .deco/blocks | head # pages with variants
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
Each running test or campaign needs a row per side: force each with a Studio
|
|
66
|
+
preview link (`__test`, `__campaign` on a draft link). **deco-variants** has
|
|
67
|
+
the details.
|
|
68
|
+
|
|
69
|
+
## 5. Interactive components
|
|
70
|
+
|
|
71
|
+
```bash
|
|
72
|
+
# client state and effects
|
|
73
|
+
grep -rlE "useState|useEffect|useReducer|useSyncExternalStore" src --include='*.tsx'
|
|
74
|
+
# event handlers
|
|
75
|
+
grep -rlE "onClick|onChange|onSubmit|addEventListener" src --include='*.tsx'
|
|
76
|
+
# direct DOM access (fragile under React)
|
|
77
|
+
grep -rlE "document\.(getElementById|querySelector)" src --include='*.tsx' --include='*.ts'
|
|
78
|
+
# inline scripts (test by SPA click, not only F5)
|
|
79
|
+
grep -rlE "useScript\(|useScriptAsDataURI\(|inlineScript\(|<script" src
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
Group the hits by UI: header (menu, search, minicart), sliders, product page
|
|
83
|
+
(gallery, variant picker, buy button, shipping estimate), cart, listing
|
|
84
|
+
(filters, sort, pagination), modals and drawers, footer (newsletter).
|
|
85
|
+
|
|
86
|
+
## 6. Server functions and loaders
|
|
87
|
+
|
|
88
|
+
Server functions replace v7's `/deco/invoke`. Each one is a request the
|
|
89
|
+
browser makes and a thing that can be cancelled by navigation.
|
|
90
|
+
|
|
91
|
+
```bash
|
|
92
|
+
grep -rn "createServerFn" src | cut -d: -f1 | sort | uniq -c # TanStack
|
|
93
|
+
grep -rln '"use server"' src app 2>/dev/null # Next.js
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
Mark the ones that write (cart, newsletter, login): they need a "write then
|
|
97
|
+
navigate at once" row ([react-spa.md](./react-spa.md#server-functions-cancelled-on-navigation)).
|
|
98
|
+
|
|
99
|
+
## 7. Integrations
|
|
100
|
+
|
|
101
|
+
```bash
|
|
102
|
+
jq -r '.dependencies // {} | keys[]' package.json | grep -E "^@decocms/" # apps-vtex, apps-shopify, โฆ
|
|
103
|
+
grep -rliE "dataLayer|sendEvent|DECO\.events" src | head # analytics
|
|
104
|
+
grep -rliE "<vendor names you know of: reviews, chat, search, consent>" src
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
Each integration gets a row: it loads, it receives events, and it fails
|
|
108
|
+
without breaking the page.
|
|
109
|
+
|
|
110
|
+
## 8. Old-site behaviors
|
|
111
|
+
|
|
112
|
+
If the site was ported, diff the inventory against the old repo too: a
|
|
113
|
+
feature that exists there and has no row here was either dropped (get
|
|
114
|
+
sign-off) or forgotten ([process.md](./process.md#inventory-of-what-was-not-ported)).
|
|
115
|
+
|
|
116
|
+
## Output
|
|
117
|
+
|
|
118
|
+
Write the inventory down as a short table before the checklist: block type โ
|
|
119
|
+
pages that use it โ component file. That table is what makes each checklist row
|
|
120
|
+
point at a real file and a real URL.
|
|
@@ -0,0 +1,183 @@
|
|
|
1
|
+
# React and SPA leftovers
|
|
2
|
+
|
|
3
|
+
A Fresh site rendered islands on full page loads and tolerated Preact habits.
|
|
4
|
+
A v8 TanStack site is React with client-side navigation: components are reused
|
|
5
|
+
across routes, inline scripts inserted on the client don't run, and React is
|
|
6
|
+
strict about controlled inputs and hydration. Most of these pass a reload test
|
|
7
|
+
and fail on a **SPA click**.
|
|
8
|
+
|
|
9
|
+
Always test by clicking links the app rendered. A `click()` on an `<a>` you
|
|
10
|
+
appended to `body` does a full reload. Confirm SPA navigation with
|
|
11
|
+
`performance.getEntriesByType("navigation").length === 1` after the click.
|
|
12
|
+
|
|
13
|
+
How to write sections and client components on v8 is in
|
|
14
|
+
**deco-site-authoring**; this file is only the go-live sweep.
|
|
15
|
+
|
|
16
|
+
## Preact and Fresh leftovers
|
|
17
|
+
|
|
18
|
+
Found by a Playwright sweep, production against local, on one store:
|
|
19
|
+
|
|
20
|
+
| Symptom | Root cause | Fix |
|
|
21
|
+
|---|---|---|
|
|
22
|
+
| Typing in an input erases every letter | `value={โฆ}` without `onChange` (Preact tolerated it; React makes it read-only) | `defaultValue` |
|
|
23
|
+
| Modal or zoom never opens on mobile | a controlled checkbox (`open={false}`) without `onChange` | uncontrolled, `defaultChecked` |
|
|
24
|
+
| "Add to cart" from a secondary component does nothing | `window.STOREFRONT.CART.addToCart` or `window.addToCart`: the Fresh global SDK doesn't exist | call the site's cart server function |
|
|
25
|
+
| A form does nothing | `hx-post` replaced by `preventDefault` and a TODO | wire it to a server function |
|
|
26
|
+
| A popup library never loads | `<script src>` inside a client-rendered section never runs | load it on demand |
|
|
27
|
+
| A label doesn't open its modal | raw HTML strings with `htmlFor` or `className` | `for` and `class` inside strings |
|
|
28
|
+
| An error on every keystroke | `onInput={useScript(...)}` passes a string as the handler | a function handler |
|
|
29
|
+
| The second lookup never renders | code removed React-owned DOM children by hand | reset state |
|
|
30
|
+
| Search steals focus every 300 ms | `setInterval(focus)` never cleared | bounded attempts, cancel on close and navigation |
|
|
31
|
+
| A double click adds two items | no in-flight guard | pending guards |
|
|
32
|
+
| A click before hydration is lost | | read `el.checked` on mount |
|
|
33
|
+
|
|
34
|
+
```bash
|
|
35
|
+
grep -rnE "window\.STOREFRONT|window\.addToCart|hx-(post|get|on|trigger)" src
|
|
36
|
+
grep -rnE "on[A-Z][a-zA-Z]+=\{useScript" src
|
|
37
|
+
grep -rnE "open=\{false\}" src
|
|
38
|
+
grep -rnE "<script[^>]+src=" src
|
|
39
|
+
grep -rnE "\.removeChild\(|\.innerHTML\s*=|replaceChildren\(" src
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
For `value=` without `onChange`, run dev with the console open on every form.
|
|
43
|
+
React warns: "You provided a `value` prop without an `onChange` handler".
|
|
44
|
+
|
|
45
|
+
## Inline scripts do not run on SPA navigation
|
|
46
|
+
|
|
47
|
+
`useScript` and `useScriptAsDataURI` still exist in `@decocms/compat-v7`
|
|
48
|
+
(v7's output, byte for byte), and `inlineScript(js)` is the string form they
|
|
49
|
+
point to. React inserts a `<script>` on the client without running it. Only
|
|
50
|
+
scripts parsed from the server HTML run. Seen: a countdown frozen at
|
|
51
|
+
00:00:00, a header under the timer, a sticky gallery that never shrinks. All
|
|
52
|
+
fine after F5.
|
|
53
|
+
|
|
54
|
+
Pattern: keep the inline script for the first paint, make it idempotent, and
|
|
55
|
+
also run it from `useLayoutEffect` with a cleanup.
|
|
56
|
+
|
|
57
|
+
```tsx
|
|
58
|
+
const init = (id: string) => {
|
|
59
|
+
const el = document.getElementById(id) as (HTMLElement & { __started?: boolean; __stop?: () => void }) | null;
|
|
60
|
+
if (!el || el.__started) return; // idempotent
|
|
61
|
+
el.__started = true;
|
|
62
|
+
const stops: (() => void)[] = [];
|
|
63
|
+
el.__stop = () => stops.forEach((s) => s()); // remove listeners and observers
|
|
64
|
+
// ...
|
|
65
|
+
};
|
|
66
|
+
useLayoutEffect(() => { init(id); return () => document.getElementById(id)?.__stop?.(); }, []);
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
`useScript(fn)` serializes `fn.toString()`, which can differ between the
|
|
70
|
+
server and the client build and break hydration. Its own docs mark it
|
|
71
|
+
deprecated in favor of `inlineScript` with a plain string.
|
|
72
|
+
|
|
73
|
+
```bash
|
|
74
|
+
grep -rlnE "useScript\(|useScriptAsDataURI\(|inlineScript\(|<script" src
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
๐งช For each hit: reach the page by a SPA click and check it works. Go
|
|
78
|
+
listing โ product โ back three times; listener counts must stay flat.
|
|
79
|
+
|
|
80
|
+
## Same-route navigation reuses components
|
|
81
|
+
|
|
82
|
+
Product โ product is the same route (the catch-all), so the page component is
|
|
83
|
+
reused.
|
|
84
|
+
|
|
85
|
+
1. `<img>` nodes reused with a new `src` show the previous product's photos for about 1.2 s. Fix: a `key` per product group on the gallery.
|
|
86
|
+
2. `if (!items.length) return null` **before** a hook: an instance moving from a product without that block to one with it calls more hooks โ React error #310, and the page renders only header and footer. One store had 13 more components with the same pattern.
|
|
87
|
+
|
|
88
|
+
```tsx
|
|
89
|
+
<Gallery key={product.inProductGroupWithID ?? product.productID} โฆ />
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
```bash
|
|
93
|
+
grep -rn "rules-of-hooks" eslint.config.* .eslintrc* biome.json 2>/dev/null || echo "rules-of-hooks not enabled"
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
Test any home-made scan against a known bug first. One awk scan "passed" with
|
|
97
|
+
zero hits because macOS awk did not support the regex.
|
|
98
|
+
|
|
99
|
+
๐งช SPA-click product โ product between products **with and without**
|
|
100
|
+
optional blocks (video, size guide); the first gallery `<img>` must change.
|
|
101
|
+
|
|
102
|
+
## Hydration error #418
|
|
103
|
+
|
|
104
|
+
**What happened** (~2,750 users a day, 90% on mobile listings): tag-manager
|
|
105
|
+
scripts appended to `body` during parse landed between `</main>` and React's
|
|
106
|
+
own tail scripts. React claimed them during hydration โ #418, and the whole
|
|
107
|
+
page re-rendered on the client.
|
|
108
|
+
|
|
109
|
+
- Keep every node after `<main>` one React rendered. `DecoDocument` renders its `children` after the page; put the site's own trailing UI there, not in raw HTML.
|
|
110
|
+
- CMS or platform HTML with unbalanced tags in `dangerouslySetInnerHTML` โ balance it before rendering; truncate HTML at word boundaries, not as plain text.
|
|
111
|
+
- Block HTML inside `<p>` breaks the parse โ use `<div>`.
|
|
112
|
+
- `location.origin` read during SSR โ pass the origin in.
|
|
113
|
+
|
|
114
|
+
```bash
|
|
115
|
+
grep -rn "dangerouslySetInnerHTML" src
|
|
116
|
+
```
|
|
117
|
+
|
|
118
|
+
๐งช Mobile emulation, 6ร CPU, tag manager on, scroll during load, about 20
|
|
119
|
+
listing loads: zero #418. After hydration, any third-party `<script>` in
|
|
120
|
+
`document.body.children` with a `__reactFiber$*` key is a bug.
|
|
121
|
+
|
|
122
|
+
## Server functions cancelled on navigation
|
|
123
|
+
|
|
124
|
+
**What happened:** a TanStack server function is cancelled when the user
|
|
125
|
+
navigates away mid-request. Cancelled at 50โ250 ms, it never reached the
|
|
126
|
+
platform. "+" then "checkout" lost the item. Also, on Fresh the add-to-cart
|
|
127
|
+
call was not awaited, so the "added" sheet opened at once; awaited, it opened
|
|
128
|
+
0.7 s late.
|
|
129
|
+
|
|
130
|
+
- Open the UI optimistically before the `await`; close it on failure.
|
|
131
|
+
- Track pending cart writes; full-page links (especially checkout) wait for them.
|
|
132
|
+
- `fetch(..., { keepalive: true })` on `pagehide` for writes.
|
|
133
|
+
|
|
134
|
+
๐งช WebKit: change the quantity and click "checkout" within 300 ms. The
|
|
135
|
+
checkout shows the new quantity.
|
|
136
|
+
|
|
137
|
+
## Stale chunks after deploy
|
|
138
|
+
|
|
139
|
+
Every deploy removes old hashed chunks. Open tabs then get 404s on
|
|
140
|
+
`/assets/*.js` (103 to 254 per deploy on one store). The router reloads only
|
|
141
|
+
on route-chunk failures; a lazy section's chunk fails into the error boundary
|
|
142
|
+
(a product page without photos, price or buy button). The v8 packages add no
|
|
143
|
+
handler for this.
|
|
144
|
+
|
|
145
|
+
- Listen to Vite's `vite:preloadError` and reload once per chunk, guarded in `sessionStorage` with a cooldown of about 30 s.
|
|
146
|
+
- Add a small inline guard in `<head>` for when the main entry itself 404s.
|
|
147
|
+
|
|
148
|
+
๐งช Open a tab, deploy, then SPA-navigate in that tab to a page with lazy
|
|
149
|
+
sections.
|
|
150
|
+
|
|
151
|
+
## Preload on intent
|
|
152
|
+
|
|
153
|
+
`createDecoRouter` defaults to `defaultPreload: "intent"`: hovering a link
|
|
154
|
+
loads that page's data. On v7, intent preload cost one store 197 GB of egress
|
|
155
|
+
in 2.5 days (each hover fetched a 1.6 MB product payload). Measure the
|
|
156
|
+
payload of a page load before go-live. If it is large, trim it
|
|
157
|
+
(**deco-storefront-performance**) or pass `defaultPreload: false`.
|
|
158
|
+
|
|
159
|
+
## Browser memory leaks
|
|
160
|
+
|
|
161
|
+
**What happened (minicart):** 1โ2 GB per open; the browser died at 3โ4 GB.
|
|
162
|
+
|
|
163
|
+
- Signal shims (`useSignalEffect`, `useComputed` without deps) โ render loops.
|
|
164
|
+
- A store hook expecting `{ unsubscribe }` while the source returns a function โ subscriptions pile up. Use `useSyncExternalStore` with a stable `subscribe`.
|
|
165
|
+
- Every cart item re-rendered on open and close โ make open/close CSS-only and memoize the list.
|
|
166
|
+
- `removeEventListener` with a new arrow function does nothing โ keep the reference.
|
|
167
|
+
|
|
168
|
+
๐งช DevTools Memory: open and close the minicart 10 times with the tag manager
|
|
169
|
+
on; a heap snapshot before and after must be flat.
|
|
170
|
+
|
|
171
|
+
## Legacy service worker
|
|
172
|
+
|
|
173
|
+
An old site's service worker kept intercepting requests on one store.
|
|
174
|
+
Removing `register()` does not uninstall it for past visitors. Ship a `sw.js`
|
|
175
|
+
at the same path that unregisters itself.
|
|
176
|
+
|
|
177
|
+
```js
|
|
178
|
+
self.addEventListener("install", () => self.skipWaiting());
|
|
179
|
+
self.addEventListener("activate", async () => {
|
|
180
|
+
await self.registration.unregister();
|
|
181
|
+
(await self.clients.matchAll()).forEach((c) => c.navigate(c.url));
|
|
182
|
+
});
|
|
183
|
+
```
|