@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.
Files changed (210) hide show
  1. package/dist/index.d.ts +1 -1
  2. package/dist/index.d.ts.map +1 -1
  3. package/dist/index.js.map +1 -1
  4. package/dist/protocol/conformance/blockMetaVectors.json +80 -0
  5. package/dist/protocol/index.d.ts +5 -2
  6. package/dist/protocol/index.d.ts.map +1 -1
  7. package/dist/protocol/index.js +5 -2
  8. package/dist/protocol/index.js.map +1 -1
  9. package/dist/v8/blockMeta.d.ts +33 -4
  10. package/dist/v8/blockMeta.d.ts.map +1 -1
  11. package/dist/v8/blockMeta.js +70 -13
  12. package/dist/v8/blockMeta.js.map +1 -1
  13. package/dist/v8/cli/index.d.ts +1 -0
  14. package/dist/v8/cli/index.d.ts.map +1 -1
  15. package/dist/v8/cli/index.js +1 -0
  16. package/dist/v8/cli/index.js.map +1 -1
  17. package/dist/v8/cli/run.d.ts +2 -0
  18. package/dist/v8/cli/run.d.ts.map +1 -1
  19. package/dist/v8/cli/run.js +30 -1
  20. package/dist/v8/cli/run.js.map +1 -1
  21. package/dist/v8/cli/skills.d.ts +25 -0
  22. package/dist/v8/cli/skills.d.ts.map +1 -0
  23. package/dist/v8/cli/skills.js +70 -0
  24. package/dist/v8/cli/skills.js.map +1 -0
  25. package/dist/v8/client.d.ts +6 -4
  26. package/dist/v8/client.d.ts.map +1 -1
  27. package/dist/v8/client.js +26 -70
  28. package/dist/v8/client.js.map +1 -1
  29. package/dist/v8/cms.d.ts.map +1 -1
  30. package/dist/v8/cms.js +1 -2
  31. package/dist/v8/cms.js.map +1 -1
  32. package/dist/v8/contentIndex.d.ts +18 -7
  33. package/dist/v8/contentIndex.d.ts.map +1 -1
  34. package/dist/v8/contentIndex.js +46 -17
  35. package/dist/v8/contentIndex.js.map +1 -1
  36. package/dist/v8/draftChanges.d.ts.map +1 -1
  37. package/dist/v8/draftChanges.js +4 -1
  38. package/dist/v8/draftChanges.js.map +1 -1
  39. package/dist/v8/index.d.ts +1 -1
  40. package/dist/v8/index.d.ts.map +1 -1
  41. package/dist/v8/remoteLoader.d.ts +4 -2
  42. package/dist/v8/remoteLoader.d.ts.map +1 -1
  43. package/dist/v8/remoteLoader.js +13 -3
  44. package/dist/v8/remoteLoader.js.map +1 -1
  45. package/dist/v8/types.d.ts +47 -7
  46. package/dist/v8/types.d.ts.map +1 -1
  47. package/package.json +3 -2
  48. package/skills/deco-apps/SKILL.md +82 -0
  49. package/skills/deco-apps/references/algolia.md +51 -0
  50. package/skills/deco-apps/references/commerce-types.md +132 -0
  51. package/skills/deco-apps/references/instrumented-fetch.md +144 -0
  52. package/skills/deco-apps/references/magento.md +55 -0
  53. package/skills/deco-apps/references/messaging.md +76 -0
  54. package/skills/deco-apps/references/shopify.md +69 -0
  55. package/skills/deco-apps/references/vendored-loaders.md +135 -0
  56. package/skills/deco-apps/references/vtex-cookies-auth.md +146 -0
  57. package/skills/deco-apps/references/vtex.md +150 -0
  58. package/skills/deco-apps/references/wake.md +75 -0
  59. package/skills/deco-cms-schema/SKILL.md +80 -0
  60. package/skills/deco-cms-schema/references/annotations.md +147 -0
  61. package/skills/deco-cms-schema/references/content-hygiene.md +91 -0
  62. package/skills/deco-cms-schema/references/formats-and-widgets.md +112 -0
  63. package/skills/deco-cms-schema/references/shapes-that-break-the-form.md +165 -0
  64. package/skills/deco-cms-schema/references/types-to-fields.md +112 -0
  65. package/skills/deco-go-live/SKILL.md +127 -0
  66. package/skills/deco-go-live/references/content-releases.md +90 -0
  67. package/skills/deco-go-live/references/process.md +106 -0
  68. package/skills/deco-go-live/references/proxy-headers-checkout.md +139 -0
  69. package/skills/deco-go-live/references/qa-checklist-template.md +150 -0
  70. package/skills/deco-go-live/references/qa-inventory.md +120 -0
  71. package/skills/deco-go-live/references/react-spa.md +183 -0
  72. package/skills/deco-go-live/references/seo-analytics.md +114 -0
  73. package/skills/deco-go-live/references/traffic-ramp.md +87 -0
  74. package/skills/deco-go-live/references/worker-runtime.md +93 -0
  75. package/skills/deco-go-live/scripts/preflight.sh +221 -0
  76. package/skills/deco-images-media/SKILL.md +64 -0
  77. package/skills/deco-images-media/references/asset-upload.md +191 -0
  78. package/skills/deco-images-media/references/components-per-binding.md +167 -0
  79. package/skills/deco-images-media/references/providers-and-cdn.md +145 -0
  80. package/skills/deco-images-media/references/quality-and-lcp.md +93 -0
  81. package/skills/deco-images-media/references/troubleshooting.md +147 -0
  82. package/skills/deco-images-media/references/video.md +122 -0
  83. package/skills/deco-make-editable/SKILL.md +94 -0
  84. package/skills/deco-make-editable/references/a11y-and-e2e.md +104 -0
  85. package/skills/deco-make-editable/references/content-shapes.md +203 -0
  86. package/skills/deco-make-editable/references/from-figma.md +110 -0
  87. package/skills/deco-make-editable/references/i18n-fields.md +112 -0
  88. package/skills/deco-make-editable/references/inventory.md +79 -0
  89. package/skills/deco-make-editable/references/pixel-parity.md +175 -0
  90. package/skills/deco-make-editable/references/seeding-content.md +119 -0
  91. package/skills/deco-nextjs-site/SKILL.md +74 -0
  92. package/skills/deco-nextjs-site/references/caching.md +116 -0
  93. package/skills/deco-nextjs-site/references/metadata-seo.md +100 -0
  94. package/skills/deco-nextjs-site/references/proxy-and-drafts.md +177 -0
  95. package/skills/deco-nextjs-site/references/rendering.md +172 -0
  96. package/skills/deco-nextjs-site/references/setup.md +190 -0
  97. package/skills/deco-nextjs-site/references/studio-bridge.md +130 -0
  98. package/skills/deco-site-authoring/SKILL.md +75 -0
  99. package/skills/deco-site-authoring/references/lazy-blocks.md +155 -0
  100. package/skills/deco-site-authoring/references/loaders.md +192 -0
  101. package/skills/deco-site-authoring/references/pages.md +158 -0
  102. package/skills/deco-site-authoring/references/review-before-publish.md +95 -0
  103. package/skills/deco-site-authoring/references/sections.md +158 -0
  104. package/skills/deco-site-authoring/references/seo.md +116 -0
  105. package/skills/deco-site-workflow/SKILL.md +101 -0
  106. package/skills/deco-site-workflow/references/check.md +116 -0
  107. package/skills/deco-site-workflow/references/cli-reference.md +106 -0
  108. package/skills/deco-site-workflow/references/content-layout.md +93 -0
  109. package/skills/deco-site-workflow/references/content-sync.md +146 -0
  110. package/skills/deco-site-workflow/references/delivery.md +51 -0
  111. package/skills/deco-site-workflow/references/deploy.md +87 -0
  112. package/skills/deco-site-workflow/references/schema.md +173 -0
  113. package/skills/deco-site-workflow/references/serve-and-studio.md +138 -0
  114. package/skills/deco-storefront-caching/SKILL.md +67 -0
  115. package/skills/deco-storefront-caching/references/cache-keys.md +129 -0
  116. package/skills/deco-storefront-caching/references/case-study.md +82 -0
  117. package/skills/deco-storefront-caching/references/egress-traps.md +153 -0
  118. package/skills/deco-storefront-caching/references/nextjs.md +60 -0
  119. package/skills/deco-storefront-caching/references/perf-guardrails-e2e.md +123 -0
  120. package/skills/deco-storefront-caching/references/verification.md +136 -0
  121. package/skills/deco-storefront-caching/references/worker-page-cache.md +160 -0
  122. package/skills/deco-storefront-caching/scripts/html-anatomy.mjs +97 -0
  123. package/skills/deco-storefront-performance/SKILL.md +81 -0
  124. package/skills/deco-storefront-performance/references/cls-third-party.md +90 -0
  125. package/skills/deco-storefront-performance/references/hydration.md +116 -0
  126. package/skills/deco-storefront-performance/references/loaders-n-plus-1.md +107 -0
  127. package/skills/deco-storefront-performance/references/navigation-ux.md +130 -0
  128. package/skills/deco-storefront-performance/references/payload-trim.md +163 -0
  129. package/skills/deco-storefront-performance/references/render-location.md +152 -0
  130. package/skills/deco-storefront-performance/references/request-dedupe.md +147 -0
  131. package/skills/deco-storefront-performance/references/trace-reading.md +79 -0
  132. package/skills/deco-storefront-performance/references/worker-memory.md +176 -0
  133. package/skills/deco-tanstack-site/SKILL.md +68 -0
  134. package/skills/deco-tanstack-site/references/document-and-security.md +155 -0
  135. package/skills/deco-tanstack-site/references/router-and-navigation.md +137 -0
  136. package/skills/deco-tanstack-site/references/routes-and-pages.md +183 -0
  137. package/skills/deco-tanstack-site/references/server-functions.md +123 -0
  138. package/skills/deco-tanstack-site/references/setup.md +153 -0
  139. package/skills/deco-tanstack-site/references/worker-entry.md +152 -0
  140. package/skills/deco-v7-to-v8-migration/SKILL.md +123 -0
  141. package/skills/deco-v7-to-v8-migration/references/caching-and-privacy.md +10 -0
  142. package/skills/deco-v7-to-v8-migration/references/content.md +25 -0
  143. package/skills/deco-v7-to-v8-migration/references/editor-forms.md +27 -0
  144. package/skills/deco-v7-to-v8-migration/references/faststore.md +40 -0
  145. package/skills/deco-v7-to-v8-migration/references/framework-code.md +53 -0
  146. package/skills/deco-v7-to-v8-migration/references/hosted-releases.md +16 -0
  147. package/skills/deco-v7-to-v8-migration/references/import-map.md +81 -0
  148. package/skills/deco-v7-to-v8-migration/references/legacy-names.md +33 -0
  149. package/skills/deco-v7-to-v8-migration/references/manual-steps.md +10 -0
  150. package/skills/deco-v7-to-v8-migration/references/native-apps.md +43 -0
  151. package/skills/deco-v7-to-v8-migration/references/nextjs.md +19 -0
  152. package/skills/deco-v7-to-v8-migration/references/parity.md +66 -0
  153. package/skills/deco-v7-to-v8-migration/references/rendering.md +13 -0
  154. package/skills/deco-v7-to-v8-migration/references/running-the-script.md +29 -0
  155. package/skills/deco-v7-to-v8-migration/references/script-steps.md +13 -0
  156. package/skills/deco-v7-to-v8-migration/references/server-functions.md +15 -0
  157. package/skills/deco-v7-to-v8-migration/references/sibling-port.md +11 -0
  158. package/skills/deco-v7-to-v8-migration/references/site-code.md +15 -0
  159. package/skills/deco-v7-to-v8-migration/references/telemetry.md +10 -0
  160. package/skills/deco-v7-to-v8-migration/references/verify.md +23 -0
  161. package/skills/deco-v7-to-v8-migration/scripts/apps.ts +297 -0
  162. package/skills/deco-v7-to-v8-migration/scripts/asyncRendering.ts +73 -0
  163. package/skills/deco-v7-to-v8-migration/scripts/blockMap.ts +584 -0
  164. package/skills/deco-v7-to-v8-migration/scripts/checkContentReads.ts +32 -0
  165. package/skills/deco-v7-to-v8-migration/scripts/ciSchemaCheck.ts +145 -0
  166. package/skills/deco-v7-to-v8-migration/scripts/compat.ts +357 -0
  167. package/skills/deco-v7-to-v8-migration/scripts/content.ts +121 -0
  168. package/skills/deco-v7-to-v8-migration/scripts/contentReads.ts +157 -0
  169. package/skills/deco-v7-to-v8-migration/scripts/experiments.ts +81 -0
  170. package/skills/deco-v7-to-v8-migration/scripts/framework.ts +61 -0
  171. package/skills/deco-v7-to-v8-migration/scripts/imageCopy.ts +276 -0
  172. package/skills/deco-v7-to-v8-migration/scripts/imageModule.ts +285 -0
  173. package/skills/deco-v7-to-v8-migration/scripts/imports.ts +942 -0
  174. package/skills/deco-v7-to-v8-migration/scripts/invoke.ts +624 -0
  175. package/skills/deco-v7-to-v8-migration/scripts/legacyNames.ts +45 -0
  176. package/skills/deco-v7-to-v8-migration/scripts/main.ts +59 -0
  177. package/skills/deco-v7-to-v8-migration/scripts/matchers.ts +41 -0
  178. package/skills/deco-v7-to-v8-migration/scripts/migrate.ts +180 -0
  179. package/skills/deco-v7-to-v8-migration/scripts/redirects.ts +455 -0
  180. package/skills/deco-v7-to-v8-migration/scripts/report.ts +50 -0
  181. package/skills/deco-v7-to-v8-migration/scripts/scaffold.ts +1119 -0
  182. package/skills/deco-v7-to-v8-migration/scripts/secrets.ts +35 -0
  183. package/skills/deco-v7-to-v8-migration/scripts/sectionLoaders.ts +216 -0
  184. package/skills/deco-v7-to-v8-migration/scripts/siteSettings.ts +261 -0
  185. package/skills/deco-v7-to-v8-migration/scripts/stubs.ts +388 -0
  186. package/skills/deco-v7-to-v8-migration/scripts/tsconfig.json +7 -0
  187. package/skills/deco-v7-to-v8-migration/scripts/vendor.ts +249 -0
  188. package/skills/deco-v7-to-v8-migration/scripts/vtexInvoke.ts +240 -0
  189. package/skills/deco-v7-to-v8-migration/scripts/walk.ts +30 -0
  190. package/skills/deco-variants/SKILL.md +57 -0
  191. package/skills/deco-variants/references/caching-variants.md +63 -0
  192. package/skills/deco-variants/references/custom-matchers.md +83 -0
  193. package/skills/deco-variants/references/draft-preview.md +59 -0
  194. package/skills/deco-variants/references/experiments-and-campaigns.md +104 -0
  195. package/skills/deco-variants/references/multivariate.md +85 -0
  196. package/skills/deco-variants/references/v7-matchers.md +71 -0
  197. package/src/index.ts +1 -1
  198. package/src/protocol/conformance/blockMetaVectors.json +80 -0
  199. package/src/protocol/index.ts +8 -1
  200. package/src/v8/blockMeta.ts +75 -11
  201. package/src/v8/cli/index.ts +1 -0
  202. package/src/v8/cli/run.ts +35 -1
  203. package/src/v8/cli/skills.ts +91 -0
  204. package/src/v8/client.ts +32 -77
  205. package/src/v8/cms.ts +1 -2
  206. package/src/v8/contentIndex.ts +49 -19
  207. package/src/v8/draftChanges.ts +5 -1
  208. package/src/v8/index.ts +1 -1
  209. package/src/v8/remoteLoader.ts +13 -3
  210. package/src/v8/types.ts +48 -7
