@decocms/blocks 8.9.1 → 8.11.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (409) hide show
  1. package/dist/index.d.ts +1 -1
  2. package/dist/index.d.ts.map +1 -1
  3. package/dist/index.js +1 -1
  4. package/dist/index.js.map +1 -1
  5. package/dist/protocol/channel.d.ts +98 -0
  6. package/dist/protocol/channel.d.ts.map +1 -0
  7. package/dist/protocol/channel.js +58 -0
  8. package/dist/protocol/channel.js.map +1 -0
  9. package/dist/protocol/client.js +2 -2
  10. package/dist/protocol/client.js.map +1 -1
  11. package/dist/protocol/conformance/blockMetaVectors.json +214 -0
  12. package/dist/protocol/conformance/contentHashFixtures.d.ts +22 -0
  13. package/dist/protocol/conformance/contentHashFixtures.d.ts.map +1 -1
  14. package/dist/protocol/conformance/contentHashFixtures.js +55 -0
  15. package/dist/protocol/conformance/contentHashFixtures.js.map +1 -1
  16. package/dist/protocol/conformance/index.d.ts +2 -1
  17. package/dist/protocol/conformance/index.d.ts.map +1 -1
  18. package/dist/protocol/conformance/index.js +2 -1
  19. package/dist/protocol/conformance/index.js.map +1 -1
  20. package/dist/protocol/conformance/vectors.d.ts +33 -0
  21. package/dist/protocol/conformance/vectors.d.ts.map +1 -0
  22. package/dist/protocol/conformance/vectors.js +3 -0
  23. package/dist/protocol/conformance/vectors.js.map +1 -0
  24. package/dist/protocol/index.d.ts +11 -1
  25. package/dist/protocol/index.d.ts.map +1 -1
  26. package/dist/protocol/index.js +11 -1
  27. package/dist/protocol/index.js.map +1 -1
  28. package/dist/protocol/keys.d.ts +1 -1
  29. package/dist/protocol/keys.js +1 -1
  30. package/dist/v8/background.d.ts +13 -0
  31. package/dist/v8/background.d.ts.map +1 -1
  32. package/dist/v8/background.js +41 -0
  33. package/dist/v8/background.js.map +1 -1
  34. package/dist/v8/blockMeta.d.ts +27 -0
  35. package/dist/v8/blockMeta.d.ts.map +1 -0
  36. package/dist/v8/blockMeta.js +75 -0
  37. package/dist/v8/blockMeta.js.map +1 -0
  38. package/dist/v8/blockStore.d.ts +43 -0
  39. package/dist/v8/blockStore.d.ts.map +1 -0
  40. package/dist/v8/blockStore.js +95 -0
  41. package/dist/v8/blockStore.js.map +1 -0
  42. package/dist/v8/boundedJson.d.ts +5 -0
  43. package/dist/v8/boundedJson.d.ts.map +1 -1
  44. package/dist/v8/boundedJson.js +10 -2
  45. package/dist/v8/boundedJson.js.map +1 -1
  46. package/dist/v8/boundedMap.d.ts +19 -0
  47. package/dist/v8/boundedMap.d.ts.map +1 -0
  48. package/dist/v8/boundedMap.js +52 -0
  49. package/dist/v8/boundedMap.js.map +1 -0
  50. package/dist/v8/builtins/data.d.ts +18 -2
  51. package/dist/v8/builtins/data.d.ts.map +1 -1
  52. package/dist/v8/builtins/data.js +17 -1
  53. package/dist/v8/builtins/data.js.map +1 -1
  54. package/dist/v8/builtins/index.d.ts.map +1 -1
  55. package/dist/v8/builtins/index.js +2 -1
  56. package/dist/v8/builtins/index.js.map +1 -1
  57. package/dist/v8/builtins/legacy.d.ts +6 -3
  58. package/dist/v8/builtins/legacy.d.ts.map +1 -1
  59. package/dist/v8/builtins/legacy.js +6 -3
  60. package/dist/v8/builtins/legacy.js.map +1 -1
  61. package/dist/v8/canonical.d.ts +8 -0
  62. package/dist/v8/canonical.d.ts.map +1 -1
  63. package/dist/v8/canonical.js +15 -0
  64. package/dist/v8/canonical.js.map +1 -1
  65. package/dist/v8/cli/builtins.d.ts.map +1 -1
  66. package/dist/v8/cli/builtins.js +1 -0
  67. package/dist/v8/cli/builtins.js.map +1 -1
  68. package/dist/v8/cli/check/index.d.ts +10 -0
  69. package/dist/v8/cli/check/index.d.ts.map +1 -1
  70. package/dist/v8/cli/check/index.js +91 -7
  71. package/dist/v8/cli/check/index.js.map +1 -1
  72. package/dist/v8/cli/content.d.ts +12 -25
  73. package/dist/v8/cli/content.d.ts.map +1 -1
  74. package/dist/v8/cli/content.js +46 -75
  75. package/dist/v8/cli/content.js.map +1 -1
  76. package/dist/v8/cli/index.d.ts +2 -2
  77. package/dist/v8/cli/index.d.ts.map +1 -1
  78. package/dist/v8/cli/index.js +2 -2
  79. package/dist/v8/cli/index.js.map +1 -1
  80. package/dist/v8/cli/remote/commands.d.ts +71 -0
  81. package/dist/v8/cli/remote/commands.d.ts.map +1 -0
  82. package/dist/v8/cli/remote/commands.js +644 -0
  83. package/dist/v8/cli/remote/commands.js.map +1 -0
  84. package/dist/v8/cli/remote/diff.d.ts +15 -0
  85. package/dist/v8/cli/remote/diff.d.ts.map +1 -0
  86. package/dist/v8/cli/remote/diff.js +102 -0
  87. package/dist/v8/cli/remote/diff.js.map +1 -0
  88. package/dist/v8/cli/remote/env.d.ts +35 -0
  89. package/dist/v8/cli/remote/env.d.ts.map +1 -0
  90. package/dist/v8/cli/remote/env.js +84 -0
  91. package/dist/v8/cli/remote/env.js.map +1 -0
  92. package/dist/v8/cli/remote/http.d.ts +149 -0
  93. package/dist/v8/cli/remote/http.d.ts.map +1 -0
  94. package/dist/v8/cli/remote/http.js +381 -0
  95. package/dist/v8/cli/remote/http.js.map +1 -0
  96. package/dist/v8/cli/remote/local.d.ts +90 -0
  97. package/dist/v8/cli/remote/local.d.ts.map +1 -0
  98. package/dist/v8/cli/remote/local.js +309 -0
  99. package/dist/v8/cli/remote/local.js.map +1 -0
  100. package/dist/v8/cli/root.d.ts +29 -0
  101. package/dist/v8/cli/root.d.ts.map +1 -1
  102. package/dist/v8/cli/root.js +28 -0
  103. package/dist/v8/cli/root.js.map +1 -1
  104. package/dist/v8/cli/run.d.ts +13 -1
  105. package/dist/v8/cli/run.d.ts.map +1 -1
  106. package/dist/v8/cli/run.js +310 -124
  107. package/dist/v8/cli/run.js.map +1 -1
  108. package/dist/v8/cli/schema/builtinSchemas.d.ts.map +1 -1
  109. package/dist/v8/cli/schema/builtinSchemas.js +28 -10
  110. package/dist/v8/cli/schema/builtinSchemas.js.map +1 -1
  111. package/dist/v8/cli/schema/generate.js +1 -1
  112. package/dist/v8/cli/schema/generate.js.map +1 -1
  113. package/dist/v8/cli/skills.d.ts +25 -0
  114. package/dist/v8/cli/skills.d.ts.map +1 -0
  115. package/dist/v8/cli/skills.js +70 -0
  116. package/dist/v8/cli/skills.js.map +1 -0
  117. package/dist/v8/client.d.ts +9 -9
  118. package/dist/v8/client.d.ts.map +1 -1
  119. package/dist/v8/client.js +138 -50
  120. package/dist/v8/client.js.map +1 -1
  121. package/dist/v8/cms.d.ts +2 -1
  122. package/dist/v8/cms.d.ts.map +1 -1
  123. package/dist/v8/cms.js +55 -46
  124. package/dist/v8/cms.js.map +1 -1
  125. package/dist/v8/content.d.ts +39 -78
  126. package/dist/v8/content.d.ts.map +1 -1
  127. package/dist/v8/content.js +155 -195
  128. package/dist/v8/content.js.map +1 -1
  129. package/dist/v8/contentIndex.d.ts +71 -0
  130. package/dist/v8/contentIndex.d.ts.map +1 -0
  131. package/dist/v8/contentIndex.js +137 -0
  132. package/dist/v8/contentIndex.js.map +1 -0
  133. package/dist/v8/draft.d.ts +7 -7
  134. package/dist/v8/draft.d.ts.map +1 -1
  135. package/dist/v8/draft.js +10 -9
  136. package/dist/v8/draft.js.map +1 -1
  137. package/dist/v8/draftChanges.d.ts +59 -32
  138. package/dist/v8/draftChanges.d.ts.map +1 -1
  139. package/dist/v8/draftChanges.js +139 -75
  140. package/dist/v8/draftChanges.js.map +1 -1
  141. package/dist/v8/errors.d.ts +21 -0
  142. package/dist/v8/errors.d.ts.map +1 -1
  143. package/dist/v8/errors.js +22 -0
  144. package/dist/v8/errors.js.map +1 -1
  145. package/dist/v8/hostedSource.d.ts +57 -0
  146. package/dist/v8/hostedSource.d.ts.map +1 -0
  147. package/dist/v8/hostedSource.js +18 -0
  148. package/dist/v8/hostedSource.js.map +1 -0
  149. package/dist/v8/identity.d.ts +1 -1
  150. package/dist/v8/identity.js +1 -1
  151. package/dist/v8/index.d.ts +1 -0
  152. package/dist/v8/index.d.ts.map +1 -1
  153. package/dist/v8/index.js +1 -0
  154. package/dist/v8/index.js.map +1 -1
  155. package/dist/v8/matchRoute.js +7 -4
  156. package/dist/v8/matchRoute.js.map +1 -1
  157. package/dist/v8/pin.d.ts +34 -0
  158. package/dist/v8/pin.d.ts.map +1 -0
  159. package/dist/v8/pin.js +156 -0
  160. package/dist/v8/pin.js.map +1 -0
  161. package/dist/v8/preview/StudioBridge.d.ts +8 -8
  162. package/dist/v8/preview/StudioBridge.d.ts.map +1 -1
  163. package/dist/v8/preview/StudioBridge.js +8 -10
  164. package/dist/v8/preview/StudioBridge.js.map +1 -1
  165. package/dist/v8/preview/StudioChannel.d.ts +51 -0
  166. package/dist/v8/preview/StudioChannel.d.ts.map +1 -0
  167. package/dist/v8/preview/StudioChannel.js +104 -0
  168. package/dist/v8/preview/StudioChannel.js.map +1 -0
  169. package/dist/v8/preview/index.d.ts +3 -0
  170. package/dist/v8/preview/index.d.ts.map +1 -1
  171. package/dist/v8/preview/index.js +3 -0
  172. package/dist/v8/preview/index.js.map +1 -1
  173. package/dist/v8/remoteLoader.d.ts +42 -5
  174. package/dist/v8/remoteLoader.d.ts.map +1 -1
  175. package/dist/v8/remoteLoader.js +317 -259
  176. package/dist/v8/remoteLoader.js.map +1 -1
  177. package/dist/v8/resolver.d.ts +22 -8
  178. package/dist/v8/resolver.d.ts.map +1 -1
  179. package/dist/v8/resolver.js +37 -32
  180. package/dist/v8/resolver.js.map +1 -1
  181. package/dist/v8/revisionId.d.ts +11 -0
  182. package/dist/v8/revisionId.d.ts.map +1 -0
  183. package/dist/v8/revisionId.js +13 -0
  184. package/dist/v8/revisionId.js.map +1 -0
  185. package/dist/v8/settings.d.ts +6 -6
  186. package/dist/v8/settings.d.ts.map +1 -1
  187. package/dist/v8/settings.js +8 -7
  188. package/dist/v8/settings.js.map +1 -1
  189. package/dist/v8/telemetry.d.ts +4 -2
  190. package/dist/v8/telemetry.d.ts.map +1 -1
  191. package/dist/v8/telemetry.js +2 -2
  192. package/dist/v8/telemetry.js.map +1 -1
  193. package/dist/v8/types.d.ts +52 -40
  194. package/dist/v8/types.d.ts.map +1 -1
  195. package/dist/v8/variants.d.ts +7 -2
  196. package/dist/v8/variants.d.ts.map +1 -1
  197. package/dist/v8/variants.js +21 -24
  198. package/dist/v8/variants.js.map +1 -1
  199. package/dist/v8/vite/index.d.ts +2 -2
  200. package/dist/v8/vite/index.js +1 -1
  201. package/dist/v8/vite/index.js.map +1 -1
  202. package/package.json +3 -2
  203. package/skills/deco-apps/SKILL.md +82 -0
  204. package/skills/deco-apps/references/algolia.md +51 -0
  205. package/skills/deco-apps/references/commerce-types.md +132 -0
  206. package/skills/deco-apps/references/instrumented-fetch.md +144 -0
  207. package/skills/deco-apps/references/magento.md +55 -0
  208. package/skills/deco-apps/references/messaging.md +76 -0
  209. package/skills/deco-apps/references/shopify.md +69 -0
  210. package/skills/deco-apps/references/vendored-loaders.md +135 -0
  211. package/skills/deco-apps/references/vtex-cookies-auth.md +146 -0
  212. package/skills/deco-apps/references/vtex.md +150 -0
  213. package/skills/deco-apps/references/wake.md +75 -0
  214. package/skills/deco-cms-schema/SKILL.md +80 -0
  215. package/skills/deco-cms-schema/references/annotations.md +147 -0
  216. package/skills/deco-cms-schema/references/content-hygiene.md +91 -0
  217. package/skills/deco-cms-schema/references/formats-and-widgets.md +112 -0
  218. package/skills/deco-cms-schema/references/shapes-that-break-the-form.md +165 -0
  219. package/skills/deco-cms-schema/references/types-to-fields.md +112 -0
  220. package/skills/deco-go-live/SKILL.md +127 -0
  221. package/skills/deco-go-live/references/content-releases.md +90 -0
  222. package/skills/deco-go-live/references/process.md +106 -0
  223. package/skills/deco-go-live/references/proxy-headers-checkout.md +139 -0
  224. package/skills/deco-go-live/references/qa-checklist-template.md +150 -0
  225. package/skills/deco-go-live/references/qa-inventory.md +120 -0
  226. package/skills/deco-go-live/references/react-spa.md +183 -0
  227. package/skills/deco-go-live/references/seo-analytics.md +114 -0
  228. package/skills/deco-go-live/references/traffic-ramp.md +87 -0
  229. package/skills/deco-go-live/references/worker-runtime.md +93 -0
  230. package/skills/deco-go-live/scripts/preflight.sh +221 -0
  231. package/skills/deco-images-media/SKILL.md +64 -0
  232. package/skills/deco-images-media/references/asset-upload.md +191 -0
  233. package/skills/deco-images-media/references/components-per-binding.md +167 -0
  234. package/skills/deco-images-media/references/providers-and-cdn.md +145 -0
  235. package/skills/deco-images-media/references/quality-and-lcp.md +93 -0
  236. package/skills/deco-images-media/references/troubleshooting.md +147 -0
  237. package/skills/deco-images-media/references/video.md +122 -0
  238. package/skills/deco-make-editable/SKILL.md +94 -0
  239. package/skills/deco-make-editable/references/a11y-and-e2e.md +104 -0
  240. package/skills/deco-make-editable/references/content-shapes.md +198 -0
  241. package/skills/deco-make-editable/references/from-figma.md +110 -0
  242. package/skills/deco-make-editable/references/i18n-fields.md +112 -0
  243. package/skills/deco-make-editable/references/inventory.md +79 -0
  244. package/skills/deco-make-editable/references/pixel-parity.md +175 -0
  245. package/skills/deco-make-editable/references/seeding-content.md +119 -0
  246. package/skills/deco-nextjs-site/SKILL.md +74 -0
  247. package/skills/deco-nextjs-site/references/caching.md +116 -0
  248. package/skills/deco-nextjs-site/references/metadata-seo.md +100 -0
  249. package/skills/deco-nextjs-site/references/proxy-and-drafts.md +177 -0
  250. package/skills/deco-nextjs-site/references/rendering.md +171 -0
  251. package/skills/deco-nextjs-site/references/setup.md +190 -0
  252. package/skills/deco-nextjs-site/references/studio-bridge.md +130 -0
  253. package/skills/deco-site-authoring/SKILL.md +75 -0
  254. package/skills/deco-site-authoring/references/lazy-blocks.md +155 -0
  255. package/skills/deco-site-authoring/references/loaders.md +192 -0
  256. package/skills/deco-site-authoring/references/pages.md +156 -0
  257. package/skills/deco-site-authoring/references/review-before-publish.md +95 -0
  258. package/skills/deco-site-authoring/references/sections.md +158 -0
  259. package/skills/deco-site-authoring/references/seo.md +116 -0
  260. package/skills/deco-site-workflow/SKILL.md +92 -0
  261. package/skills/deco-site-workflow/references/check.md +116 -0
  262. package/skills/deco-site-workflow/references/cli-reference.md +104 -0
  263. package/skills/deco-site-workflow/references/content-layout.md +93 -0
  264. package/skills/deco-site-workflow/references/content-sync.md +146 -0
  265. package/skills/deco-site-workflow/references/delivery.md +51 -0
  266. package/skills/deco-site-workflow/references/deploy.md +87 -0
  267. package/skills/deco-site-workflow/references/schema.md +173 -0
  268. package/skills/deco-site-workflow/references/serve-and-studio.md +138 -0
  269. package/skills/deco-storefront-caching/SKILL.md +67 -0
  270. package/skills/deco-storefront-caching/references/cache-keys.md +129 -0
  271. package/skills/deco-storefront-caching/references/case-study.md +82 -0
  272. package/skills/deco-storefront-caching/references/egress-traps.md +153 -0
  273. package/skills/deco-storefront-caching/references/nextjs.md +60 -0
  274. package/skills/deco-storefront-caching/references/perf-guardrails-e2e.md +123 -0
  275. package/skills/deco-storefront-caching/references/verification.md +136 -0
  276. package/skills/deco-storefront-caching/references/worker-page-cache.md +160 -0
  277. package/skills/deco-storefront-caching/scripts/html-anatomy.mjs +97 -0
  278. package/skills/deco-storefront-performance/SKILL.md +81 -0
  279. package/skills/deco-storefront-performance/references/cls-third-party.md +90 -0
  280. package/skills/deco-storefront-performance/references/hydration.md +116 -0
  281. package/skills/deco-storefront-performance/references/loaders-n-plus-1.md +107 -0
  282. package/skills/deco-storefront-performance/references/navigation-ux.md +130 -0
  283. package/skills/deco-storefront-performance/references/payload-trim.md +163 -0
  284. package/skills/deco-storefront-performance/references/render-location.md +152 -0
  285. package/skills/deco-storefront-performance/references/request-dedupe.md +147 -0
  286. package/skills/deco-storefront-performance/references/trace-reading.md +79 -0
  287. package/skills/deco-storefront-performance/references/worker-memory.md +176 -0
  288. package/skills/deco-tanstack-site/SKILL.md +68 -0
  289. package/skills/deco-tanstack-site/references/document-and-security.md +155 -0
  290. package/skills/deco-tanstack-site/references/router-and-navigation.md +137 -0
  291. package/skills/deco-tanstack-site/references/routes-and-pages.md +183 -0
  292. package/skills/deco-tanstack-site/references/server-functions.md +123 -0
  293. package/skills/deco-tanstack-site/references/setup.md +153 -0
  294. package/skills/deco-tanstack-site/references/worker-entry.md +152 -0
  295. package/skills/deco-v7-to-v8-migration/SKILL.md +122 -0
  296. package/skills/deco-v7-to-v8-migration/references/caching-and-privacy.md +10 -0
  297. package/skills/deco-v7-to-v8-migration/references/content.md +25 -0
  298. package/skills/deco-v7-to-v8-migration/references/editor-forms.md +27 -0
  299. package/skills/deco-v7-to-v8-migration/references/faststore.md +40 -0
  300. package/skills/deco-v7-to-v8-migration/references/framework-code.md +53 -0
  301. package/skills/deco-v7-to-v8-migration/references/hosted-releases.md +16 -0
  302. package/skills/deco-v7-to-v8-migration/references/import-map.md +81 -0
  303. package/skills/deco-v7-to-v8-migration/references/legacy-names.md +33 -0
  304. package/skills/deco-v7-to-v8-migration/references/manual-steps.md +10 -0
  305. package/skills/deco-v7-to-v8-migration/references/native-apps.md +43 -0
  306. package/skills/deco-v7-to-v8-migration/references/nextjs.md +19 -0
  307. package/skills/deco-v7-to-v8-migration/references/parity.md +66 -0
  308. package/skills/deco-v7-to-v8-migration/references/rendering.md +13 -0
  309. package/skills/deco-v7-to-v8-migration/references/running-the-script.md +29 -0
  310. package/skills/deco-v7-to-v8-migration/references/script-steps.md +13 -0
  311. package/skills/deco-v7-to-v8-migration/references/server-functions.md +15 -0
  312. package/skills/deco-v7-to-v8-migration/references/sibling-port.md +11 -0
  313. package/skills/deco-v7-to-v8-migration/references/site-code.md +15 -0
  314. package/skills/deco-v7-to-v8-migration/references/telemetry.md +10 -0
  315. package/skills/deco-v7-to-v8-migration/references/verify.md +20 -0
  316. package/skills/deco-v7-to-v8-migration/scripts/apps.ts +297 -0
  317. package/skills/deco-v7-to-v8-migration/scripts/asyncRendering.ts +73 -0
  318. package/skills/deco-v7-to-v8-migration/scripts/blockMap.ts +584 -0
  319. package/skills/deco-v7-to-v8-migration/scripts/ciSchemaCheck.ts +145 -0
  320. package/skills/deco-v7-to-v8-migration/scripts/compat.ts +357 -0
  321. package/skills/deco-v7-to-v8-migration/scripts/content.ts +121 -0
  322. package/skills/deco-v7-to-v8-migration/scripts/experiments.ts +81 -0
  323. package/skills/deco-v7-to-v8-migration/scripts/framework.ts +61 -0
  324. package/skills/deco-v7-to-v8-migration/scripts/imageCopy.ts +276 -0
  325. package/skills/deco-v7-to-v8-migration/scripts/imageModule.ts +285 -0
  326. package/skills/deco-v7-to-v8-migration/scripts/imports.ts +942 -0
  327. package/skills/deco-v7-to-v8-migration/scripts/invoke.ts +624 -0
  328. package/skills/deco-v7-to-v8-migration/scripts/legacyNames.ts +45 -0
  329. package/skills/deco-v7-to-v8-migration/scripts/main.ts +59 -0
  330. package/skills/deco-v7-to-v8-migration/scripts/matchers.ts +41 -0
  331. package/skills/deco-v7-to-v8-migration/scripts/migrate.ts +176 -0
  332. package/skills/deco-v7-to-v8-migration/scripts/redirects.ts +455 -0
  333. package/skills/deco-v7-to-v8-migration/scripts/report.ts +50 -0
  334. package/skills/deco-v7-to-v8-migration/scripts/scaffold.ts +1119 -0
  335. package/skills/deco-v7-to-v8-migration/scripts/secrets.ts +35 -0
  336. package/skills/deco-v7-to-v8-migration/scripts/sectionLoaders.ts +216 -0
  337. package/skills/deco-v7-to-v8-migration/scripts/siteSettings.ts +261 -0
  338. package/skills/deco-v7-to-v8-migration/scripts/stubs.ts +388 -0
  339. package/skills/deco-v7-to-v8-migration/scripts/tsconfig.json +7 -0
  340. package/skills/deco-v7-to-v8-migration/scripts/vendor.ts +249 -0
  341. package/skills/deco-v7-to-v8-migration/scripts/vtexInvoke.ts +240 -0
  342. package/skills/deco-v7-to-v8-migration/scripts/walk.ts +30 -0
  343. package/skills/deco-variants/SKILL.md +57 -0
  344. package/skills/deco-variants/references/caching-variants.md +63 -0
  345. package/skills/deco-variants/references/custom-matchers.md +83 -0
  346. package/skills/deco-variants/references/draft-preview.md +59 -0
  347. package/skills/deco-variants/references/experiments-and-campaigns.md +104 -0
  348. package/skills/deco-variants/references/multivariate.md +85 -0
  349. package/skills/deco-variants/references/v7-matchers.md +71 -0
  350. package/src/index.ts +2 -0
  351. package/src/protocol/channel.ts +127 -0
  352. package/src/protocol/client.ts +2 -2
  353. package/src/protocol/conformance/blockMetaVectors.json +214 -0
  354. package/src/protocol/conformance/contentHashFixtures.ts +74 -0
  355. package/src/protocol/conformance/index.ts +9 -1
  356. package/src/protocol/conformance/vectors.ts +36 -0
  357. package/src/protocol/index.ts +32 -0
  358. package/src/protocol/keys.ts +1 -1
  359. package/src/v8/background.ts +42 -0
  360. package/src/v8/blockMeta.ts +100 -0
  361. package/src/v8/blockStore.ts +124 -0
  362. package/src/v8/boundedJson.ts +20 -2
  363. package/src/v8/boundedMap.ts +53 -0
  364. package/src/v8/builtins/data.ts +26 -2
  365. package/src/v8/builtins/index.ts +2 -1
  366. package/src/v8/builtins/legacy.ts +6 -3
  367. package/src/v8/canonical.ts +15 -0
  368. package/src/v8/cli/builtins.ts +1 -0
  369. package/src/v8/cli/check/index.ts +97 -7
  370. package/src/v8/cli/content.ts +49 -91
  371. package/src/v8/cli/index.ts +2 -2
  372. package/src/v8/cli/remote/commands.ts +834 -0
  373. package/src/v8/cli/remote/diff.ts +100 -0
  374. package/src/v8/cli/remote/env.ts +107 -0
  375. package/src/v8/cli/remote/http.ts +484 -0
  376. package/src/v8/cli/remote/local.ts +343 -0
  377. package/src/v8/cli/root.ts +40 -0
  378. package/src/v8/cli/run.ts +366 -135
  379. package/src/v8/cli/schema/builtinSchemas.ts +29 -10
  380. package/src/v8/cli/schema/generate.ts +1 -1
  381. package/src/v8/cli/skills.ts +91 -0
  382. package/src/v8/client.ts +162 -60
  383. package/src/v8/cms.ts +62 -53
  384. package/src/v8/content.ts +179 -229
  385. package/src/v8/contentIndex.ts +183 -0
  386. package/src/v8/draft.ts +15 -14
  387. package/src/v8/draftChanges.ts +151 -85
  388. package/src/v8/errors.ts +37 -0
  389. package/src/v8/hostedSource.ts +67 -0
  390. package/src/v8/identity.ts +1 -1
  391. package/src/v8/index.ts +1 -0
  392. package/src/v8/matchRoute.ts +7 -4
  393. package/src/v8/pin.ts +176 -0
  394. package/src/v8/preview/StudioBridge.ts +8 -10
  395. package/src/v8/preview/StudioChannel.ts +116 -0
  396. package/src/v8/preview/index.ts +3 -0
  397. package/src/v8/remoteLoader.ts +350 -286
  398. package/src/v8/resolver.ts +56 -33
  399. package/src/v8/revisionId.ts +14 -0
  400. package/src/v8/settings.ts +10 -9
  401. package/src/v8/telemetry.ts +3 -3
  402. package/src/v8/types.ts +52 -40
  403. package/src/v8/variants.ts +30 -26
  404. package/src/v8/vite/index.ts +3 -3
  405. package/dist/v8/cli/serve/server.d.ts +0 -29
  406. package/dist/v8/cli/serve/server.d.ts.map +0 -1
  407. package/dist/v8/cli/serve/server.js +0 -296
  408. package/dist/v8/cli/serve/server.js.map +0 -1
  409. package/src/v8/cli/serve/server.ts +0 -348
