@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,116 @@
|
|
|
1
|
+
# Hydration: mismatches, sections that never wake up, and flashes
|
|
2
|
+
|
|
3
|
+
Load when: React logs a hydration mismatch; a section shows its server markup but clicks
|
|
4
|
+
and effects do nothing; part of the page goes blank or flashes a fallback on load.
|
|
5
|
+
|
|
6
|
+
Most of this is plain React 19 and TanStack Start. The v8-specific parts are the streamed
|
|
7
|
+
block promises (section 2) and the per-block `<Suspense>` (section 3).
|
|
8
|
+
|
|
9
|
+
## 1. Mismatches: find the element, then the cause
|
|
10
|
+
|
|
11
|
+
React's error names the element whose server HTML differs from the first client render.
|
|
12
|
+
Compare the server HTML (view-source, or `curl`) with the DOM in DevTools at that spot.
|
|
13
|
+
Test with a hard reload: a client-side navigation renders on the client only and hides
|
|
14
|
+
the problem.
|
|
15
|
+
|
|
16
|
+
| Cause | Example | Fix |
|
|
17
|
+
|---|---|---|
|
|
18
|
+
| A value only the server has | `process.env.STORE_NAME` in a component: set on the server, `undefined` in the browser bundle | Pass it from the server in loader data, or use a build-time value (`import.meta.env.VITE_*`) that both bundles get |
|
|
19
|
+
| Time, randomness, locale | `Date.now()`, `Math.random()`, `toLocaleString()` with the server's time zone | Compute on the server and pass the result, or render it in an effect |
|
|
20
|
+
| Browser-only state in render | `window`, `localStorage`, `matchMedia`, the cart count from a cookie | Render a stable placeholder, fill it in `useEffect` |
|
|
21
|
+
| Invalid nesting | `<a>` inside `<a>`, `<div>` inside `<p>`, a `<button>` inside a `<button>` | The browser repairs the HTML before React sees it. Fix the markup (below) |
|
|
22
|
+
| A browser extension | Injected attributes on `<html>` or `<body>` | Reproduce in a clean profile before you change code |
|
|
23
|
+
|
|
24
|
+
`DecoDocument` already sets `suppressHydrationWarning` on `<body>`. It covers that
|
|
25
|
+
element's own attributes only, not its children.
|
|
26
|
+
|
|
27
|
+
### `suppressHydrationWarning`, only where the content really differs
|
|
28
|
+
|
|
29
|
+
Some content is meant to differ: a cart badge, a greeting, a wishlist heart. Put the
|
|
30
|
+
attribute on the element whose text differs, not on a wrapper:
|
|
31
|
+
|
|
32
|
+
```tsx
|
|
33
|
+
// Wrong: hides every mismatch in the subtree, including real bugs
|
|
34
|
+
<div suppressHydrationWarning><Header /><CartBadge count={count} /></div>
|
|
35
|
+
|
|
36
|
+
// Right: one element, one known difference
|
|
37
|
+
<span suppressHydrationWarning>{count}</span>
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
It works one level deep and only for text and attributes. For anything bigger, render a
|
|
41
|
+
placeholder on the server and the real thing after mount.
|
|
42
|
+
|
|
43
|
+
### Nested links
|
|
44
|
+
|
|
45
|
+
A card that is a link, with a "see more" link inside it, is `<a>` inside `<a>`. React warns
|
|
46
|
+
(`validateDOMNesting`) and the browser splits the outer link. Give the inner component a
|
|
47
|
+
prop that renders a `<span>` when it is already inside a link:
|
|
48
|
+
|
|
49
|
+
```tsx
|
|
50
|
+
export function SeeMore({ href, insideLink }: { href: string; insideLink?: boolean }) {
|
|
51
|
+
return insideLink ? <span className="see-more">See more</span> : <a href={href} className="see-more">See more</a>;
|
|
52
|
+
}
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
Find candidates with `rg -l '<a[^>]*>.*<a' src/ --glob '*.tsx'`, then read the components a
|
|
56
|
+
card renders.
|
|
57
|
+
|
|
58
|
+
## 2. A streamed section that never hydrates (TanStack Start)
|
|
59
|
+
|
|
60
|
+
Symptom: the section looks right, but no effect runs and no handler fires. It hides behind
|
|
61
|
+
plain links (navigation still works) and behind reduced motion (a scroll animation that
|
|
62
|
+
never starts looks like a static grid).
|
|
63
|
+
|
|
64
|
+
Seen on TanStack Start 1.166 with block promises returned through the page server function
|
|
65
|
+
and streamed: a block still pending when the document streamed arrived as a late
|
|
66
|
+
resolution script, and the browser's copy of its promise never settled.
|
|
67
|
+
|
|
68
|
+
Check, after any change to the page route or a TanStack upgrade:
|
|
69
|
+
|
|
70
|
+
1. Load a page whose blocks call the upstream. In the console, confirm that every block
|
|
71
|
+
promise in the route's loader data is fulfilled.
|
|
72
|
+
2. Pick a section's DOM node and confirm it has a key starting with `__reactFiber`.
|
|
73
|
+
|
|
74
|
+
If either fails, await every block on the server before returning. TTFB then becomes the
|
|
75
|
+
slowest block (see [`render-location.md`](./render-location.md#3-streamed-blocks-vs-awaited-blocks)),
|
|
76
|
+
so say so in the route file and in the PR. The `deco-v7-to-v8-migration` skill has the same
|
|
77
|
+
note for migrated sites.
|
|
78
|
+
|
|
79
|
+
## 3. Flashes and blank frames
|
|
80
|
+
|
|
81
|
+
In the example page route, each section block renders inside its own `<Suspense>` with
|
|
82
|
+
a fallback. What the visitor
|
|
83
|
+
sees between the server HTML and the hydrated page depends on that fallback and on how
|
|
84
|
+
the section's component loads.
|
|
85
|
+
|
|
86
|
+
| Symptom | Cause | Fix |
|
|
87
|
+
|---|---|---|
|
|
88
|
+
| A section paints, goes blank or shows its fallback, then paints again | The component is loaded with `React.lazy`, and its module is not ready during hydration, so React drops the server HTML and shows the fallback | Import above-the-fold section components statically in the view map. Keep `React.lazy` for sections below the fold |
|
|
89
|
+
| The page jumps when a section resolves | The fallback is shorter than the section | Give the fallback the section's height (`min-height`, aspect ratio). See [`cls-third-party.md`](./cls-third-party.md) |
|
|
90
|
+
| A section shows the route's failure UI (the example app renders "This content is temporarily unavailable") | The block failed on the server | Read the server log for that block's error. It is a loader failure, not a render problem |
|
|
91
|
+
|
|
92
|
+
To see a flash frame by frame, record a trace with screenshots
|
|
93
|
+
([`trace-reading.md`](./trace-reading.md)).
|
|
94
|
+
|
|
95
|
+
## 4. Keys and DOM warnings
|
|
96
|
+
|
|
97
|
+
Fix these even when nothing looks broken: they hide real errors in the console, and a
|
|
98
|
+
wrong key reuses the wrong DOM node.
|
|
99
|
+
|
|
100
|
+
| Warning | Fix |
|
|
101
|
+
|---|---|
|
|
102
|
+
| `Each child in a list should have a unique "key" prop` | A stable id: `key={product.productID}`. An index only for static lists |
|
|
103
|
+
| `Encountered two children with the same key` | The id is not unique (two cards in the same product group). Combine: `` key={`${product.productID}-${index}`} `` |
|
|
104
|
+
| `Invalid DOM property 'fetchpriority'` | `fetchPriority`. Same for SVG: `strokeLinecap`, `fillRule`, `clipRule` |
|
|
105
|
+
| `Invalid DOM property 'class'` | `className` (a Preact leftover) |
|
|
106
|
+
| `value` without `onChange` | Add `onChange`, or use `defaultValue` |
|
|
107
|
+
| `selected` on `<option>` | `value` on the `<select>` |
|
|
108
|
+
|
|
109
|
+
## Checklist
|
|
110
|
+
|
|
111
|
+
- [ ] Hard reload, console open, zero hydration errors on home, listing, product page
|
|
112
|
+
- [ ] Every block promise fulfilled; a section node has `__reactFiber…`
|
|
113
|
+
- [ ] Above-the-fold sections imported statically
|
|
114
|
+
- [ ] Fallbacks the height of their section
|
|
115
|
+
- [ ] `suppressHydrationWarning` only on single elements with known differences
|
|
116
|
+
- [ ] No nested `<a>`, no key or DOM-property warnings
|
|
@@ -0,0 +1,107 @@
|
|
|
1
|
+
# N+1 calls in block functions
|
|
2
|
+
|
|
3
|
+
Load when: SSR time grows with the number of products on the page; the same upstream
|
|
4
|
+
operation shows up dozens of times for one page; VTEX answers 429.
|
|
5
|
+
|
|
6
|
+
In v8 the loaders a site uses are its own code: the migration vendors v7's app loaders
|
|
7
|
+
into the site, and new ones call a thin client (`createVtexClient` from
|
|
8
|
+
`@decocms/apps-vtex`, and the other `@decocms/apps-*`). Nothing in the framework batches
|
|
9
|
+
or caches those calls. An N+1 is in your code, and so is the fix.
|
|
10
|
+
|
|
11
|
+
## The pattern
|
|
12
|
+
|
|
13
|
+
```ts
|
|
14
|
+
// RED FLAG: one upstream call per product
|
|
15
|
+
export async function productShelf(props: { products: Product[] }) {
|
|
16
|
+
const products = await Promise.all(
|
|
17
|
+
props.products.map(async (p) => ({ ...p, specs: await fetchSpecs(p.productID) })),
|
|
18
|
+
);
|
|
19
|
+
return { component: "shelf", props: { products } };
|
|
20
|
+
}
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
A 24-product shelf is 24 extra round trips before the section can render. A burst like
|
|
24
|
+
that can draw 429s from VTEX, and the VTEX client retries a 429 on idempotent requests
|
|
25
|
+
(2 retries with backoff by default), which adds more wait. A home page with several
|
|
26
|
+
shelves multiplies it.
|
|
27
|
+
|
|
28
|
+
| Pattern | Severity | Example |
|
|
29
|
+
|---|---|---|
|
|
30
|
+
| Upstream call inside `.map()` | Critical | `products.map((p) => fetchSpecs(p.id))` |
|
|
31
|
+
| Data already in the product | High | refetching specs or SKUs the search returned |
|
|
32
|
+
| Per-item call where a batch exists | High | one Master Data search per id |
|
|
33
|
+
| `await` inside a `for` loop | Medium | `for (const p of products) await fetch(p)` |
|
|
34
|
+
| Unbounded `Promise.all` | Medium | `Promise.all(hundredItems.map(fetch))` |
|
|
35
|
+
|
|
36
|
+
## Fix order
|
|
37
|
+
|
|
38
|
+
**1. Is the data already there?** Most N+1s fetch what the search already returned. An
|
|
39
|
+
Intelligent Search product carries its specification groups and its SKUs, and the
|
|
40
|
+
schema.org mapping in the site's loaders puts them on the product
|
|
41
|
+
(`@decocms/compat-v7/commerce/types`):
|
|
42
|
+
|
|
43
|
+
| Per-item VTEX call | Already on the product as |
|
|
44
|
+
|---|---|
|
|
45
|
+
| `/api/catalog_system/pvt/products/{id}/Specification` | `product.isVariantOf.additionalProperty` |
|
|
46
|
+
| `/api/catalog_system/pub/products/variations/{id}` | `product.isVariantOf.hasVariant` |
|
|
47
|
+
|
|
48
|
+
Delete the call and read the field. If components expect the old shape (numeric spec ids,
|
|
49
|
+
the Catalog API's `{ Id, Name, Value[] }`), write a small adapter from
|
|
50
|
+
`additionalProperty` and keep it next to the components. Get the exact spec names from a
|
|
51
|
+
real search response first: some stores have names with double spaces or trailing
|
|
52
|
+
blanks.
|
|
53
|
+
|
|
54
|
+
**2. Is it per page, not per product?** Related products, "buy together" and cross-selling
|
|
55
|
+
are one call for the page, not one per card. `createVtexClient(...).catalog.crossSelling`
|
|
56
|
+
takes one product id. Call it once for the page's product.
|
|
57
|
+
|
|
58
|
+
**3. Can it batch?** Some APIs take many ids in one call:
|
|
59
|
+
|
|
60
|
+
- Price simulation: `vtex.checkout.simulation({ items: [...] })` takes every SKU of the
|
|
61
|
+
shelf in one `items` array. Build the list, call once, then map results back by id.
|
|
62
|
+
- Master Data: `vtex.masterdata.search(entity, { where: "id=1 OR id=2 OR id=3" })`.
|
|
63
|
+
- Intelligent Search: one `vtex.search.products` call with a facet or query that selects
|
|
64
|
+
the set (a collection, a list of ids your store supports) instead of one search per item.
|
|
65
|
+
|
|
66
|
+
**4. Genuinely per item?** Then bound it. Cap the fan-out, keep the call off the critical
|
|
67
|
+
path (a `Lazy<T>` prop, or a client component that fetches when visible), and cache it
|
|
68
|
+
upstream (see `deco-storefront-caching`). Never `Promise.all` over a list you do not
|
|
69
|
+
control the length of.
|
|
70
|
+
|
|
71
|
+
## The N+1 that has no loop
|
|
72
|
+
|
|
73
|
+
Two sections each fetch the same product to derive the same facet, then run the same
|
|
74
|
+
faceted search. Inside each block it looks like one call. Across the page it is four.
|
|
75
|
+
That is a duplicate-call problem, not a loop. See [`request-dedupe.md`](./request-dedupe.md).
|
|
76
|
+
|
|
77
|
+
Do not "fix" it by switching to a different upstream API. On one store the tempting swap
|
|
78
|
+
(legacy Catalog to Intelligent Search) changed the shape of `product.category`, which the
|
|
79
|
+
facet was built from, so the shelf silently showed other products. Remove the duplicate
|
|
80
|
+
call you have.
|
|
81
|
+
|
|
82
|
+
## Find them
|
|
83
|
+
|
|
84
|
+
```bash
|
|
85
|
+
# upstream calls inside map/forEach/for in the site's code
|
|
86
|
+
grep -rnE "\.map\(\s*async|forEach\(\s*async" src/ .deco/index.ts
|
|
87
|
+
grep -rnE "for \(.*\) *\{" -A3 src/ | grep -n "await"
|
|
88
|
+
# who calls the thin clients
|
|
89
|
+
grep -rnE "\.(search|catalog|checkout|masterdata|io)\.[a-zA-Z]+\(" src/
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
## Verify
|
|
93
|
+
|
|
94
|
+
Count calls, do not eyeball the page. The method is in
|
|
95
|
+
[`request-dedupe.md`](./request-dedupe.md#count-the-calls): one log line per upstream
|
|
96
|
+
call in dev, or the `http.client.request.duration` metric in production. After the fix,
|
|
97
|
+
one page load shows one line per operation, not one per product. Then confirm the end
|
|
98
|
+
result with the `curl` timing in `SKILL.md`, on the same URL, cold and warm.
|
|
99
|
+
|
|
100
|
+
## Checklist
|
|
101
|
+
|
|
102
|
+
- [ ] No upstream call inside `.map(async` in a block function
|
|
103
|
+
- [ ] Specs and SKUs read from the product, not refetched
|
|
104
|
+
- [ ] Cross-selling called once per page
|
|
105
|
+
- [ ] Simulation batched into one `items` array
|
|
106
|
+
- [ ] Every `Promise.all` over external data has a bounded input
|
|
107
|
+
- [ ] Calls counted before and after
|
|
@@ -0,0 +1,130 @@
|
|
|
1
|
+
# Navigation: variant switches, prefetch, scroll and feedback
|
|
2
|
+
|
|
3
|
+
Load when: clicking a size or colour on the product page takes >500 ms; one variant click
|
|
4
|
+
makes two `/_serverFn/` requests; forward navigation keeps the old scroll position; a
|
|
5
|
+
click gives no feedback for seconds; hovering a grid of cards loads the upstream.
|
|
6
|
+
|
|
7
|
+
TanStack Start only. A client-side navigation in v8 calls the page server function (one
|
|
8
|
+
`/_serverFn/` request), which routes, resolves the page's blocks and calls the upstream,
|
|
9
|
+
the same work as a full page render.
|
|
10
|
+
|
|
11
|
+
## What you already have
|
|
12
|
+
|
|
13
|
+
- `createDecoRouter` turns on `scrollRestoration` and sets `defaultPreload: "intent"`
|
|
14
|
+
(prefetch on hover or focus). You can pass `defaultPreload` to change it.
|
|
15
|
+
- `DecoDocument` renders `NavigationProgress` (a bar at the top while the router loads)
|
|
16
|
+
and `StableOutlet` (keeps the content's height during a navigation, so the footer does
|
|
17
|
+
not jump). A site with its own document can import both from `@decocms/tanstack/react`.
|
|
18
|
+
|
|
19
|
+
## 1. Variant switches
|
|
20
|
+
|
|
21
|
+
Two kinds of "variant", two mechanics:
|
|
22
|
+
|
|
23
|
+
| Case | Data needed | Do |
|
|
24
|
+
|---|---|---|
|
|
25
|
+
| Same product, other SKU (size, voltage) | Already loaded: `product.isVariantOf.hasVariant` | Change the URL with `history.replaceState`: **zero requests** |
|
|
26
|
+
| Other product (a colour that is its own product) | A new product | Navigate: exactly one request, with a loading state |
|
|
27
|
+
|
|
28
|
+
A product page usually loads every SKU in the first render. A `?skuId=` in the URL is for
|
|
29
|
+
sharing and bookmarks. If the page route passes the search string to the page server
|
|
30
|
+
function, any change to it reloads the whole page. Do not route a same-product SKU change
|
|
31
|
+
through the router:
|
|
32
|
+
|
|
33
|
+
```tsx
|
|
34
|
+
const [current, setCurrent] = useState(() => relativeUrl(product.url));
|
|
35
|
+
|
|
36
|
+
const onVariant = useCallback((event: React.MouseEvent, href: string) => {
|
|
37
|
+
event.preventDefault();
|
|
38
|
+
setCurrent(href);
|
|
39
|
+
window.history.replaceState(null, "", href);
|
|
40
|
+
}, []);
|
|
41
|
+
|
|
42
|
+
<a href={href} onClick={(e) => onVariant(e, href)} aria-current={href === current}>
|
|
43
|
+
{label}
|
|
44
|
+
</a>
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
Use a plain `<a>` with `preventDefault`, not `<Link>`: a `<Link>` asks the router, and the
|
|
48
|
+
router fetches. The router does not see this URL change; that is the point. A reload or a
|
|
49
|
+
shared link opens the right SKU as long as the page reads `skuId` on the server.
|
|
50
|
+
|
|
51
|
+
### The double fetch
|
|
52
|
+
|
|
53
|
+
A `<Link to="…?skuId=160">` with prefetch on intent fires twice: hover prefetches one URL,
|
|
54
|
+
the click loads another (with a different search string), and the prefetched result is
|
|
55
|
+
not reused. On variant links, turn prefetch off: `<Link preload={false}>`. Prefetch is for
|
|
56
|
+
pages you do not have yet; a variant of the page you are on is not one.
|
|
57
|
+
|
|
58
|
+
## 2. Prefetch on dense grids
|
|
59
|
+
|
|
60
|
+
With `defaultPreload: "intent"`, moving the mouse across a listing page prefetches each
|
|
61
|
+
card's product page. Each one is a server function call that resolves a full page against
|
|
62
|
+
the upstream. On a grid of 48 cards that can be dozens of upstream page loads per visitor
|
|
63
|
+
who never clicks.
|
|
64
|
+
|
|
65
|
+
Measure it: record a HAR while you move the mouse over a grid, then count `/_serverFn/`
|
|
66
|
+
entries. Options, in order of preference:
|
|
67
|
+
|
|
68
|
+
1. Let the site's `pageCache` answer them. The worker calls it for server-function
|
|
69
|
+
requests too, so a cached product page costs no upstream. See `deco-storefront-caching`.
|
|
70
|
+
2. Turn prefetch off on card links only (`preload={false}`), and keep it on menus and
|
|
71
|
+
other links people hover with intent.
|
|
72
|
+
3. `createDecoRouter({ defaultPreload: false })`, and opt in per link.
|
|
73
|
+
|
|
74
|
+
## 3. Scroll to top on forward navigation
|
|
75
|
+
|
|
76
|
+
`scrollRestoration` restores the position on back and forward. If forward navigation (a
|
|
77
|
+
card click to a product page) sometimes leaves the new page scrolled down, scroll on
|
|
78
|
+
resolved navigations that are not history traversal:
|
|
79
|
+
|
|
80
|
+
```ts
|
|
81
|
+
// src/router.tsx, after createDecoRouter
|
|
82
|
+
if (typeof window !== "undefined") {
|
|
83
|
+
let lastAction: string | undefined;
|
|
84
|
+
router.history.subscribe(({ action }) => {
|
|
85
|
+
lastAction = action.type;
|
|
86
|
+
});
|
|
87
|
+
router.subscribe("onResolved", (event) => {
|
|
88
|
+
// PUSH and REPLACE are forward navigations; BACK, FORWARD and GO are restored by the router
|
|
89
|
+
if (event.pathChanged && (lastAction === "PUSH" || lastAction === "REPLACE")) {
|
|
90
|
+
window.scrollTo({ top: 0 });
|
|
91
|
+
}
|
|
92
|
+
});
|
|
93
|
+
}
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
Check that back still restores the old position after adding it.
|
|
97
|
+
|
|
98
|
+
## 4. Feedback on the clicked element
|
|
99
|
+
|
|
100
|
+
`NavigationProgress` is a thin bar. On product cards, a spinner over the clicked card is
|
|
101
|
+
clearer. `useRouterState` tells you a navigation to that card's path is pending:
|
|
102
|
+
|
|
103
|
+
```tsx
|
|
104
|
+
import { Link, useRouterState } from "@tanstack/react-router";
|
|
105
|
+
|
|
106
|
+
export function CardLink({ to, children, className }: { to: string; children: React.ReactNode; className?: string }) {
|
|
107
|
+
const pending = useRouterState({
|
|
108
|
+
select: (s) => s.isLoading && s.location.pathname === to && s.resolvedLocation?.pathname !== to,
|
|
109
|
+
});
|
|
110
|
+
return (
|
|
111
|
+
<Link to={to} className={`relative ${className ?? ""}${pending ? " pointer-events-none" : ""}`}>
|
|
112
|
+
{children}
|
|
113
|
+
{pending && <span className="absolute inset-0 grid place-items-center bg-white/60" aria-hidden>…</span>}
|
|
114
|
+
</Link>
|
|
115
|
+
);
|
|
116
|
+
}
|
|
117
|
+
```
|
|
118
|
+
|
|
119
|
+
Use it on the card image. On text links the overlay looks odd; the top bar is enough.
|
|
120
|
+
|
|
121
|
+
## Verify
|
|
122
|
+
|
|
123
|
+
Record a HAR (a script, so both runs click the same things) and count `/_serverFn/`
|
|
124
|
+
requests:
|
|
125
|
+
|
|
126
|
+
- Same-product variant click: **0**.
|
|
127
|
+
- Other-product variant click: **1**.
|
|
128
|
+
- Card click after hovering it: **1** in total, not 2.
|
|
129
|
+
|
|
130
|
+
Then time the click to the next paint in a Performance trace ([`trace-reading.md`](./trace-reading.md)).
|
|
@@ -0,0 +1,163 @@
|
|
|
1
|
+
# Payload trim: smaller Product graphs before they reach the HTML
|
|
2
|
+
|
|
3
|
+
Load when: a listing page's HTML is several MB; a `/_serverFn/` navigation response is
|
|
4
|
+
huge; the HTML holds thousands of `UnitPriceSpecification` entries; JSON-LD is large.
|
|
5
|
+
|
|
6
|
+
## Why the HTML is heavy
|
|
7
|
+
|
|
8
|
+
On TanStack Start, what a block returns becomes route loader data. It is serialised into
|
|
9
|
+
the HTML for hydration, and again into the `/_serverFn/` response of every client-side
|
|
10
|
+
navigation. On Next.js, props passed to client components go into the RSC payload. Every
|
|
11
|
+
field the block returns is shipped, whether a component reads it or not.
|
|
12
|
+
|
|
13
|
+
A VTEX `Product` (schema.org shape, `@decocms/compat-v7/commerce/types`) is mostly ballast
|
|
14
|
+
for a product card:
|
|
15
|
+
|
|
16
|
+
- `offers.offers[].priceSpecification`: one `UnitPriceSpecification` per installment plan,
|
|
17
|
+
often ~30 per offer.
|
|
18
|
+
- `isSimilarTo[]`: up to ~10 full `Product` graphs, for colour swatches.
|
|
19
|
+
- `additionalProperty`: dozens of entries.
|
|
20
|
+
- `image[]`: every image of the product.
|
|
21
|
+
|
|
22
|
+
Measured on a listing page of a VTEX store after trimming:
|
|
23
|
+
|
|
24
|
+
| | before | after |
|
|
25
|
+
|---|---|---|
|
|
26
|
+
| Raw HTML | 28.7 MB | 2.89 MB (−89.9%) |
|
|
27
|
+
| `UnitPriceSpecification` count | 63,744 | 585 (−99.1%) |
|
|
28
|
+
| `PropertyValue` count | 82,877 | 11,577 (−86.0%) |
|
|
29
|
+
| `ImageObject` count | 13,497 | 1,921 (−85.8%) |
|
|
30
|
+
|
|
31
|
+
## Rule: check every reader, then trim what nobody reads
|
|
32
|
+
|
|
33
|
+
List the components that read the product on that page and what each reads. A typical
|
|
34
|
+
listing:
|
|
35
|
+
|
|
36
|
+
| Reader | Reads | Keep |
|
|
37
|
+
|---|---|---|
|
|
38
|
+
| `useOffer` (`@decocms/compat-v7/commerce/sdk/useOffer`) | `offers.offers[0]`: price, availability, seller, the `ListPrice` spec and the best `Installment` | `ListPrice` + best `Installment` |
|
|
39
|
+
| Product card | name, url, `productID`, first image, some `additionalProperty`, `isVariantOf.hasVariant` for sizes | the card's fields; `hasVariant` |
|
|
40
|
+
| Colour swatches | on each `isSimilarTo[]`: availability, thumbnails, the colour property, `isVariantOf.productGroupID` | only those |
|
|
41
|
+
| Quick-buy size selector | each `hasVariant[]` offer: availability and its price specs | slimmed specs, not dropped |
|
|
42
|
+
| Product page | the whole graph | **do not trim** |
|
|
43
|
+
|
|
44
|
+
Your store's components may read more. Grep them before you remove a field.
|
|
45
|
+
|
|
46
|
+
## The trim functions
|
|
47
|
+
|
|
48
|
+
```ts
|
|
49
|
+
// src/sdk/productPayload.ts
|
|
50
|
+
import type {
|
|
51
|
+
AggregateOffer,
|
|
52
|
+
Product,
|
|
53
|
+
ProductListingPage,
|
|
54
|
+
UnitPriceSpecification,
|
|
55
|
+
} from "@decocms/compat-v7/commerce/types";
|
|
56
|
+
import { bestInstallment } from "@decocms/compat-v7/commerce/sdk/useOffer";
|
|
57
|
+
|
|
58
|
+
const LIST_PRICE = "https://schema.org/ListPrice";
|
|
59
|
+
const SWATCH_PROPS = new Set(["Color"]); // your store's colour property names
|
|
60
|
+
|
|
61
|
+
/** ListPrice plus the installment useOffer would pick, nothing else. */
|
|
62
|
+
const slimSpecs = (specs: UnitPriceSpecification[] = []): UnitPriceSpecification[] => {
|
|
63
|
+
const list = specs.find((s) => s.priceType === LIST_PRICE);
|
|
64
|
+
const best = specs.reduce(bestInstallment, null);
|
|
65
|
+
return [list, best].filter((s): s is UnitPriceSpecification => !!s);
|
|
66
|
+
};
|
|
67
|
+
|
|
68
|
+
const slimOffers = (agg: AggregateOffer | undefined, dropSpecs = false) => {
|
|
69
|
+
const first = agg?.offers?.[0];
|
|
70
|
+
if (!agg || !first) return agg;
|
|
71
|
+
return { ...agg, offers: [{ ...first, priceSpecification: dropSpecs ? [] : slimSpecs(first.priceSpecification) }] };
|
|
72
|
+
};
|
|
73
|
+
|
|
74
|
+
const isThumb = (img: { alternateName?: string; url?: string }) =>
|
|
75
|
+
/thumb/i.test(img.alternateName ?? "") || /thumb/i.test(img.url ?? "");
|
|
76
|
+
|
|
77
|
+
/** isSimilarTo[]: what a swatch reads. */
|
|
78
|
+
const slimSimilar = (p: Product): Product => {
|
|
79
|
+
const thumbs = p.image?.filter(isThumb);
|
|
80
|
+
return {
|
|
81
|
+
...p,
|
|
82
|
+
image: thumbs?.length ? thumbs : p.image?.slice(0, 1),
|
|
83
|
+
additionalProperty: p.additionalProperty?.filter((x) => SWATCH_PROPS.has(x.name ?? "")),
|
|
84
|
+
offers: slimOffers(p.offers, true), // swatches read availability only
|
|
85
|
+
isVariantOf: p.isVariantOf && ({ productGroupID: p.isVariantOf.productGroupID } as Product["isVariantOf"]),
|
|
86
|
+
isSimilarTo: undefined, // never nest: a later change would grow it geometrically
|
|
87
|
+
};
|
|
88
|
+
};
|
|
89
|
+
|
|
90
|
+
export const trimProductForCard = (p: Product): Product => ({
|
|
91
|
+
...p,
|
|
92
|
+
offers: slimOffers(p.offers),
|
|
93
|
+
isSimilarTo: p.isSimilarTo?.map(slimSimilar),
|
|
94
|
+
isVariantOf: p.isVariantOf && {
|
|
95
|
+
...p.isVariantOf,
|
|
96
|
+
hasVariant: p.isVariantOf.hasVariant?.map((v) => ({ ...v, offers: slimOffers(v.offers) })),
|
|
97
|
+
},
|
|
98
|
+
});
|
|
99
|
+
|
|
100
|
+
export const trimListingPage = (page: ProductListingPage | null) =>
|
|
101
|
+
page?.products?.length ? { ...page, products: page.products.map(trimProductForCard) } : page;
|
|
102
|
+
```
|
|
103
|
+
|
|
104
|
+
`bestInstallment` is the reducer `useOffer` uses, so the card shows the same installment
|
|
105
|
+
after the trim as before. The functions build new objects and never mutate their input.
|
|
106
|
+
That matters in v8: a block's result is shared by every place in the request that named
|
|
107
|
+
the same block with the same inputs, and the product page may be one of them.
|
|
108
|
+
|
|
109
|
+
Adapt the swatch filter (`isThumb`, `SWATCH_PROPS`) to what your store's components read.
|
|
110
|
+
Thumbnail naming differs between stores.
|
|
111
|
+
|
|
112
|
+
## Where to apply it
|
|
113
|
+
|
|
114
|
+
In the block function or vendored loader that returns the products for a card list, just
|
|
115
|
+
before it returns:
|
|
116
|
+
|
|
117
|
+
```ts
|
|
118
|
+
export async function productListingPage(props: Props) {
|
|
119
|
+
const page = await loadListing(props); // your mapping to schema.org
|
|
120
|
+
return trimListingPage(page);
|
|
121
|
+
}
|
|
122
|
+
```
|
|
123
|
+
|
|
124
|
+
- Every path that renders cards must trim: the first render, "load more", infinite scroll,
|
|
125
|
+
and any server function that returns products. A path you forget brings back the full
|
|
126
|
+
payload and breaks nothing visibly.
|
|
127
|
+
- Keep the product page on the full graph. Use a different block (or a prop) for cards.
|
|
128
|
+
- Trimming does not shrink an upstream cache that stores the raw VTEX response. It shrinks
|
|
129
|
+
the HTML, the `/_serverFn/` responses, and a page cache that stores either.
|
|
130
|
+
|
|
131
|
+
## JSON-LD on listing pages
|
|
132
|
+
|
|
133
|
+
Structured data is serialised too. A listing's JSON-LD is an `ItemList` of `ListItem` with
|
|
134
|
+
`url` and `position`; the full `Product` belongs on the product page. One store emitted a
|
|
135
|
+
`"Products"` type (not in schema.org, so no crawler read it) at 2.75 MB per listing page.
|
|
136
|
+
The `ItemList` form was 6,198 bytes. Feed the SEO block from the same loader block as the
|
|
137
|
+
page (so the client runs it once) and map to the small shape there.
|
|
138
|
+
|
|
139
|
+
## Personal data in the HTML
|
|
140
|
+
|
|
141
|
+
Never embed shopper data (cart, postal code, name, session) in server-rendered HTML or
|
|
142
|
+
loader data of a page that can be cached. One cached copy serves it to the next visitor.
|
|
143
|
+
Load it in a client component after hydration. Cache rules are in `deco-storefront-caching`.
|
|
144
|
+
|
|
145
|
+
## Verify
|
|
146
|
+
|
|
147
|
+
```bash
|
|
148
|
+
URL=https://www.example.com/some-listing
|
|
149
|
+
curl -s "$URL" | wc -c # raw HTML bytes
|
|
150
|
+
curl -s --compressed -o /dev/null -w '%{size_download}\n' "$URL" # bytes on the wire
|
|
151
|
+
curl -s "$URL" | grep -o UnitPriceSpecification | wc -l # bloat marker, should fall ~99%
|
|
152
|
+
```
|
|
153
|
+
|
|
154
|
+
Do the same for the navigation response: open the page, click to another listing, and
|
|
155
|
+
read the `/_serverFn/` response size in DevTools.
|
|
156
|
+
|
|
157
|
+
Visual checks after the trim:
|
|
158
|
+
|
|
159
|
+
- [ ] Cards show price, list price and installment text as before
|
|
160
|
+
- [ ] Colour swatches render and link to the right products
|
|
161
|
+
- [ ] The size selector disables out-of-stock sizes
|
|
162
|
+
- [ ] "Load more" and infinite scroll render trimmed cards correctly
|
|
163
|
+
- [ ] The product page is unchanged
|
|
@@ -0,0 +1,152 @@
|
|
|
1
|
+
# Render location: server work that is slow, wasted, or in the wrong place
|
|
2
|
+
|
|
3
|
+
Load when: TTFB is seconds while the HTML is small; a page resolves data it never
|
|
4
|
+
renders; you do not know which block is slow; the site carries thousands of redirects.
|
|
5
|
+
|
|
6
|
+
Lighthouse cannot see any of this. It shows up as one TTFB number with no audit
|
|
7
|
+
pointing at it. The browser timeline is clean; the server did the work.
|
|
8
|
+
|
|
9
|
+
## 1. Attribute the wait before you change anything
|
|
10
|
+
|
|
11
|
+
Time every block function for one run. The block map is a plain object of functions,
|
|
12
|
+
so wrap it where you create the CMS (not in `.deco/index.ts`, which `deco schema` reads):
|
|
13
|
+
|
|
14
|
+
```ts
|
|
15
|
+
// src/cms.ts — temporary, for a local or preview run
|
|
16
|
+
import { createCMS, type Blocks } from "@decocms/blocks";
|
|
17
|
+
import blocks from "../.deco";
|
|
18
|
+
|
|
19
|
+
const timed = (map: Blocks): Blocks =>
|
|
20
|
+
Object.fromEntries(
|
|
21
|
+
Object.entries(map).map(([name, fn]) => [
|
|
22
|
+
name,
|
|
23
|
+
async (input: unknown) => {
|
|
24
|
+
const t0 = performance.now();
|
|
25
|
+
try {
|
|
26
|
+
return await fn(input);
|
|
27
|
+
} finally {
|
|
28
|
+
console.log(`[block] ${Math.round(performance.now() - t0)}ms ${name}`);
|
|
29
|
+
}
|
|
30
|
+
},
|
|
31
|
+
]),
|
|
32
|
+
);
|
|
33
|
+
|
|
34
|
+
export const cms = createCMS({ blocks: timed(blocks), site: "my-store" });
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
The wrapper times only the function's own run: the resolver resolves a block's inputs
|
|
38
|
+
before it calls the function, so a nested block logs its own line. A block the client
|
|
39
|
+
already ran for the same inputs in this request logs nothing (it is a memo hit; see
|
|
40
|
+
[`request-dedupe.md`](./request-dedupe.md)). Sort the lines by ms. The ranking matters,
|
|
41
|
+
not the absolute numbers.
|
|
42
|
+
|
|
43
|
+
In production, the same data exists as telemetry spans: when a trace is sampled, every
|
|
44
|
+
block run becomes a span named after its block type, with `deco.block.type`. Sampling
|
|
45
|
+
is off by default. It needs a telemetry destination (a `token` or a `telemetry.endpoint`
|
|
46
|
+
on `createCMS`), the cap `createCMS({ telemetry: { limits: { traceSampleRate } } })`
|
|
47
|
+
(default 0), and `telemetry.traceSampleRate` in the saved `CMS` block (default 0).
|
|
48
|
+
|
|
49
|
+
## 2. A prop resolved eagerly and then thrown away
|
|
50
|
+
|
|
51
|
+
The resolver resolves every `__resolveType` in a block's inputs before it calls the
|
|
52
|
+
function, including branches the section will not render: a 404 fallback, a tab that
|
|
53
|
+
is closed, a modal, the hidden side of a flag.
|
|
54
|
+
|
|
55
|
+
Measured on a v7 product page: the "not found" fallback held a shelf whose products came
|
|
56
|
+
from a full-text search. It cost **1.7 s on every product page**, and the result was
|
|
57
|
+
discarded. v8 resolves inputs the same way, so the same content shape costs the same.
|
|
58
|
+
|
|
59
|
+
The fix in v8 is the built-in `lazy` block. Type the prop as `Lazy<T>` and call it only
|
|
60
|
+
on the branch that renders it:
|
|
61
|
+
|
|
62
|
+
```ts
|
|
63
|
+
import type { Lazy } from "@decocms/blocks";
|
|
64
|
+
|
|
65
|
+
interface Props {
|
|
66
|
+
product: Product | null;
|
|
67
|
+
notFoundShelf: Lazy<Product[]>; // content: { "__resolveType": "lazy", "value": { …the loader… } }
|
|
68
|
+
}
|
|
69
|
+
|
|
70
|
+
export async function productPage({ product, notFoundShelf }: Props) {
|
|
71
|
+
if (product) return { component: "pdp", props: { product } };
|
|
72
|
+
return { component: "not-found", props: { shelf: await notFoundShelf() } };
|
|
73
|
+
}
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
A `Lazy<T>` value resolves when called, at most once, with the same client. `deco schema`
|
|
77
|
+
turns a `Lazy<T>` field into a `lazy` block whose `value` is a `T`. `deco check` then
|
|
78
|
+
rejects content that puts a plain value in that field, and a `lazy` block in a field that
|
|
79
|
+
is not `Lazy<T>`, so the content has to change with the type. See `deco-site-authoring`
|
|
80
|
+
for writing lazy props with Suspense and skeletons.
|
|
81
|
+
|
|
82
|
+
Two more shapes with the same cost:
|
|
83
|
+
|
|
84
|
+
- **Blocks that render nothing** (theme fonts, an SEO section's JSON-LD input) still run
|
|
85
|
+
their data blocks. Type that prop `Lazy<T>` and wrap it in `lazy` in content, so
|
|
86
|
+
nothing is fetched until the function calls it.
|
|
87
|
+
- **Variants.** The built-in `multivariate` resolves rules in order, stops at the first
|
|
88
|
+
true one, and runs only that variant's `value`, which is a `Lazy`. A variant saved
|
|
89
|
+
without the `lazy` wrapper (`deco check` flags it) resolves eagerly when it comes
|
|
90
|
+
before the winner. Run `deco check` on migrated content.
|
|
91
|
+
|
|
92
|
+
## 3. Streamed blocks vs awaited blocks
|
|
93
|
+
|
|
94
|
+
In the example page route, each section block is its own promise, and only the SEO
|
|
95
|
+
block is awaited. TTFB is then routing plus the SEO block, and the slow sections stream
|
|
96
|
+
in afterwards. Check what your site does:
|
|
97
|
+
|
|
98
|
+
| Your route | TTFB is | Use it when |
|
|
99
|
+
|---|---|---|
|
|
100
|
+
| Awaits only routing and SEO | routing plus the SEO block | the default |
|
|
101
|
+
| Awaits every block | the slowest block | blocks read only in-memory content, or response headers depend on how blocks resolved |
|
|
102
|
+
| Awaits one block before starting the others | that block plus the rest | never: start every block first, then await |
|
|
103
|
+
|
|
104
|
+
The SEO block often needs the same product the main section needs. If both name the same
|
|
105
|
+
loader with the same inputs, the client runs it once and both get the result. If they
|
|
106
|
+
differ in one prop (a `count`, an extra facet), it runs twice. See `request-dedupe.md`.
|
|
107
|
+
|
|
108
|
+
Streaming has one trap on TanStack Start: a block promise still pending when the
|
|
109
|
+
document streams can reach the browser without settling, so the section never hydrates.
|
|
110
|
+
The check and the fix are in [`hydration.md`](./hydration.md).
|
|
111
|
+
|
|
112
|
+
## 4. A large Redirects block is paid on every request
|
|
113
|
+
|
|
114
|
+
`createDecoWorker` checks the CMS redirects on every non-asset `GET` or `HEAD` that is not a
|
|
115
|
+
server-function call. The check runs before `routes` and before your `pageCache`, so a
|
|
116
|
+
cache hit pays it too. Each check builds a new client, reads the `redirects` block
|
|
117
|
+
(a fresh copy of its rules), and `matchRoute` compiles the rules into a trie. The trie is
|
|
118
|
+
cached per array, and the array is new for each client. The page route reads the redirects
|
|
119
|
+
again with its own client, so a rendered page pays it twice.
|
|
120
|
+
|
|
121
|
+
Measured on a laptop with Bun, against this repo's `createCMS` and `matchRoute`, per
|
|
122
|
+
client (`redirects()` plus one `matchRoute`):
|
|
123
|
+
|
|
124
|
+
| Rules in the block | Cost per client |
|
|
125
|
+
|---|---|
|
|
126
|
+
| 1,000 | ~3 ms |
|
|
127
|
+
| 5,000 | ~13 ms |
|
|
128
|
+
| 20,000 | ~45 ms |
|
|
129
|
+
| 50,000 | ~120 ms |
|
|
130
|
+
|
|
131
|
+
A Worker isolate is slower than a laptop. If a migration folded a large redirect CSV into
|
|
132
|
+
`Redirects`, keep the editor-managed rules there and move the long tail to a point lookup:
|
|
133
|
+
a Workers KV namespace read by key in your `routes` handler (one `get` per request, never
|
|
134
|
+
`list`). The memory side of this is in [`worker-memory.md`](./worker-memory.md).
|
|
135
|
+
|
|
136
|
+
## 5. Bots get the same HTML as people
|
|
137
|
+
|
|
138
|
+
v8 has no deferred sections, so crawlers and browsers get the same document. Check what
|
|
139
|
+
that document carries for crawlers. One listing page emitted JSON-LD of type `"Products"`,
|
|
140
|
+
which does not exist in schema.org, so no crawler read it. It was **2.75 MB per listing
|
|
141
|
+
page**. A listing's JSON-LD is an `ItemList` of `ListItem` with `url` and `position`; the
|
|
142
|
+
full `Product` belongs on the product page. That change took the block from 2,474,206 to
|
|
143
|
+
6,198 bytes. More in [`payload-trim.md`](./payload-trim.md).
|
|
144
|
+
|
|
145
|
+
## Rules
|
|
146
|
+
|
|
147
|
+
- Small wire plus long wait means server work. Large wire plus short wait means payload.
|
|
148
|
+
- Do not move rendering to the client to win a number. Above-the-fold content and
|
|
149
|
+
anything a crawler must read stays on the server. This file is about work that is
|
|
150
|
+
discarded or repeated.
|
|
151
|
+
- Check one URL two or three times. A swing from 0.2 s to 3.6 s is a cold isolate or a
|
|
152
|
+
cache miss, not the page.
|