@@ -0,0 +1,147 @@
1
+ # Troubleshooting images
2
+
3
+ Start from the symptom. Most checks need two things: the `src` stored in the
4
+ content (in `.deco/blocks` or the loader's output) and the URL the page actually
5
+ requested (DevTools, Network, filter "Img").
6
+
7
+ | Symptom | Likely cause | Section |
8
+ |---|---|---|
9
+ | Every image on the site is a bit soft | No tier, or `low`, in `decoCdn` | [Soft everywhere](#soft-everywhere) |
10
+ | One banner is pixelated, worse on phones and Retina screens | Source has fewer pixels than the slot needs | [Undersized source](#undersized-source) |
11
+ | A full-width hero is soft only on wide screens | `sizes` default says 50vw | [Wrong sizes](#wrong-sizes) |
12
+ | Images are huge (MBs) and slow | Source passes through unresized | [Not resized](#not-resized) |
13
+ | 404 or 508 on `/image?…` | Bad `src` inside the CDN URL | [Broken CDN URLs](#broken-cdn-urls) |
14
+ | Image blocked, console shows a CSP error | Host missing from `img-src` | [providers-and-cdn.md](./providers-and-cdn.md#hosts-for-csp-and-preconnect) |
15
+ | Mobile crop looks wrong, desktop fine | `Source` ratios differ per breakpoint | [Mobile crop](#mobile-crop) |
16
+ | Page jumps as images load | Missing `width`/`height` | [quality-and-lcp.md](./quality-and-lcp.md#preloading-the-lcp-image) |
17
+
18
+ ## Soft everywhere
19
+
20
+ Look at the `quality` parameter on any requested `/image?…` URL.
21
+
22
+ - **No `quality` parameter**: the site's `decoCdn` has no `quality` option, so
23
+ the CDN default applies to every image. Set `decoCdn({ quality: "high" })`.
24
+ - **`quality=low`**: someone chose `low` site-wide. Raise it.
25
+ - **Not a Deco CDN URL at all**: the image came from a platform provider.
26
+ `vtexCatalogWebp` and `vtexFileManager` use VTEX's 1 to 10 scale (default
27
+ 8); `vtexCatalog`, `vtexCatalogFrame` and `shopifyCdn` ignore quality.
28
+
29
+ A site-wide tier change touches every image URL, so the CDN cache refills
30
+ once. That is expected.
31
+
32
+ ## Undersized source
33
+
34
+ The most common "distorted image" report is not stretching. It is a source with
35
+ fewer pixels than the slot needs on a high-density screen, upscaled by the
36
+ browser. Tell-tale sign: **sharp when the file is opened directly, pixelated on
37
+ the site.** Opening it shows its small native size; the site shows it larger.
38
+
39
+ **Mechanism.** `width` on `Image` or `Source` is the 1x CSS width. The srcset
40
+ also offers `2 × width`, and on a DPR 2 screen the browser takes that one. If
41
+ the uploaded file is smaller, the CDN or browser has to invent pixels. No
42
+ parameter fixes that: `quality: "original"` only adds bytes.
43
+
44
+ **Required source pixels = rendered CSS width × device pixel ratio.** Use 2x as
45
+ the target; most phones and laptops are DPR 2 or more.
46
+
47
+ ### Diagnose
48
+
49
+ 1. Measure the **original** file, not a resized URL. Take the `src` from the
50
+ content (before it went through `ImageUrl`) and download that:
51
+
52
+ ```bash
53
+ curl -sL "<original src>" -o /tmp/orig
54
+ sips -g pixelWidth -g pixelHeight /tmp/orig # macOS; or: identify /tmp/orig
55
+ ```
56
+
57
+ Measuring a `/image?width=1400…` URL reports 1400, the output size, which
58
+ hides the problem.
59
+ 2. Read the `width` on the component. Each `Source` has its own:
60
+
61
+ ```tsx
62
+ <Source media="(min-width: 1024px)" src={desktop} width={700} height={342} /> // needs 1400×684
63
+ <Source media="(max-width: 1023px)" src={mobile} width={375} height={184} /> // needs 750×368
64
+ ```
65
+ 3. Source width ≥ `width × 2`: sharp. Smaller: that is the bug. In one measured
66
+ case a 542px-wide file filled a slot that needed 1400px, a 2.6x upscale.
67
+
68
+ ### Fix
69
+
70
+ Upload a larger source, at least 2x the slot, in the slot's aspect ratio. Larger
71
+ is fine: the CDN downscales, which never blurs.
72
+
73
+ These do **not** fix it:
74
+
75
+ - Changing `width`/`height` on the component. The slot on screen is the same,
76
+ so the browser upscales anyway.
77
+ - `quality: "original"`. No detail is added. Go back to `"high"`.
78
+ - Shrinking the component with CSS. It only helps below half the source width,
79
+ and it changes the design everywhere the component is used.
80
+
81
+ No larger original? An AI upscaler can help. Choose a scale that clears the
82
+ target (3x on 542px gives 1626px, above 1400; 2x gives 1084px, below). Check
83
+ fine detail (text, logos, small product features) before shipping. A real
84
+ high-resolution photo is always better.
85
+
86
+ Then stop it from happening again: put the 2x size in the field's
87
+ `@description` (see [components-per-binding.md](./components-per-binding.md#image-fields-in-section-props)).
88
+
89
+ ### Explaining it to a non-technical stakeholder
90
+
91
+ > The image looks pixelated because the uploaded file is smaller than the space
92
+ > it fills. The banner needs 1400×684 px (750×368 px on mobile); the current file
93
+ > is 542×280 px, so the site has to stretch it. It looks sharp when you open the
94
+ > file because it is shown at its small original size there. Upload the image at
95
+ > the larger size, ideally the original high-resolution photo.
96
+
97
+ ## Wrong sizes
98
+
99
+ `Image` defaults `sizes` to `"(max-width: 768px) 100vw, 50vw"`. On a 1440px
100
+ screen that tells the browser a full-width hero is 720 CSS px wide, so it may
101
+ pick the 1x candidate. Set `sizes` to the real layout (see
102
+ [quality-and-lcp.md](./quality-and-lcp.md#sizes-and-the-srcset)).
103
+
104
+ ## Not resized
105
+
106
+ The requested URL equals the `src` in the content: no provider matched it.
107
+
108
+ - `imageUrl.isOptimizable(src)` returns false for it. Check in a test or a
109
+ console.
110
+ - `decoCdn()` without `sources` resizes only Deco-hosted URLs. For other hosts,
111
+ add the platform provider or use `decoCdn({ sources: "all" })`.
112
+ - A provider listed after `decoCdn({ sources: "all" })` never runs. Move it
113
+ earlier.
114
+ - `data:` URIs and empty strings are never resized, by design.
115
+ - On Next.js, a source no provider resizes goes to `fallback`, or is returned
116
+ unchanged. Pass `fallback: nextImageOptimizer` if you want Next to resize it.
117
+ - A relative path like `/assets/banner.jpg` is not a Deco-hosted URL, so the
118
+ default `decoCdn()` leaves it alone and the site serves the file as is. With
119
+ `sources: "all"` it becomes `src=/assets/banner.jpg` on the CDN. Check that the
120
+ CDN can serve such a URL before relying on it.
121
+
122
+ ## Broken CDN URLs
123
+
124
+ - **`src=image` or `src=<cdn>/image`**: an already-resized URL was resized
125
+ again by older code. v8 `decoCdn` unwraps these. If you still see them, some
126
+ code builds CDN URLs by hand; switch it to `imageUrl`.
127
+ - **508 on `assets.decocms.com` or `decoims.com`**: the `src` points back at
128
+ `decoims.com`, and the CDN fetches itself. `decoCdn` strips `decoims.com`
129
+ from sources when it is in `legacyHosts` (the default on those domains). With
130
+ a custom `legacyHosts: []` on `assets.decocms.com` and `sources: "all"`, a
131
+ `decoims.com` source is sent whole as `src=` and the loop comes back.
132
+ - **404 with a valid-looking `src`**: characters like `%`, `&`, `#`, `+` in a
133
+ file name. `decoCdn` escapes them only when it unwraps a nested URL; rename
134
+ such files when you upload them. The v8 upload endpoint already does (see
135
+ [asset-upload.md](./asset-upload.md)).
136
+ - **The query string on the source disappeared**: `decoCdn` drops everything
137
+ after `?` in `src`. A source that needs its query (signed URLs) must not go
138
+ through `decoCdn`; give it its own provider or leave it unmatched.
139
+
140
+ ## Mobile crop
141
+
142
+ A `Picture` has a `Source` per media query, each with its own `width` and
143
+ `height`, so the ratio can differ. With `fit: "cover"` (the default) the CDN
144
+ crops to that ratio. A common bug: desktop is 700×342 (about 2:1) and mobile
145
+ is 350×350, so the mobile photo is cropped to a square. Decide the intended
146
+ mobile shape by looking at the live mobile render (emulate the device and DPR,
147
+ take a screenshot), then make the `Source` and the uploaded file agree.
@@ -0,0 +1,122 @@
1
+ # Video
2
+
3
+ v8 ships **no `Video` component**. Neither `@decocms/tanstack` nor
4
+ `@decocms/nextjs` has one, and `@decocms/blocks/image` is for images only.
5
+ Render a plain `<video>`.
6
+
7
+ Two layers decide whether a video plays with sound, and they are independent:
8
+
9
+ 1. **The file.** Does the served file contain an audio track? For videos on the
10
+ Deco media host, that depends on the URL (below).
11
+ 2. **The player.** Is the `<video>` muted, and does it autoplay? That is HTML
12
+ attributes and browser policy.
13
+
14
+ ## The media host strips audio by default
15
+
16
+ Videos uploaded to Deco and served from `decoims.com` come without the audio
17
+ track unless the URL asks for it. This is behavior of the media host, not of the
18
+ v8 packages, so verify it on your URL (below).
19
+
20
+ | URL | Audio track | Size in one measured case |
21
+ |---|---|---|
22
+ | `…/video.mp4` | removed | 3.08 MB |
23
+ | `…/video.mp4?muted=true` | removed | 3.08 MB |
24
+ | `…/video.mp4?muted=false` | present | 3.59 MB |
25
+
26
+ The silent version is a different, smaller file. No player setting brings sound
27
+ back to it. Each variant is cached under its own URL, so switching to
28
+ `?muted=false` fetches a separate file with no cache-busting needed.
29
+
30
+ Verify with two requests and compare sizes:
31
+
32
+ ```bash
33
+ curl -sI "<video url>" | grep -i content-length
34
+ curl -sI "<video url>?muted=false" | grep -i content-length
35
+ ```
36
+
37
+ The `?muted=false` response should be larger.
38
+
39
+ ## Do not send video through `ImageUrl`
40
+
41
+ `decoCdn` builds `https://<domain>/image?…&src=<path>` and keeps only the part
42
+ of `src` before `?`. A video passed to `Image`, `useImageUrl()` or the next/image
43
+ loader becomes an image request and loses `?muted=false`. Use the stored URL
44
+ as is.
45
+
46
+ ## Browser autoplay
47
+
48
+ Browsers block autoplay with sound in most cases; muted video autoplays. To
49
+ play with sound, plan for a user action (a click on `controls` or your own
50
+ button). This is browser policy; no URL or attribute changes it.
51
+
52
+ | Goal | File URL | `<video>` attributes |
53
+ |---|---|---|
54
+ | Silent background loop | default (no param) | `autoPlay muted loop playsInline` |
55
+ | Plays with sound when the user starts it | `?muted=false` | `controls`, no `autoPlay` |
56
+ | Autoplays silently, user can unmute | `?muted=false` | `autoPlay muted loop playsInline` plus a button that sets `video.muted = false` |
57
+
58
+ `playsInline` stops iOS from going fullscreen on play.
59
+
60
+ ```tsx
61
+ import type { ImageWidget, VideoWidget } from "@decocms/compat-v7/types/widgets";
62
+ import { useImageUrl } from "@decocms/tanstack/react";
63
+
64
+ interface Props {
65
+ /** @description MP4 or WebM */
66
+ video: VideoWidget;
67
+ poster?: ImageWidget;
68
+ sound?: boolean;
69
+ }
70
+
71
+ function withSound(src: string) {
72
+ if (!/^https?:\/\//.test(src)) return src; // relative paths: leave alone
73
+ const url = new URL(src);
74
+ url.searchParams.set("muted", "false");
75
+ return url.href;
76
+ }
77
+
78
+ export default function HeroVideo({ video, poster, sound }: Props) {
79
+ const imageUrl = useImageUrl();
80
+ return (
81
+ <video
82
+ src={sound ? withSound(video) : video}
83
+ poster={poster ? imageUrl(poster, { width: 1280, height: 720 }) : undefined}
84
+ width={1280}
85
+ height={720}
86
+ autoPlay
87
+ muted
88
+ loop
89
+ playsInline
90
+ preload="metadata"
91
+ />
92
+ );
93
+ }
94
+ ```
95
+
96
+ Notes on the example:
97
+
98
+ - `withSound` only makes sense for media-host URLs. Other hosts may ignore or
99
+ reject the parameter.
100
+ - The poster is an image, so it does go through `ImageUrl`.
101
+ - `width` and `height` reserve the box, as with images.
102
+ - `preload="metadata"` avoids downloading the whole file before play. For a
103
+ hero video that is the LCP element, consider the poster as the LCP image and
104
+ preload that instead.
105
+
106
+ ## Video fields
107
+
108
+ `VideoWidget` (from `@decocms/compat-v7/types/widgets`) or `@format video-uri`
109
+ on a string gives the field a video picker. `deco check` accepts any string
110
+ there, so it will not catch a broken video URL.
111
+
112
+ ## "The video has no sound"
113
+
114
+ 1. **Check the URL.** If it is a media-host URL without `?muted=false`, the
115
+ served file has no audio. Add the parameter.
116
+ 2. **Check the player.** If the URL has `?muted=false` and it is still silent,
117
+ the element is `muted` (required for autoplay). Add `controls` or an unmute
118
+ button.
119
+ 3. **Check the code path.** If the rendered `src` is an `/image?…` URL, the
120
+ video went through `ImageUrl`. Render the stored URL directly.
121
+ 4. **Verify** by opening the `?muted=false` URL in a tab: it should play with
122
+ sound.
@@ -0,0 +1,94 @@
1
+ ---
2
+ name: deco-make-editable
3
+ description: "@decocms/blocks 8: turn a hardcoded site, or a Figma design, into blocks that people edit in deco Studio, without changing how the site looks. Covers the inventory of content vs interface, the three content shapes (global blocks read by name, composed pages of type page, collections read with client.entries), the foo/fooPt bilingual field convention, seeding .deco/blocks from the existing code and sending it with deco push --draft and deco check --draft, implementing sections from a Figma file with the Figma MCP tools, pixel-parity checks with Playwright, accessibility and functional checks, and working in small PRs. Load it when asked to make a site, page, menu, footer or landing editable in Studio, to move hardcoded text into the CMS, to handle two languages in CMS content, or to build a Figma design as editable sections on a v8 site."
4
+ ---
5
+
6
+ # Make a site editable in Studio
7
+
8
+ The goal is not "move strings into JSON". It is two things at once:
9
+
10
+ 1. Someone who is not a developer opens Studio, changes a text, a link or the
11
+ order of sections, publishes, and the site changes.
12
+ 2. The site renders exactly as it did before the conversion.
13
+
14
+ Every step serves one of those two halves. The same method works when the
15
+ starting point is a Figma file instead of a hardcoded site: build the sections
16
+ from the design, then seed them with the design's content.
17
+
18
+ This skill is about method. For the v8 mechanics it relies on, load the skill
19
+ that owns them:
20
+
21
+ - `deco-site-authoring`: writing sections, pages and loaders.
22
+ - `deco-cms-schema`: how a `Props` type becomes the Studio form (JSDoc tags,
23
+ widgets, shapes that break the form).
24
+ - `deco-site-workflow`: the `deco` CLI, where content lives, drafts and
25
+ publishing, and what to check when Studio cannot see the site.
26
+ - `deco-tanstack-site` or `deco-nextjs-site`: the routes and the worker.
27
+
28
+ ## When to load what
29
+
30
+ | Reference | Load it when |
31
+ |---|---|
32
+ | [`references/inventory.md`](./references/inventory.md) | Starting: deciding what goes to the CMS, what stays in code, and the order of PRs |
33
+ | [`references/content-shapes.md`](./references/content-shapes.md) | Choosing between a global block, a composed page and a collection, and wiring each one |
34
+ | [`references/i18n-fields.md`](./references/i18n-fields.md) | The site has two languages and the content must be edited in both |
35
+ | [`references/seeding-content.md`](./references/seeding-content.md) | Writing the first `.deco/blocks` files from the current code, sending them as a draft, and the order of publish and deploy |
36
+ | [`references/from-figma.md`](./references/from-figma.md) | The starting point is a Figma file: mapping frames to sections, tokens, assets |
37
+ | [`references/pixel-parity.md`](./references/pixel-parity.md) | Proving a PR changes nothing visible: HTML diff, screenshot diff, Figma comparison, live edit |
38
+ | [`references/a11y-and-e2e.md`](./references/a11y-and-e2e.md) | Before calling a section or a page done: accessibility and functional checks |
39
+
40
+ ## The loop, per content area
41
+
42
+ Work in small PRs, one content area at a time (menu, then home, then
43
+ landings). Each PR goes through the same loop:
44
+
45
+ 1. **Inventory** the area: which texts, links and lists are content.
46
+ 2. **Shape** each piece: global block, composed page or collection.
47
+ 3. **Type** the props and add the block to the block map (`.deco/index.ts`, or
48
+ `.deco/index.tsx` when it holds JSX). Run `deco schema`.
49
+ 4. **Seed** `.deco/blocks` from the current code, never by retyping.
50
+ 5. **Check** with `deco check` (content in git, no `DECO_SITE`) or
51
+ `deco push --draft=<name>` then `deco check --draft=<name>` (a hosted site).
52
+ 6. **Prove parity**: the page on the branch and on `main` render the same
53
+ HTML and the same pixels, at desktop and mobile widths, in every language.
54
+ 7. **Live edit**: change the content and see the change land on the right
55
+ page and language only.
56
+
57
+ A PR that is not pixel-identical to `main` does not merge. That rule is what
58
+ lets a conversion run for weeks without anyone noticing it on the live site.
59
+
60
+ ## v8 facts this skill relies on
61
+
62
+ These are true of the packages in this repo and change how the v7 version of
63
+ this method worked.
64
+
65
+ - **Studio lists only what the block map lists.** A block type exists because
66
+ `.deco/index.ts` exports a function under that key. Components that are not
67
+ in the map never show up in Studio's section picker, so there is no folder
68
+ to keep clean.
69
+ - **The form comes from the function's input type.** `deco schema` reads the
70
+ first parameter's type of each function in the map and writes
71
+ `.deco/schema.gen.json`. A function that returns JSX or a
72
+ `{ component, props }` descriptor is a section; one that returns its own
73
+ input is content (grouped with pages when the type extends `Route`).
74
+ - **Block functions get only their saved input.** `currentClient()` inside one
75
+ knows the visitor and the version, not the URL. Anything that depends on the
76
+ path (such as the language) is added by the site's code that renders the
77
+ result, not by the block function.
78
+ - **Results are read-only.** A client runs each block function once per
79
+ distinct input and hands the same object to every place that uses it. Copy
80
+ before you change a result (the `localize` helper in
81
+ [i18n-fields.md](./references/i18n-fields.md) builds a new object).
82
+ - **There is no locale in the CMS.** Two languages are a site convention (see
83
+ [i18n-fields.md](./references/i18n-fields.md)).
84
+ - **The CLI has no asset upload command.** How images get to the site is
85
+ covered in `deco-images-media`.
86
+
87
+ ## Rules for this skill
88
+
89
+ - Never retype content. Extract it from the code with a script.
90
+ - No fallback copy of the content in code. A constant fallback becomes a
91
+ second source of truth that drifts from what editors see.
92
+ - Do not publish a draft (`deco publish`) without the site owner's explicit
93
+ OK for that publish.
94
+ - Anything specific to one store goes in that store's own notes, not here.
@@ -0,0 +1,104 @@
1
+ # Accessibility and functional checks
2
+
3
+ Pixel parity proves a section looks right with today's content. These checks
4
+ prove it works, for every visitor, and keeps working when editors change the
5
+ content.
6
+
7
+ Deeper checklists live in other skills; this file lists what a conversion or a
8
+ Figma build must not skip:
9
+
10
+ - `deco-go-live`: a QA checklist built from the site's blocks and routes.
11
+ - `deco-images-media` and `deco-storefront-performance`: images, LCP, CLS,
12
+ heavy HTML.
13
+
14
+ ## Content robustness
15
+
16
+ Editors will do things the design never showed. For each section, try:
17
+
18
+ - every optional field empty: no empty heading tag, no dangling separator, no
19
+ broken layout;
20
+ - a text three times longer than the design's, and a one-word one;
21
+ - a list with zero items, one item, and more items than the design shows;
22
+ - a section removed, and the same section added twice to one page;
23
+ - an image with a different aspect ratio than the design's.
24
+
25
+ A section that renders nothing when its main content is empty is better than
26
+ one that renders an empty box. A section added twice must not reuse an `id`
27
+ (two `id="faq"` break anchors and `aria-controls`).
28
+
29
+ ## Accessibility
30
+
31
+ - **Headings:** one `h1` per page, then `h2` and `h3` in order. A section's
32
+ heading level must not depend on where an editor puts it: when a section can
33
+ be first on a page (and become the `h1`), give it a prop for the level or
34
+ keep the `h1` in a section that only goes first.
35
+ - **Images:** every content image has `alt` text, and the `alt` is a field
36
+ next to the image in the form. Decorative images have `alt=""`.
37
+ - **Links and buttons:** every icon-only control has an accessible name
38
+ (`aria-label`, kept in code). Links that open a new tab say so to screen
39
+ readers.
40
+ - **Contrast:** WCAG AA, 4.5:1 for normal text, 3:1 for large text and UI
41
+ parts. When editors choose colors or put text over an image they choose,
42
+ contrast is their choice: add an overlay or a text color option to the
43
+ section instead of trusting each image.
44
+ - **Keyboard:** every interactive element is reachable with Tab, shows a
45
+ visible focus ring, and works with Enter or Space. Menus and drawers close
46
+ with Escape and return focus to the button that opened them.
47
+ - **Language:** `<html lang>` matches the page's language on a two-language
48
+ site (`DecoDocument` takes a `lang` prop on TanStack Start).
49
+ - A skip link to the main content, when the header has many links.
50
+
51
+ Run an automated pass (axe or Lighthouse) on each converted page as a floor,
52
+ not as proof.
53
+
54
+ ## Functional checks
55
+
56
+ Walk each converted page on desktop (1440px) and mobile (375px or 390px).
57
+
58
+ **Header and navigation**
59
+
60
+ - The logo links home. Every menu link goes where its `href` says, with the
61
+ locale prefix on secondary-language pages.
62
+ - Dropdowns or mega menus open on hover and on keyboard focus.
63
+ - Mobile: the menu button opens the drawer, nested items expand and collapse,
64
+ the drawer closes on navigation and on a backdrop tap.
65
+ - A sticky header does not cover anchored headings (`scroll-margin-top`).
66
+
67
+ **Content sections**
68
+
69
+ - Calls to action link to the right page. External links open in a new tab.
70
+ - Carousels: arrows and dots work, swipe works on mobile, autoplay stops on
71
+ hover and focus.
72
+ - Accordions and tabs work with the keyboard.
73
+ - Forms (newsletter, contact) submit, show success and error states, and
74
+ keep their messages in code, not in a block.
75
+
76
+ **Footer**
77
+
78
+ - Every link column renders and links work. Social and payment icons render.
79
+ - Mobile: columns stack or collapse as designed.
80
+
81
+ **Mobile**
82
+
83
+ - Touch targets are at least 44×44px.
84
+ - No horizontal scroll at 375px.
85
+ - Body text is at least 16px.
86
+ - Fixed or sticky bars do not hide content.
87
+
88
+ ## Performance, briefly
89
+
90
+ - The page's LCP image uses `preload`; every other image loads lazily.
91
+ - Every image has `width` and `height`, so nothing shifts while it loads.
92
+ - Deferring sections far below the fold (the built-in `lazy` block, loading
93
+ skeletons) is covered in `deco-site-authoring`.
94
+ - Compare the HTML size of a converted page with `main`. Content from a block
95
+ should not make a page heavier than the hardcoded version.
96
+
97
+ ## Automate what you repeat
98
+
99
+ When a check runs on every PR (menu links, the mobile drawer, the CTA
100
+ targets), write it as a Playwright test against the dev server. Keep the tests
101
+ on behavior and roles (`getByRole("navigation")`, `getByRole("button", { name:
102
+ "Open menu" })` for interface text kept in code), not on CSS classes or
103
+ positions, so an editor reordering sections or rewording a heading does not
104
+ break them.
@@ -0,0 +1,203 @@
1
+ # The three content shapes
2
+
3
+ Every piece of content from the [inventory](./inventory.md) takes one of three
4
+ shapes. Pick the shape first; the code follows from it.
5
+
6
+ | Shape | Use for | Saved as | Read with |
7
+ |---|---|---|---|
8
+ | **Global block** | Things on every page: header menu, footer, a top banner | One saved block with a fixed name, e.g. `.deco/blocks/Header%20menu.json` | `client.resolve("Header menu")` in a loader shared by every page |
9
+ | **Composed page** | Pages editors rearrange: home, landings | A saved block of type `page` with `name`, `path`, `seo` and `sections` | `client.routes()` + `matchRoute`, then `client.resolve(name)` |
10
+ | **Collection** | Many documents of one kind: articles, FAQ entries, store addresses | One saved block per document, all of one type | `client.entries(type)` for names and paths (index only), then `client.resolve(name)` per document shown |
11
+
12
+ A saved block's file name is `encodeURIComponent(name) + ".json"`, so the
13
+ block named `Header menu` lives in `Header%20menu.json`. Subfolders of
14
+ `.deco/blocks` are not read. A saved block cannot take the name of a block
15
+ type or a built-in (`page`, `lazy`, `multivariate`, …): `deco check` reports
16
+ it.
17
+
18
+ The site wiring around these (the client, the catch-all route, the worker) is
19
+ in `deco-tanstack-site` or `deco-nextjs-site`. The examples below assume a
20
+ TanStack Start site with `src/cms.ts` exporting `cms` from `createCMS`, as in
21
+ `examples/tanstack-worker-smoke`.
22
+
23
+ ## Sections: JSX or descriptors
24
+
25
+ A block function that returns JSX, or a `{ component, props }` object, is a
26
+ section: Studio offers it wherever a section fits. `tanstack-smoke` and
27
+ `tanstack-worker-smoke` in `examples/` return descriptors, because a server
28
+ function's result must be serialized; the site maps each descriptor to its
29
+ component when it renders. The Next.js examples and `tanstack-rsc-smoke`
30
+ (server components) return JSX from the block map (`.deco/index.tsx`).
31
+
32
+ ```ts
33
+ // .deco/index.ts
34
+ import type { Blocks, Seo } from "@decocms/blocks";
35
+ import type { HeaderMenuProps } from "../src/sections/HeaderMenu";
36
+ import type { HeroProps } from "../src/sections/Hero";
37
+
38
+ export type Section =
39
+ | { component: "header-menu"; props: HeaderMenuProps }
40
+ | { component: "hero"; props: HeroProps };
41
+
42
+ export default {
43
+ seo: (input: Seo) => input,
44
+ "header-menu": (input: HeaderMenuProps): Section => ({ component: "header-menu", props: input }),
45
+ hero: (input: HeroProps): Section => ({ component: "hero", props: input }),
46
+ } satisfies Blocks;
47
+ ```
48
+
49
+ Run `deco schema` after every change to a `Props` type, and commit the
50
+ regenerated `.deco/schema.gen.json`. In CI, `deco schema --check` fails when
51
+ the file is out of date.
52
+
53
+ ## Global blocks
54
+
55
+ One saved block per piece, named for what editors call it:
56
+
57
+ ```json
58
+ // .deco/blocks/Header%20menu.json
59
+ {
60
+ "__resolveType": "header-menu",
61
+ "links": [
62
+ { "label": "Pricing", "href": "/pricing" },
63
+ { "label": "Docs", "href": "/docs" }
64
+ ]
65
+ }
66
+ ```
67
+
68
+ Read it once per request, in a loader every page shares (the root route on
69
+ TanStack Start), and hand the result to the layout:
70
+
71
+ ```ts
72
+ // src/global-blocks.functions.ts
73
+ import { createServerFn } from "@tanstack/react-start";
74
+ import { contentClient } from "@decocms/tanstack/server";
75
+ import type { Section } from "../.deco";
76
+ import { cms } from "./cms";
77
+
78
+ const GLOBAL_BLOCKS = ["Header menu", "Footer"] as const;
79
+
80
+ export const loadGlobalBlocks = createServerFn({ method: "GET" }).handler(async () => {
81
+ const client = contentClient(cms);
82
+ const results = await Promise.all(GLOBAL_BLOCKS.map((name) => client.resolve<Section>(name)));
83
+ return Object.fromEntries(
84
+ GLOBAL_BLOCKS.map((name, i) => {
85
+ const [value, error] = results[i]!;
86
+ if (error) console.error(name, error);
87
+ return [name, value ?? null];
88
+ }),
89
+ ) as Record<(typeof GLOBAL_BLOCKS)[number], Section | null>;
90
+ });
91
+ ```
92
+
93
+ What held up in practice:
94
+
95
+ - **List the global block names in one place.** A missing block then shows up
96
+ as one `null` you can test for, not as a header that silently renders empty.
97
+ - **No fallback copy in code.** When a block cannot be read, render nothing (or
98
+ the section's empty state) and log the error. A constant with the old menu
99
+ becomes a second source of truth that drifts from what editors see.
100
+ - **Derive what editors should not manage.** The active menu item comes from
101
+ comparing `href` with the current path, not from an extra field.
102
+ - **External links** in CMS lists still need `target="_blank"` and
103
+ `rel="noopener noreferrer"`. Set them in the component from the URL, not
104
+ from a field editors can forget.
105
+
106
+ ## Composed pages
107
+
108
+ A page is a saved block of the built-in type `page`. Its `sections` are the
109
+ blocks editors add, remove and reorder:
110
+
111
+ ```json
112
+ // .deco/blocks/Home.json
113
+ {
114
+ "__resolveType": "page",
115
+ "name": "Home",
116
+ "path": "/",
117
+ "seo": { "__resolveType": "seo", "title": "…", "description": "…" },
118
+ "sections": [
119
+ { "__resolveType": "hero", "title": "…", "cta": { "label": "…", "href": "/start" } },
120
+ { "__resolveType": "guides", "items": [] }
121
+ ]
122
+ }
123
+ ```
124
+
125
+ The page loader in `examples/tanstack-worker-smoke/src/open-page.server.ts`
126
+ does the rest: `client.routes()` lists every page's `{ name, path }` from the
127
+ index, `matchRoute(href, { routes })` picks one, and `client.resolve(name, {
128
+ run: false })` reads it, then each section resolves on its own so a slow one
129
+ does not hold the others. `deco-tanstack-site` covers the catch-all route that
130
+ calls it.
131
+
132
+ **Keep your routes.** You do not have to hand the whole site to a catch-all
133
+ route to get CMS pages. A site with content files, locale prefixes or
134
+ redirects of its own can keep its file routes and call the same page loader
135
+ only in the routes that are now CMS pages (`loadPage({ data: { href: "/" } })`
136
+ in `src/routes/index.tsx`). On TanStack Router a file route such as `/` ranks
137
+ above the `$` catch-all, so converting one route never changes the others.
138
+
139
+ **Keep the frame in code.** The header and footer around a page stay in the
140
+ layout, fed by global blocks. A page's `sections` hold only what changes from
141
+ page to page.
142
+
143
+ **Render no wrapper you did not have.** The site writes the loop that renders
144
+ each section. If the old page had no element around each section, do not add
145
+ one: an extra `<div>` breaks CSS such as `.page > section` and fails the
146
+ [HTML parity](./pixel-parity.md) check.
147
+
148
+ **The tab title can come from the page.** The `page` block's `seo` field takes
149
+ any block that returns a `Seo` (`{ title, description }`), such as the `seo`
150
+ block in the map above. A page without one falls back to the root route's
151
+ defaults.
152
+
153
+ ## Collections
154
+
155
+ A collection is a block type whose function returns its own input, with one
156
+ saved block per document:
157
+
158
+ ```ts
159
+ // src/post.ts
160
+ import type { Route } from "@decocms/blocks";
161
+
162
+ export interface Post extends Route {
163
+ /**
164
+ * @title Published on
165
+ * @format date
166
+ */
167
+ date: string;
168
+ /** @format rich-text */
169
+ body: string;
170
+ }
171
+
172
+ // .deco/index.ts
173
+ post: (input: Post) => input,
174
+ ```
175
+
176
+ Because `Post` extends `Route` (`name` and `path`), `deco schema` puts the
177
+ type in the `pages` group and `deco check` reports two posts with conflicting
178
+ paths. A type without `path` is plain content that only the site's code reads.
179
+
180
+ `client.routes()` lists only blocks of type `page`, not posts. To give each
181
+ post its own URL, list the posts and match them together with the pages, as
182
+ `examples/nextjs-binding-smoke/src/open-page.server.ts` does:
183
+ `matchRoute(href, { routes: [...routes, ...posts] })`.
184
+
185
+ List them with `client.entries`, which reads only the content index (names,
186
+ types, paths, references, `noIndex`), and resolve the documents you show:
187
+
188
+ ```ts
189
+ const [entries, error] = await client.entries("post");
190
+ if (error) throw error;
191
+ const posts = await Promise.all(
192
+ entries.slice(0, 20).map(async ({ name }) => (await client.resolve<Post>(name))[0]),
193
+ );
194
+ ```
195
+
196
+ `entries` is sorted by block name and costs no block fetch however many
197
+ documents there are; each `resolve(name)` reads one body. Sort by a field of
198
+ the body (a date) only over the documents you resolved, or put the sort key in
199
+ the name. For pages, route with `client.routes()` and `client.redirects()`.
200
+ There is no working `client.list()`: it was removed (it fetched every block of
201
+ the type) and throws, naming these replacements.
202
+
203
+ See `examples/nextjs-binding-smoke/src/app/blog/page.tsx` for a list page.