@@ -0,0 +1,75 @@
1
+ ---
2
+ name: deco-site-authoring
3
+ description: "Writing sections, pages and loaders for a site on @decocms/blocks 8 (with @decocms/tanstack or @decocms/nextjs). Covers block functions in .deco/index.ts and their Props, React sections as descriptors or elements, client components instead of islands or HTMX, page blocks with path templates and route params, loaders as block functions (one run per distinct input per client, no request object), SEO and JSON-LD fed by the same commerce loader as the page, the built-in lazy block, one promise per section with Suspense and loading skeletons, and the review before deco push. Load it when creating or changing a section, page or loader, when a section never loads, loads twice or shows the wrong data, or before pushing content and code."
4
+ ---
5
+
6
+ # Authoring sections, pages and loaders on v8
7
+
8
+ On @decocms/blocks 8 everything an editor can place is a **block function**: a plain
9
+ function in the block map, `.deco/index.ts` (or `.tsx`), that takes one argument, its
10
+ inputs, and returns a value. Content is JSON in `.deco/blocks/`, where each object names
11
+ a function in `__resolveType` and carries its inputs. `client.resolve` walks that JSON
12
+ inside out, so nested blocks run first, siblings run concurrently, and each function
13
+ gets its inputs already resolved.
14
+
15
+ Use this skill when you are writing or changing the code an editor uses. It is not for
16
+ wiring the binding or deploying.
17
+
18
+ ## The model in five lines
19
+
20
+ - **Section**: a block function that returns a React element, or a descriptor
21
+ `{ component, props }`. `deco schema` puts it in the section picker.
22
+ - **Loader**: a block function that returns data. A field of type `T` accepts a plain
23
+ value or any block whose awaited return type fits `T`.
24
+ - **Matcher**: a block function that returns a boolean.
25
+ - **Page**: the built-in `page` block, `{ name, path, seo?, sections }`, routed by
26
+ `matchRoute`.
27
+ - **No request scope**: a block function gets its inputs and nothing else. It calls
28
+ `currentClient()` to reach the client, and gets route params as arguments.
29
+
30
+ ## When to load what
31
+
32
+ | Reference | Load it when |
33
+ |---|---|
34
+ | [`references/sections.md`](./references/sections.md) | Writing a section, choosing descriptors or elements, adding interactivity (hooks, `"use client"`), porting a Fresh island or an HTMX section |
35
+ | [`references/pages.md`](./references/pages.md) | Creating a page block, path templates and params, shared header/footer, a page with variants, routing a custom type, a route conflict |
36
+ | [`references/loaders.md`](./references/loaders.md) | Fetching data for a section, passing a route param to a loader, a loader that runs twice, `BLOCK_FAILED`, secrets, upstream fetches |
37
+ | [`references/lazy-blocks.md`](./references/lazy-blocks.md) | `Lazy<T>` props, the `lazy` built-in, streaming sections with Suspense, loading skeletons, a failed or hidden section |
38
+ | [`references/seo.md`](./references/seo.md) | A page's `seo` field, title and description from product data, canonical and JSON-LD, the SEO checklist for a new site |
39
+ | [`references/review-before-publish.md`](./references/review-before-publish.md) | Before `deco push` or opening a PR: the checklist, `deco schema --check`, `deco check` against a draft |
40
+
41
+ ## Rules that hold everywhere
42
+
43
+ - **One argument, no context.** A block function gets exactly one argument, its
44
+ inputs, with `__resolveType` removed. There is no `req`, no `ctx`, no `invoke`.
45
+ - **Results are read-only.** A client runs each block function once per distinct
46
+ input and hands every occurrence the same object. Copy a result before you change
47
+ it.
48
+ - **A failing block fails its parent.** The error is `BLOCK_FAILED` with `path`
49
+ set to where it happened, such as `["sections", 2, "product"]`. `resolve` never
50
+ throws: it returns `[value, null]` or `[null, error]`.
51
+ - **A hidden block is `undefined`.** A `multivariate` with no true rule resolves to
52
+ `undefined`, and lists drop it. Render nothing for it.
53
+ - **Names.** Block map keys are the type names saved in content. Built-in names
54
+ (`lazy`, `multivariate`, `always`, `never`, `experiment`, `campaign`, `page`,
55
+ `redirect`, `redirects`, `cms-settings`, `split-traffic`, `calendar`) are names no
56
+ saved block can take. A block map key with a built-in's name replaces the
57
+ built-in, and `deco check` tells you what relies on it.
58
+ - **After changing a Props type, run `deco schema`.** The Studio form comes from
59
+ `.deco/schema.gen.json`, and `deco check` validates against it.
60
+
61
+ ## Related skills
62
+
63
+ - `deco-site-workflow`: the `deco` CLI end to end (`pull`, `diff`, `push --draft`,
64
+ `publish`, `schema push`, `check`).
65
+ - `deco-cms-schema`: how a Props type becomes the Studio form (JSDoc tags, widgets,
66
+ shapes that break the form).
67
+ - `deco-tanstack-site` and `deco-nextjs-site`: the catch-all route, `open-page`, the
68
+ worker or proxy, server functions, document head.
69
+ - `deco-variants`: `multivariate`, matchers, A/B tests and campaigns.
70
+ - `deco-apps`: the `@decocms/apps-*` clients a loader calls, commerce types.
71
+ - `deco-images-media`: images and video inside sections.
72
+ - `deco-storefront-performance` and `deco-storefront-caching`: slow loaders,
73
+ duplicate upstream calls, payload size, cache keys.
74
+ - `deco-v7-to-v8-migration`: a site moving from v7, where sections still use
75
+ `(props, req)` loaders through `@decocms/compat-v7/sections`.
@@ -0,0 +1,155 @@
1
+ # Lazy blocks, streaming and skeletons
2
+
3
+ Two different tools answer "don't make the page wait for this":
4
+
5
+ - The **`lazy` built-in** skips work on the server: a prop typed `Lazy<T>` is a function
6
+ the block calls only if it needs the value.
7
+ - **One promise per section** streams the page: the page loader resolves each section on
8
+ its own, and the route shows a fallback in a Suspense boundary until that section is
9
+ ready.
10
+
11
+ v8 has no async rendering of the v7 kind. There is no `Rendering/Lazy.tsx` wrapper in
12
+ content, no `LoadingFallback` export picked up by the framework, and no section that
13
+ waits for the viewport before it loads. The migration script unwraps v7's wrappers into
14
+ plain sections.
15
+
16
+ ## The `lazy` built-in
17
+
18
+ ```ts
19
+ import type { Lazy } from "@decocms/blocks";
20
+
21
+ export async function productCard({
22
+ title,
23
+ showProduct,
24
+ product,
25
+ }: {
26
+ title: string;
27
+ showProduct: boolean;
28
+ product: Lazy<Product>;
29
+ }) {
30
+ if (!showProduct) return <Title text={title} />; // the loader never runs
31
+ const item = await product(); // the loader runs here
32
+ return <Card title={title} product={item} />;
33
+ }
34
+ ```
35
+
36
+ In content, the field holds a `lazy` block around the loader:
37
+
38
+ ```json
39
+ {
40
+ "__resolveType": "product-card",
41
+ "title": "Summer collection",
42
+ "showProduct": true,
43
+ "product": {
44
+ "__resolveType": "lazy",
45
+ "value": { "__resolveType": "product-by-slug", "slug": "summer-shirt" }
46
+ }
47
+ }
48
+ ```
49
+
50
+ How it behaves:
51
+
52
+ - The resolver does not resolve `value` first. It hands the block a memoized
53
+ `() => Promise<T>` instead.
54
+ - The value resolves the first time the function is called, and only once. A second
55
+ call returns the same result.
56
+ - If the value fails, the call rejects, and the block decides what to do. If the block
57
+ lets the error escape, the block fails with the inner error's code and path.
58
+ - A lazy value that is never called never runs, and never rejects unhandled.
59
+ - `value` can be any JSON, not only a block. Saved block references inside it expand
60
+ when it is called.
61
+
62
+ Schema and checks:
63
+
64
+ - `deco schema` turns a `Lazy<T>` prop into a field that holds a `lazy` block whose
65
+ `value` has the form of `T`. `Lazy<T>[]` is a list of them.
66
+ - `deco check` reports `this field is Lazy<T>: wrap the value in a lazy block` for a
67
+ plain value in such a field, and `a lazy block only fits a Lazy<T> field` for a `lazy`
68
+ block anywhere else. A `lazy` block cannot sit directly in a page's `sections`.
69
+ - The built-in `multivariate` stores each variant's `value` as a `lazy` block, so only
70
+ the chosen variant runs. `deco check` reports `a variant's value must be a lazy block`
71
+ otherwise.
72
+ - A matcher can take an inner rule as `Lazy<boolean>` and skip it:
73
+ `async ({ a, b }: { a: boolean; b: Lazy<boolean> }) => a && (await b())`.
74
+
75
+ Use `Lazy<T>` when the block may not need the data: a toggle, a tab that is closed by
76
+ default, a fallback source, an expensive rule. It does not move work to the browser or
77
+ delay it until scroll. A block that always calls its lazy prop gains nothing from it.
78
+
79
+ ## One promise per section
80
+
81
+ The page loader in the examples (`src/open-page.server.ts`) reads the page with
82
+ `{ run: false }`, then starts one `client.resolve(section)` per section and returns the
83
+ promises without awaiting them:
84
+
85
+ ```ts
86
+ const blocks = sections.map((block, index) => ({
87
+ key: `${href}:${index}`,
88
+ value: c.resolve(block).then(([value, error]) => {
89
+ if (error) console.error(error);
90
+ return { value: value ?? undefined, failed: error !== null };
91
+ }),
92
+ }));
93
+ ```
94
+
95
+ Each entry settles to `{ value, failed }` and never rejects, so one slow or failing
96
+ section does not hold or break the others. The route renders each one in its own
97
+ boundary. On TanStack Start without RSC:
98
+
99
+ ```tsx
100
+ <Suspense key={block.key} fallback={<SectionSkeleton />}>
101
+ <Await promise={block.value}>
102
+ {({ value, failed }) => {
103
+ if (failed) return <p role="status">This content is temporarily unavailable.</p>;
104
+ return value ? <View block={value} /> : null; // undefined: an editor hid it
105
+ }}
106
+ </Await>
107
+ </Suspense>
108
+ ```
109
+
110
+ With TanStack RSC (`examples/tanstack-rsc-smoke`), an async server component awaits
111
+ the promise inside the same `Suspense`. The Next.js examples resolve the whole page in
112
+ one call instead, so nothing streams per section and one failing block fails the page.
113
+ A Next.js site that wants per-section streaming applies the same split in its page
114
+ loader. The wiring is in the `deco-tanstack-site` and `deco-nextjs-site` skills.
115
+
116
+ Three states to render, every time:
117
+
118
+ | State | Cause | Render |
119
+ |---|---|---|
120
+ | Pending | The section's loaders are still running | The Suspense fallback |
121
+ | `failed: true` | A block in the section threw | A small, quiet message, or nothing for decoration |
122
+ | `value === undefined` | A rule hid the section | Nothing |
123
+
124
+ Two caveats from migrated sites (details in the `deco-v7-to-v8-migration` skill,
125
+ `rendering.md`):
126
+
127
+ - After changing the page setup, check in the browser that every streamed section
128
+ hydrates (its handlers and effects run). One TanStack Start release left streamed
129
+ sections with server markup that never hydrated.
130
+ - A page whose blocks only read in-memory content can await them, so every section is
131
+ in the first HTML chunk. Stop awaiting a block once it fetches upstream.
132
+
133
+ ## Skeletons
134
+
135
+ The fallback is shown in the server's first HTML and then replaced in place. A
136
+ skeleton that is the wrong size moves the page when the section arrives (CLS).
137
+
138
+ - **Match the box.** Same container, padding, gaps and aspect ratios as the real
139
+ section, at each breakpoint. Height matters more than detail.
140
+ - **Pure markup.** CSS only (a pulse animation is fine). No hooks, no data, no props
141
+ from the loader. It renders before any data exists.
142
+ - **Represent the content.** A shelf skeleton shows a title bar and the number of cards
143
+ the real shelf shows per breakpoint (for example two on mobile, four on desktop,
144
+ hiding the rest with responsive classes).
145
+ - **Reuse a card skeleton.** Most shelves and grids repeat a product card. Build one
146
+ `CardSkeleton` that mirrors the real card (image, name in two lines, price block,
147
+ button) and use it everywhere.
148
+ - **Pick the skeleton per section type.** `{ run: false }` already gives the page
149
+ loader each section's `__resolveType` (saved references are expanded, so a reference
150
+ to a saved block shows the saved block's type). The page loader can return it next to
151
+ `key` and `value`, and the route can map it to a skeleton, with one generic fallback
152
+ for the rest.
153
+ - **Above the fold.** The first sections (header, hero, product summary) are what the
154
+ user sees first. Keep their loaders fast, or await them, rather than showing a
155
+ skeleton where the main content should be.
@@ -0,0 +1,192 @@
1
+ # Loaders
2
+
3
+ On v8 a loader is a block function that returns data. There is no `loaders/` folder
4
+ convention, no `export const loader` next to a section, and no `(props, req, ctx)`
5
+ signature. A loader is a key in the block map like any other block.
6
+
7
+ ```ts
8
+ // src/catalog.ts
9
+ import type { Product } from "@decocms/compat-v7/commerce/types";
10
+
11
+ export async function productBySlug({ slug }: { slug: string }): Promise<Product> {
12
+ // call the platform client here (see the deco-apps skill)
13
+ }
14
+ ```
15
+
16
+ ```ts
17
+ // .deco/index.ts
18
+ export default {
19
+ "product-by-slug": productBySlug,
20
+ "product-card": (input: ProductCardProps) => <ProductCard {...input} />,
21
+ } satisfies Blocks;
22
+ ```
23
+
24
+ `deco schema` puts a key in the loaders group when its return type is not an element,
25
+ a descriptor or a boolean, and is not its own props type. A function that returns its
26
+ props unchanged (like `seo: (input: Seo) => input`) is content, or a page when its
27
+ props extend `Route`. Use whatever data types fit the site. The schema.org-shaped
28
+ commerce types (`Product`, `ProductDetailsPage`, `ProductListingPage`, `BreadcrumbList`)
29
+ are in `@decocms/compat-v7/commerce/types`.
30
+
31
+ ## How content plugs a loader into a section
32
+
33
+ A section prop with an object type accepts a plain value, or any block whose awaited
34
+ return type fits that type (TypeScript assignability). Studio offers those blocks as
35
+ choices for the field. In content:
36
+
37
+ ```json
38
+ {
39
+ "__resolveType": "product-card",
40
+ "title": "Summer collection",
41
+ "product": { "__resolveType": "product-by-slug", "slug": "summer-shirt" }
42
+ }
43
+ ```
44
+
45
+ The resolver runs `product-by-slug` first and calls `product-card` with the `Product`
46
+ it returned. So type section props by the data they render, not by the loader that
47
+ fetches it. Any loader that returns a `Product` then fits.
48
+
49
+ ## One run per distinct input, per client
50
+
51
+ A client (one per request) remembers each block function's result by its inputs:
52
+
53
+ - The same function with the same inputs runs once per client. Every place that asks
54
+ gets the same promise, including calls made at the same time. Key order in the inputs
55
+ does not matter.
56
+ - Different inputs run separately. A new client (the next request) runs again.
57
+ - Inputs that are not JSON (a function passed by code) are not remembered.
58
+
59
+ This is how a page shares one upstream call between the product section and its SEO
60
+ block (see [seo.md](./seo.md)). It also means results are shared. Never mutate a
61
+ loader's result. Copy it first.
62
+
63
+ This is per request only. Caching across requests is a job for the upstream client's
64
+ `fetch` (see the `deco-storefront-caching` skill), not for the block.
65
+
66
+ ## Route params and other request data
67
+
68
+ A block function gets its inputs and nothing else. To read request-dependent data:
69
+
70
+ - **Route params** come from `matchRoute` in the page loader, which passes them as
71
+ arguments to the top-level blocks it resolves (see [pages.md](./pages.md)). A nested
72
+ loader does not get them. The section that received the param resolves the loader
73
+ itself, through the current client:
74
+
75
+ ```ts
76
+ import { currentClient } from "@decocms/blocks";
77
+ import type { Product } from "@decocms/compat-v7/commerce/types";
78
+
79
+ export interface ProductDetailsProps {
80
+ /** @ignore */
81
+ slug?: string;
82
+ }
83
+
84
+ export async function productDetails({ slug }: ProductDetailsProps) {
85
+ const client = currentClient(); // before any await
86
+ const [product, error] = await client.resolve<Product>({
87
+ __resolveType: "product-by-slug",
88
+ slug,
89
+ });
90
+ if (error) throw error;
91
+ return { component: "product-details", props: { product } } as const;
92
+ }
93
+ ```
94
+
95
+ The call goes through the same client, so it shares the per-request memo with every
96
+ other block asking for the same slug. `@ignore` keeps `slug` out of the Studio form,
97
+ since editors do not fill it in. The page loader does.
98
+
99
+ - **Visitor, version and date**: `currentClient()` returns the client, with
100
+ `client.visitor`, `client.version` and `client.date`. Call it at the start of the
101
+ function, before any `await`. On runtimes without `AsyncLocalStorage` it is gone after
102
+ the first `await`, and it throws outside a block function.
103
+
104
+ - **Cookies, headers, device**: these are not block inputs. The binding reads them in
105
+ the page loader. Pass what a block needs as an argument, the same way as a param. A
106
+ block that depends on the request varies the cached page, so check with the
107
+ `deco-storefront-caching` skill first.
108
+
109
+ ## Secrets and clients
110
+
111
+ Content holds no secrets, and there is no `secret` block. Create the upstream client in
112
+ code from the deploy platform's secrets, and close over it:
113
+
114
+ ```ts
115
+ import { createInstrumentedFetch } from "@decocms/blocks/fetch";
116
+ import type { Review } from "./model"; // the site's own type
117
+
118
+ const reviewsFetch = createInstrumentedFetch({ provider: "reviews" });
119
+
120
+ export const productReviews =
121
+ (apiKey: string) =>
122
+ async ({ productId }: { productId: string }): Promise<Review[]> => {
123
+ const url = `https://reviews.example.com/v1/products/${encodeURIComponent(productId)}`;
124
+ const response = await reviewsFetch(url, {
125
+ operation: "reviews.list",
126
+ headers: { authorization: `Bearer ${apiKey}` },
127
+ });
128
+ if (!response.ok) throw new Error(`reviews: HTTP ${response.status}`);
129
+ return (await response.json()) as Review[];
130
+ };
131
+
132
+ // .deco/index.ts: "product-reviews": productReviews(reviewsApiKey),
133
+ ```
134
+
135
+ Editors choose `productId`. The key never enters content. A v7 `secret` block left in
136
+ content fails `deco check` with `unknown block type`, and the message says secrets live
137
+ in the deploy platform. The
138
+ `@decocms/apps-*` clients and how to configure them are in the `deco-apps` skill.
139
+
140
+ ## Fetching upstream
141
+
142
+ - Use the platform client from `@decocms/apps-*` when there is one.
143
+ - For an API of your own, wrap `fetch` with `createInstrumentedFetch` from
144
+ `@decocms/blocks/fetch`:
145
+
146
+ ```ts
147
+ import { createInstrumentedFetch } from "@decocms/blocks/fetch";
148
+
149
+ const reviewsFetch = createInstrumentedFetch({
150
+ provider: "reviews",
151
+ retry: { attempts: 2 },
152
+ circuitBreaker: { failures: 5, cooldownMs: 30_000 },
153
+ });
154
+ await reviewsFetch(url, { operation: "reviews.list" });
155
+ ```
156
+
157
+ Each request is measured once (`http.client.request.duration`, labelled by
158
+ `provider` and `operation`). Retries and the circuit breaker are off unless set. Only
159
+ idempotent methods retry, never a `POST`.
160
+ - Ask for only what the section shows. Trim large upstream payloads in the loader
161
+ before they reach a section. The `deco-storefront-performance` skill has the method.
162
+
163
+ ## Errors
164
+
165
+ - A loader that throws fails as `BLOCK_FAILED`, with `path` pointing at the field, for
166
+ example `["sections", 2, "product"]`, and the original error in `cause`.
167
+ - A failed nested block fails its parent. A page loader that resolves each section on
168
+ its own (the TanStack examples) shows one failed section's error state and renders
169
+ the others. One that resolves the whole page in one call (the Next.js examples)
170
+ fails the whole page.
171
+ - Decide what "no data" means. For an optional section, return `undefined` (render
172
+ nothing) or an empty list. Throw only when the page cannot make sense without it.
173
+ - On TanStack the page loader can mark the response with `DEGRADED_HEADER`
174
+ (`x-deco-degraded`, from `@decocms/tanstack/server`) when a loader failed, so the
175
+ site's page cache does not store it. Headers are sent before the body, so the page
176
+ loader has to await every block before it answers, and nothing streams. See the
177
+ `deco-storefront-caching` skill.
178
+
179
+ ## Moving a v7 or Fresh loader
180
+
181
+ | v7 / Fresh | v8 |
182
+ |---|---|
183
+ | `export const loader = (props, req, ctx) => ...` in the section | A loader block, plugged into a section prop in content; or the section resolves it through `currentClient()` |
184
+ | `loaders/x.ts` default export | A block map key pointing at the function |
185
+ | `ctx.invoke.<app>.loaders.x(...)` | Call the platform client from `@decocms/apps-*` in code, or `currentClient().resolve({ __resolveType: "x", ... })` for another block |
186
+ | `requestToParam` in content | Params from `matchRoute`, passed by the page loader |
187
+ | `req.headers`, cookies | Read by the binding and passed as arguments |
188
+ | Cached loaders, `cache: "stale-while-revalidate"` | No block-level cache. Cache in the upstream client's `fetch` |
189
+
190
+ A migrated site can keep v7's `(props, req)` section loaders through
191
+ `runSectionLoaders` in `@decocms/compat-v7/sections`. That path is for migrations
192
+ only. See the `deco-v7-to-v8-migration` skill. Write new loaders as block functions.
@@ -0,0 +1,156 @@
1
+ # Pages
2
+
3
+ A page is a saved block of the built-in type `page`. It lives at
4
+ `.deco/blocks/<name>.json` (the file name is `encodeURIComponent(name)`), and the site's
5
+ catch-all route finds it by path with `matchRoute`.
6
+
7
+ ```json
8
+ {
9
+ "__resolveType": "page",
10
+ "name": "Summer shirt",
11
+ "path": "/:slug/p",
12
+ "seo": { "__resolveType": "seo", "title": "Summer shirt", "description": "Light cotton shirt." },
13
+ "sections": [
14
+ { "__resolveType": "Header" },
15
+ { "__resolveType": "product-hero", "name": "Summer shirt", "price": 49, "currency": "USD", "image": "/images/summer-shirt.jpg" },
16
+ { "__resolveType": "Footer" }
17
+ ]
18
+ }
19
+ ```
20
+
21
+ The resolved type is `Page<Section>` from `@decocms/blocks`: `name` and `path` (from
22
+ `Route`), an optional `seo` and `sections`. The built-in `page` returns its inputs as
23
+ they are, so a resolved page is `{ name, path, seo, sections }` with every section
24
+ resolved. Without `seo`, the site's defaults apply (see [seo.md](./seo.md)).
25
+
26
+ Create or edit pages in Studio, or edit the JSON and send it with the `deco` CLI (see
27
+ the `deco-site-workflow` skill). There is no `website/pages/Page.tsx` type to write.
28
+ v7 content that still says so resolves through a legacy alias.
29
+
30
+ ## Paths
31
+
32
+ `path` is a template. `matchRoute` compiles all paths into a segment tree and tries, at
33
+ each segment, the literal child first, then a `:param` child, then a trailing `*`. So
34
+ `/sale` beats `/:slug`, and `/:slug` beats `/*`.
35
+
36
+ | Template | Matches | `params` |
37
+ |---|---|---|
38
+ | `/about` | `/about` | `{}` |
39
+ | `/:slug/p` | `/summer-shirt/p` | `{ slug: "summer-shirt" }` |
40
+ | `/blog/:slug` | `/blog/archive` | `{ slug: "archive" }` |
41
+ | `/c/*` | `/c/shoes/running` | `{ "*": "shoes/running" }` (one or more segments) |
42
+
43
+ - The URL is percent-decoded, its query and fragment are dropped, and a trailing slash
44
+ is removed before matching. A `:param` never holds a slash.
45
+ - A splat is only a trailing `*` segment. v7's `/:slug*` form is not v8 syntax.
46
+ - Two pages whose paths reach the same leaf (`/:a/p` and `/:b/p`) conflict. `deco check`
47
+ reports it, and at runtime the page whose saved name sorts first wins.
48
+
49
+ ## How a page is opened
50
+
51
+ The binding's page loader (`src/open-page.server.ts` in the examples and in what the
52
+ migration script writes) does this per request. You rarely change it, but you need it
53
+ in mind to know what reaches your blocks.
54
+
55
+ 1. `client.routes()`: `{ name, path }` of every page, from the content index. `name`
56
+ is the saved block's name.
57
+ 2. `matchRoute(href, { routes })`: `match` with `entry` and `params`, or `not-found`.
58
+ 3. `client.prefetch(entry.name)`: starts downloading the page and everything it
59
+ references, in parallel with the next step.
60
+ 4. `client.redirects()` and `matchRoute(href, { routes: [], redirects })`: a redirect
61
+ wins over a page at the same path.
62
+ 5. `client.resolve(entry.name, { run: false })`: the page as JSON, saved references
63
+ expanded, nothing run.
64
+ 6. In the TanStack examples: one `client.resolve(section)` per section, each its own
65
+ promise, plus `seo`. The route renders each promise in its own Suspense boundary.
66
+ See [lazy-blocks.md](./lazy-blocks.md). The Next.js examples skip step 5 and
67
+ resolve the whole page in one call (`client.resolve(entry.name)`), so there one
68
+ failing block fails the page.
69
+
70
+ The wiring of that file, the route and `head()` belong to the `deco-tanstack-site` and
71
+ `deco-nextjs-site` skills.
72
+
73
+ ## Route params reach blocks as arguments
74
+
75
+ A block function never sees the URL. `matchRoute` returns `params` to the page loader,
76
+ and the page loader passes them on. With a section read in step 5, add the param as an
77
+ argument when you resolve it:
78
+
79
+ ```ts
80
+ const { slug } = match.params;
81
+ const [hero, error] = await c.resolve({ ...section, slug });
82
+ ```
83
+
84
+ For an inline block, the extra field becomes one of its inputs. For a reference to a
85
+ saved block, it is merged over the saved block's own fields (shallow,
86
+ `{ ...saved, ...arguments }`). Only the top-level block gets it. A loader nested inside
87
+ the section does not. The section passes `slug` down itself (see
88
+ [loaders.md](./loaders.md)). Decide one name per param (`slug`) and use it in every
89
+ block that needs it, so the page loader can pass the same arguments to all of them.
90
+
91
+ A page loader that resolves the whole page in one call has no per-section step. Passing
92
+ `slug` to `resolve({ __resolveType: entry.name, slug })` only reaches the `page` block
93
+ itself, not its sections. Resolve the sections one by one to pass params.
94
+
95
+ This is the page loader's choice, not a framework rule. Read the site's
96
+ `open-page.server.ts` before you assume a block gets a param. The v7 way,
97
+ `website/functions/requestToParam.ts` in content, has no v8 block.
98
+
99
+ ## Shared header and footer
100
+
101
+ Save shared sections once as named blocks (`Header.json`, `Footer.json`) and reference
102
+ them by name in each page:
103
+
104
+ ```json
105
+ { "__resolveType": "Header" }
106
+ ```
107
+
108
+ A reference resolves to the saved block. Fields you add next to `__resolveType` replace
109
+ the saved block's fields of the same name, for that page only. Copy the references from
110
+ the home page when you create a page, so every page shows the same header and footer.
111
+
112
+ ## Variants of a page's sections
113
+
114
+ `sections` can be a list, or one `multivariate` block whose variants are whole lists.
115
+ The page loader handles both: a single block resolves to the chosen list. Use the whole
116
+ list form when an A/B test changes the layout, and per-section variants when it
117
+ changes one section. See the `deco-variants` skill.
118
+
119
+ ## Changing the page type
120
+
121
+ - **Extra fields on every page.** Add a `page` key to the block map. It replaces the
122
+ built-in, and its Props type becomes the page form:
123
+
124
+ ```ts
125
+ interface StorePage extends Page {
126
+ theme: "light" | "dark";
127
+ }
128
+ export default { page: (props: StorePage) => props /* , ... */ } satisfies Blocks;
129
+ ```
130
+
131
+ `deco check` warns that Studio's page list and editor rely on the built-in `page`.
132
+ Keep the same fields so they keep working. The `seo` field then follows your type:
133
+ Studio offers a block for it only if the block's return type fits that type.
134
+
135
+ - **A routable type of your own** (blog posts, store locator entries). Make its Props
136
+ extend `Route` (`name` and `path`). A block whose Props have a `path` field but do not
137
+ extend `Route` is an error, and `deco schema` writes no schema until you fix it. Then
138
+ route it next to pages:
139
+
140
+ ```ts
141
+ const [posts] = await c.list<Post>("post");
142
+ const match = matchRoute(pathname, { routes: [...routes, ...posts] });
143
+ ```
144
+
145
+ `client.list(type)` returns entries as saved (nothing run) by default. Pass
146
+ `{ run: true }` to run them.
147
+
148
+ ## Checklist for a new page
149
+
150
+ 1. The path does not shadow another page (`deco check` reports conflicts).
151
+ 2. Header and footer are references to the shared saved blocks.
152
+ 3. Each section's type is a key in the block map, and `deco schema` is current.
153
+ 4. The page has `seo`, or you know which defaults it falls back to.
154
+ 5. A dynamic page's blocks get the params they need from the page loader.
155
+ 6. Open the page through `deco push --draft=<name>` and its preview link before
156
+ publishing.
@@ -0,0 +1,95 @@
1
+ # Review before publish
2
+
3
+ Run this before `deco push`, before opening a PR, and again before `deco publish`. Read
4
+ the diff (`git diff` for code, `deco diff` for content) and go through each item. The
5
+ command details are in the `deco-site-workflow` skill.
6
+
7
+ ## 1. The schema matches the code
8
+
9
+ - Run `deco schema`. It must print no errors. With an error it writes nothing, and
10
+ Studio keeps the old forms.
11
+ - In CI, `deco schema --check` fails when `.deco/schema.gen.json` is out of date.
12
+ Commit the regenerated file with the code change.
13
+ - Read every warning: `props are typed any` (empty form) and `returns any` (offered for
14
+ no field) are bugs.
15
+
16
+ ## 2. Existing content still fits
17
+
18
+ This is the check for breaking changes: a renamed or removed prop, a changed loader
19
+ return type, a removed block map key.
20
+
21
+ - `deco check` with no flag checks **production** content (when the site has
22
+ `DECO_SITE`) against your **local** `.deco/schema.gen.json`. That is exactly the
23
+ question "does my code change break pages already live?". Run it after `deco schema`.
24
+ - `deco check --draft=<name>` checks a draft's content. `--revision=<id>` checks a
25
+ published release.
26
+ - With no `DECO_SITE` anywhere, `deco check` checks the files in `.deco/blocks`.
27
+ - Exit code 1 means at least one error: an unknown block type, a field no type
28
+ declares (`unknown field`), a block that does not fit its field, two pages or
29
+ redirects matching the same URLs. Warnings do not fail it, but read them: a replaced
30
+ built-in, a `redirect` block that is not routed.
31
+
32
+ If a prop must change shape, keep the old field working until content is migrated, or
33
+ migrate the content in the same change and push it as a draft.
34
+
35
+ ## 3. Content edits are what you meant
36
+
37
+ - `deco diff` shows what `.deco/blocks` changes against what you pulled.
38
+ `deco diff --draft=<name>` compares against a draft.
39
+ - `deco push --draft=<name>` saves the changed blocks into a draft as one change and
40
+ prints its preview link. Open every page you touched through that link, at mobile and
41
+ desktop widths.
42
+ - Publish only with an explicit go-ahead: `deco publish --draft=<name>` prints the
43
+ changes first, then makes the draft live.
44
+
45
+ ## 4. Hardcoded text and styles
46
+
47
+ - Text a merchant would change (titles, labels, banners, links) is a prop, not a string
48
+ in the component. Fixed interface text (aria labels, "Add to cart" when the site has
49
+ no i18n) can stay in code.
50
+ - Styles use the site's design tokens (Tailwind theme values, CSS variables), not raw
51
+ values that have a token.
52
+ - A prop that only switches layout or spacing earns its place only if editors need it.
53
+
54
+ ## 5. Sections
55
+
56
+ - Props are typed with a named interface, and the block map uses `satisfies Blocks`.
57
+ - The section renders nothing for `undefined` and has a failed state on routes that
58
+ stream sections.
59
+ - Interactive parts are small `"use client"` components. No hooks in an element-mode
60
+ section itself.
61
+ - In descriptor mode, the new section has its union member, its block map key and its
62
+ `case` in the route's view.
63
+ - The route's Suspense fallback for the section is a skeleton of the right size.
64
+
65
+ ## 6. Loaders
66
+
67
+ - Each loader asks the upstream for only what the sections show.
68
+ - No loader mutates a result it got from another block.
69
+ - Blocks that need the same data resolve the same loader with identical inputs, so the
70
+ request makes one call (see [loaders.md](./loaders.md)).
71
+ - A loader that can fail has a decision: return empty, render nothing, or throw.
72
+ - Upstream calls go through an `@decocms/apps-*` client or `createInstrumentedFetch`.
73
+ - Expensive data a section may not use is a `Lazy<T>` prop.
74
+
75
+ ## 7. Secrets
76
+
77
+ - No token, API key or password in code, in `.deco/blocks`, or in a prop default.
78
+ Content holds no secrets on v8. Secrets live in the deploy platform and reach code
79
+ when the client is created.
80
+ - `.env` and `.dev.vars` are not committed.
81
+
82
+ ## 8. Dead code
83
+
84
+ - Every new file is imported. Every new block map key is used by content or meant for
85
+ editors.
86
+ - A removed block map key has no content left that uses it (`deco check` reports the
87
+ unknown type).
88
+ - No leftover v7 or Fresh imports (`apps/`, `$fresh`, `islands/`,
89
+ `@decocms/blocks/cms`).
90
+
91
+ ## 9. Order of release
92
+
93
+ Code that adds or changes a block must be deployed, and its schema pushed, before
94
+ content that uses it is published. Otherwise production resolves a type it does not
95
+ have (`UNKNOWN_BLOCK`). The deploy order is in the `deco-site-workflow` skill.