@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,138 @@
1
+ # Connect a site to deco Studio (and what happened to `deco serve`)
2
+
3
+ This page takes a v8 site from "Studio can't edit it" to "editors change content in Studio, preview
4
+ it, and publish it", with nothing else to read.
5
+
6
+ ## If Studio asks you to connect `deco serve`
7
+
8
+ `deco serve` served `.deco/` from your working tree to Studio over a local endpoint. It shipped in
9
+ `@decocms/blocks` 8.1 through 8.9.x. **It was removed in 8.10.0**, when content moved to Studio's
10
+ hosted CMS on the CDN. On 8.10+:
11
+
12
+ ```text
13
+ $ npx deco serve
14
+ unknown command "serve"
15
+ …
16
+ ```
17
+
18
+ (exit 64). Check the installed version with `npm ls @decocms/blocks`. `npx deco --help` lists the
19
+ commands this version has.
20
+
21
+ - **On 8.10 or newer:** there is nothing to run on your machine. Studio edits hosted drafts, and the
22
+ site reads them from the CDN. "Connecting" is Steps 1 to 5 below.
23
+ - **On 8.9.x or older:** upgrade `@decocms/blocks` (and the binding, `@decocms/tanstack` or
24
+ `@decocms/nextjs`, at the same version), then do Steps 1 to 5. This skill doesn't document the old
25
+ `deco serve` flags.
26
+ - The error `the endpoint speaks an older deco-content than this client needs (… or newer): update
27
+ @decocms/blocks (8.2.0 or newer) where the endpoint runs` comes from the content protocol client
28
+ when it reaches an older endpoint, such as an 8.1.x `deco serve`. Same fix: upgrade.
29
+
30
+ ## Step 1: the site reads hosted content
31
+
32
+ ```ts
33
+ // src/cms.ts
34
+ import { createCMS } from "@decocms/blocks";
35
+ import blocks from "../.deco";
36
+
37
+ export const cms = createCMS({ blocks, site: "my-store" });
38
+ ```
39
+
40
+ - `site` is Studio's site name. `@decocms/blocks` reads no environment variable: the site passes the
41
+ value, as a literal or from its own config. The CLI finds the same name in `DECO_SITE` (see
42
+ [schema.md](./schema.md), Step 2), so keep the two equal.
43
+ - Leave `content` out. Passing both `site` and `content` is a `TypeError`.
44
+ - A site moving from bundled content (`createCMS({ blocks, content })` with `.deco/blocks.gen.ts`)
45
+ drops `content`, the import of the generated module, and `deco content` from its scripts.
46
+
47
+ How the binding wires `cms` into routes and the worker is in `deco-tanstack-site` /
48
+ `deco-nextjs-site`.
49
+
50
+ ## Step 2: send the schema
51
+
52
+ ```bash
53
+ npx deco schema && npx deco schema push
54
+ ```
55
+
56
+ Without it, Studio has no forms. Tokens, errors and CI wiring: [schema.md](./schema.md).
57
+
58
+ ## Step 3: publish a first release, before you deploy with `site`
59
+
60
+ With `site` set, the site has no content until a release exists. The first request on a site whose
61
+ `latest.json` is missing (never published) fails with `LOADER_FAILED` (cause
62
+ `ContentUnavailableError`); the SDK never serves an empty site. So publish first:
63
+
64
+ ```bash
65
+ # .deco/blocks holds the content you have (bundled before, or written by hand)
66
+ npx deco push --draft=initial # every file is new: all of them go to the draft
67
+ npx deco check --draft=initial # the draft against the code
68
+ npx deco publish --draft=initial # the first release
69
+ ```
70
+
71
+ Then remove `.deco/blocks/` from git and add `.deco/blocks/` and `.deco/pull.json` to `.gitignore`.
72
+ `deco pull` fills the folder again when you need it. A push must fit one save (500 blocks, 8 MiB,
73
+ 1 MiB per block); for a bigger site see [content-sync.md](./content-sync.md#push).
74
+
75
+ A site with no content yet can skip this only if it creates its first blocks in Studio and publishes
76
+ before the deploy that sets `site`.
77
+
78
+ ## Step 4: the page accepts Studio's frame
79
+
80
+ Studio opens the site in an iframe and loads its editor code into the page through the **Studio
81
+ channel**, a small inline script the bindings put on every page:
82
+
83
+ - **TanStack** (`@decocms/tanstack`): `DecoDocument` in `__root.tsx` (or `<DecoPreview site=… />` in
84
+ a document of your own) mounts the bridge, the channel and the draft badge. `createDecoWorker` adds
85
+ Studio's origins to `frame-ancestors` and `script-src` and sends no `X-Frame-Options`.
86
+ - **Next.js** (`@decocms/nextjs`): `<StudioBridge site="my-store" />` in the root layout's `<body>`.
87
+ A site that writes its own CSP passes it through `withStudioCsp(directives)`. Render
88
+ `<StudioPage pathTemplate={match.entry.path} />` on CMS pages so Studio opens the right page.
89
+
90
+ The page trusts an exact list of Studio origins: the binding's `studioOrigins` option, else the
91
+ `DECO_STUDIO_ORIGIN` env var (comma-separated), else `https://studio.decocms.com` and
92
+ `https://studio-stg.decocms.com`. A page framed by any other origin does nothing. For a Studio you
93
+ run locally, set `DECO_STUDIO_ORIGIN=http://localhost:3000` (its origin) for the site, and
94
+ `DECO_STUDIO_URL` to its API base for the CLI.
95
+
96
+ ## Step 5: previews, in Studio and on your machine
97
+
98
+ Studio saves edits into a draft. A draft is seen through a link: `?__draft=<pointer>` on any page.
99
+ The CLI prints it:
100
+
101
+ ```bash
102
+ npx deco drafts url my-change
103
+ # a preview URL, or a pointer plus:
104
+ # (the site has no preview address in Studio: open the site with ?__draft=<this pointer>)
105
+ ```
106
+
107
+ A draft link previews only on allowed hosts: the ones Studio writes into the release
108
+ (`previewHosts` in `latest.json`) plus `createCMS({ preview: { hosts } })`. On any other host the link
109
+ silently renders the published release. That is the usual reason a draft "shows production" on
110
+ `localhost`. Allow it in dev:
111
+
112
+ ```ts
113
+ createCMS({
114
+ blocks,
115
+ site: "my-store",
116
+ // Vite dev; on Next.js test process.env.NODE_ENV === "development"
117
+ ...(import.meta.env.DEV ? { preview: { hosts: ["localhost"] } } : {}),
118
+ });
119
+ ```
120
+
121
+ A host pattern without a port matches any port. Before the first publish, or for a release published
122
+ before Studio wrote `previewHosts`, every host previews.
123
+
124
+ Local dev reads content from the CDN like production. Editing `.deco/blocks` locally changes nothing
125
+ on the page until you `deco push` it to a draft and open the draft link.
126
+
127
+ ## Diagnose a site Studio can't edit
128
+
129
+ | Symptom | Check | Fix |
130
+ |---|---|---|
131
+ | Studio says to send the schema, or forms are empty or stale | `npx deco schema push` prints `(a v8 schema)` | [schema.md](./schema.md) |
132
+ | Page in Studio is blank or refuses to frame | `curl -sI <url>`: `content-security-policy` has `frame-ancestors` with `https://studio.decocms.com`; no `x-frame-options` | Use the binding's worker or `withStudioCsp`; remove your own `X-Frame-Options` |
133
+ | Page shows, but no section outlines or live updates | Page HTML has a `<script data-deco-studio-channel …>`; its `data-studio-origins` lists Studio's origin | Mount `DecoDocument` / `DecoPreview` / `StudioBridge`; fix `studioOrigins` or `DECO_STUDIO_ORIGIN`; add the CSP `nonce` |
134
+ | Every page errors with `LOADER_FAILED` | `https://delivery.decocms.com/sites/<site>/latest.json` returns 404 | Publish a first release (Step 3) |
135
+ | Draft link shows the published content | Host not in the preview hosts | `preview.hosts` (Step 5) |
136
+ | Draft link shows the release and a notice that the draft can't be read | The draft no longer exists or can't be read | Get a fresh link with `deco drafts url <name>` |
137
+ | `/live/*`, `/.decofile`, `/deco/*` answer 404 | Expected on v8 (TanStack worker). `/deco/_liveness` answers `OK` | Remove v7 admin wiring; see `deco-v7-to-v8-migration` |
138
+ | A CLI command exits 3 | No token, or Studio refused it | [schema.md](./schema.md), Step 3 |
@@ -0,0 +1,67 @@
1
+ ---
2
+ name: deco-storefront-caching
3
+ description: "Edge caching and origin egress for storefronts on @decocms/blocks 8. Covers the site-owned pageCache on createDecoWorker from @decocms/tanstack/worker (isCacheable, cacheVersion keyed by build and content revision, assignmentsKey, segmentKey and the __cseg token, serverFnPagePath, DEGRADED_HEADER, markPrivate, drafts and old releases never cached, the purge route), cache-key rules (key only on what changes the payload, strip tracking params, segment without splitting for nothing, never store non-200, degraded or empty pages, one upstream call per request), the traps that kill hit rate or raise egress (Set-Cookie, tracking-param poisoning, region and device splits, Vary, redirects, hidden variants, payload bloat), the Next.js equivalents in @decocms/nextjs/proxy, and verification with curl, X-Cache headers, scripts/html-anatomy.mjs and Playwright guardrails. Load it when the hit rate drops, egress or upstream calls rise, a page is never cached, or a change touches the worker entry or the cache key."
4
+ ---
5
+
6
+ # Storefront caching and egress (v8)
7
+
8
+ On v8 the framework caches no page. `createDecoWorker` from `@decocms/tanstack/worker` decides
9
+ drafts, the visitor and each test's assignment, then hands every cacheable request to the site's
10
+ own `pageCache`. The cache key, the TTLs and the purge route live in the site's
11
+ `src/worker-entry.ts`, usually a copy of the repo's example. So when the hit rate drops, the cause
12
+ is almost always in site code: the key, a cookie, a header, or a page that should not be stored.
13
+
14
+ Read this when you arrived with a number (egress up, hit rate down, upstream bill up) or with a
15
+ change to the worker entry, a loader on a cacheable page, or the segment.
16
+
17
+ ## When to load what
18
+
19
+ | Reference | Load it when |
20
+ |---|---|
21
+ | [`references/worker-page-cache.md`](./references/worker-page-cache.md) | Wiring or changing `pageCache`: what the worker does for you, the helpers, profiles and TTLs, stale serving, server functions and `__cseg`, the purge route |
22
+ | [`references/cache-keys.md`](./references/cache-keys.md) | Writing or reviewing the key or `buildSegment`; a page cached empty or broken; deduping upstream calls; an upstream data cache |
23
+ | [`references/egress-traps.md`](./references/egress-traps.md) | Hit rate is low or egress is high and you need the list of causes, in the order to check them |
24
+ | [`references/verification.md`](./references/verification.md) | Proving a fix: curl probes, the headers to read, `scripts/html-anatomy.mjs`, telemetry |
25
+ | [`references/perf-guardrails-e2e.md`](./references/perf-guardrails-e2e.md) | Locking the gains in CI with a Playwright spec and probes |
26
+ | [`references/nextjs.md`](./references/nextjs.md) | The site runs on `@decocms/nextjs` instead of the TanStack worker |
27
+ | [`references/case-study.md`](./references/case-study.md) | You want a worked example of an egress audit, with measured numbers and two reverts |
28
+
29
+ `scripts/html-anatomy.mjs` (Node 18+, no dependencies) shows where the bytes of a page go:
30
+ `node .agents/skills/deco-storefront-caching/scripts/html-anatomy.mjs https://SITE/category`.
31
+
32
+ ## The model in five lines
33
+
34
+ 1. A request reaches `pageCache` only if `isCacheable` accepts it: a `GET` of the current release,
35
+ no draft signal, no `Authorization`, not `/_build`, not `vite dev`. Everything else skips it.
36
+ 2. Every key carries `cacheVersion(cms, __BUILD_HASH__, url)`: `<build>.<content revision>`. A
37
+ deploy or a publish moves every page to new entries. Nothing to purge after a publish.
38
+ 3. Every key carries `assignmentsKey(page.assignments)`: the tests on and the campaigns running,
39
+ never the visitor id. Visitors on the same side of every test share one entry.
40
+ 4. The worker adds the visitor's first-visit cookie after `pageCache` answers, so a stored copy
41
+ never carries it. Any other `Set-Cookie` outside the example's `SAFE_COOKIES` makes it treat
42
+ the response as private and not store it.
43
+ 5. A response that sets no `CDN-Cache-Control` leaves the worker with `CDN-Cache-Control: no-store`.
44
+ The example lets the CDN keep only server-function data whose `__cseg` token matches.
45
+
46
+ ## Order of work for "egress is high"
47
+
48
+ 1. Get the numbers first: which paths, how many bytes, hit rate per path (`deco-performance-audit`
49
+ in decocms/skills, or the `http.server.request.duration` metric by `cache` and `http.route`).
50
+ 2. Pages that are never stored (`X-Cache: BYPASS`) cost on every visit. Fix those first.
51
+ 3. Then keys that split for nothing (tracking params, region, device, assignments).
52
+ 4. Then the size of what is stored (a fat HIT is still egress).
53
+ 5. Lock it in with the Playwright guardrails, then watch telemetry for 24 hours.
54
+
55
+ ## Related skills
56
+
57
+ - `deco-tanstack-site`: the worker entry, `createStart` with `decoServerFnFetch`, the router.
58
+ - `deco-nextjs-site`: Next.js setup; its caching reference covers ISR in depth.
59
+ - `deco-variants`: keeping variant pages cacheable, client-side personalization.
60
+ - `deco-storefront-performance`: payload trimming, duplicate upstream calls, Worker memory.
61
+ - `deco-apps`: which commerce responses are shopper-invariant and safe to cache.
62
+ - `deco-go-live`: the cache checks in the cutover list.
63
+ - `deco-v7-to-v8-migration`: moving v7's `createDecoWorkerEntry`, `buildSegment` and cache
64
+ profiles into the worker entry (its caching-and-privacy reference).
65
+ - decocms/skills: `deco-performance-audit` (CDN numbers), `deco-bot-management` and
66
+ `deco-cloudflare-waf` (crawler traffic), `deco-e2e-testing` (Playwright harness).
67
+ - Runbook: `docs/runbooks/cache-hit-drop.md` in this repo, for the cache-hit-drop alert.
@@ -0,0 +1,129 @@
1
+ # Cache keys and what may be stored
2
+
3
+ One rule decides most hit-rate bugs: **the key holds exactly what changes the response, and
4
+ nothing else.** Too little in the key serves the wrong page to someone. Too much splits one page
5
+ into many entries that each miss.
6
+
7
+ ## The example's key
8
+
9
+ `cacheKey(url, parts)` in the example worker entry builds a `Request` from:
10
+
11
+ | Part | Where it comes from | Why |
12
+ |---|---|---|
13
+ | Path and query | `page.url`, minus the hash, `TRACKING_PARAMS` and `__cseg` | The page itself |
14
+ | `payload` | Server functions only, canonicalized (`skuId`, `idsku` dropped from page paths) | The page data the call loads |
15
+ | `__v` | `cacheVersion(cms, __BUILD_HASH__, url)` | A deploy or publish moves every entry |
16
+ | `__seg` | `segmentKey(segmentOf(request))` | Device and the site's own parts |
17
+ | `__a` | `assignmentsKey(page.assignments)` | Which side of each test, which campaigns |
18
+ | `__fetch` | `Sec-Fetch-Dest: empty` on a page URL | A programmatic fetch gets its own entry, as in v7 |
19
+
20
+ Use the same function for lookup, store and purge. Two functions drift, and then a purge
21
+ silently deletes nothing.
22
+
23
+ ## Rules
24
+
25
+ ### 1. Strip tracking parameters, and add yours
26
+
27
+ The example drops `utm_source`, `utm_medium`, `utm_campaign`, `utm_term`, `utm_content`,
28
+ `utmi_campaign`, `utmi_page`, `utmi_part`, `fbclid`, `gclid`, `gclsrc`, `dclid`, `msclkid`,
29
+ `twclid`, `li_fat_id`, `mc_cid`, `mc_eid`, `ttclid`, `srsltid` (case-insensitive name match).
30
+
31
+ Check your real traffic for others and add them to `TRACKING_PARAMS`. Common ones not in the list:
32
+ `gad_source` and other `gad_*`, `gbraid`, `wbraid`, `_gl`. A param that is not in the list makes
33
+ every ad click a new entry.
34
+
35
+ Stripping a param from the key is only half the job. The page was rendered with the raw URL. See
36
+ "tracking-param poisoning" in `egress-traps.md` before you trust it.
37
+
38
+ ### 2. Never the visitor, always the assignments
39
+
40
+ `page.visitor` must never be in the key: every visitor would miss. `assignmentsKey` is what the
41
+ page renders by. Two visitors on the same side of every test share an entry. More running tests
42
+ mean more entries per URL (up to 2^tests); retire finished tests. `deco-variants` covers the rest.
43
+
44
+ ### 3. Segment only by what the content varies by
45
+
46
+ `buildSegment(request)` in the worker entry returns the device plus the site's own parts (a
47
+ region, a sales channel). Each part multiplies the entries per URL.
48
+
49
+ - Add a part only if the HTML differs by it. Ask: would two requests that differ only in this
50
+ part get byte-identical pages? If yes, it does not belong in the key.
51
+ - Region is the usual offender. A part filled from the CDN's geo header on every request splits
52
+ each URL by every region, even when one region sees different content. On VTEX, use the
53
+ regionalization `regionId` the shopper actually has, or move the regional choice to the
54
+ browser and a separate cacheable URL.
55
+ - Device: the example keys every page by device. If a page renders the same HTML for all devices,
56
+ the device split only lowers the hit rate for it.
57
+ - `loggedIn: true` makes the request private: never read from or written to the cache. Detect it
58
+ from the cookie your sign-in flow actually sets. A cookie that every returning visitor carries
59
+ (a checkout or cart cookie) turns most traffic private.
60
+
61
+ ### 4. Keep the key stable
62
+
63
+ Order changes must not change the key. `segmentKey` and `assignmentsKey` sort their parts, and the
64
+ example canonicalizes server-function payloads with `JSON.stringify` after a walk. If you add a
65
+ part built from an object, sort its keys first.
66
+
67
+ ### 5. Store only clean 200s
68
+
69
+ The example stores a render only if it is a 200, not degraded, not private. Keep all three.
70
+
71
+ - A non-200 (a CMS 404 page through `x-page-status`, a 5xx) is never stored.
72
+ - An empty or partial page that answers 200 is the dangerous one. In v8 a block read returns a
73
+ `[value, error]` result instead of throwing. If a section's loader failed or the upstream returned
74
+ `null`, the page can still render a 200 with an empty grid. Stored, every visitor gets it for the
75
+ whole fresh and stale window.
76
+ - Fix: when a loader the page needs fails or returns nothing, set `x-deco-degraded: true`
77
+ (`DEGRADED_HEADER`). The example then serves a stale copy if it has one, and never stores the
78
+ degraded render. Treat "no products where products are required" as a failure, not as data.
79
+ - Do not add a process-wide "last good" copy on top of the page cache. The stale windows already
80
+ do that, and an extra copy per isolate diverges between isolates and hides real failures.
81
+
82
+ ### 6. Private data never shares a URL's entry
83
+
84
+ - Cart, user, wishlist, addresses: server functions that call `markPrivate()`, or answer with
85
+ `Cache-Control: private, no-store`. The example never stores them.
86
+ - Do not write a cookie while rendering a cacheable page. Move the write to a POST handler or a
87
+ private server function. A cookie on the response makes the example bypass, which is safe but
88
+ costs a render every time.
89
+ - Do not strip `Set-Cookie` or override `private` to "fix" the hit rate. The private header is
90
+ usually there because the response depends on the shopper (price table, campaign).
91
+
92
+ ## One upstream call per request
93
+
94
+ Several sections often need the same upstream data.
95
+
96
+ - Inside one request, `@decocms/blocks` already runs each block function once per canonical input:
97
+ the resolver keeps one promise per function and inputs, for that request only. Two sections
98
+ that resolve the same loader block with the same props share one call.
99
+ - Block bodies (the content) are fetched once per hash per isolate and shared by concurrent
100
+ requests.
101
+ - Across requests, the example does not coalesce concurrent misses. Two requests that miss the
102
+ same key at once both render. Stale-while-revalidate keeps this rare on hot pages. If a viral
103
+ page's misses hurt the upstream, add a lock in your own `pageCache`; nothing in the framework
104
+ provides one.
105
+ - If you write a helper that calls the upstream directly, dedupe it per request (a `Map` of key to
106
+ promise that drops a rejected promise), never per process.
107
+
108
+ `deco-storefront-performance` covers finding the duplicate calls.
109
+
110
+ ## Upstream data cache
111
+
112
+ v8 has no framework loader cache (v7's `createCachedLoader` is gone). An upstream cache is a
113
+ `fetch` you write and pass to the client:
114
+
115
+ - `createVtexClient({ ..., fetch })` from `@decocms/apps-vtex`; the other `@decocms/apps-*` clients
116
+ take a `fetch` option too. They all go through `createInstrumentedFetch` from
117
+ `@decocms/blocks/fetch`.
118
+ - A response your fetch serves from its cache should carry `x-cache: HIT`: the
119
+ `http.client.request.duration` metric then labels it `cached=true`.
120
+ - Key it on everything the response depends on (the VTEX client's docs name `regionId`; also the
121
+ sales channel, locale, price table). Cache only shopper-invariant responses (`deco-apps`).
122
+ - An in-memory cache is per isolate and TTL-only. A long TTL delays every upstream change, deploy
123
+ or not. Keep it to seconds or minutes.
124
+
125
+ ## Test the key
126
+
127
+ The example's `worker-entry.test.ts` shows the shape: tracking params share one entry, devices get
128
+ their own, the purge's keys equal the stored keys. Add a case for every part you add to
129
+ `buildSegment`, and one that asserts two visitors in the same test bucket share a key.
@@ -0,0 +1,82 @@
1
+ # Case study: an egress audit on a VTEX storefront
2
+
3
+ A worked example. The site ran on the v1 Fresh/Deno stack, so the code it changed (loader
4
+ `cacheKey` exports, a Redis loader cache, site middleware) does not exist on v8. The lessons do;
5
+ each one ends with where it lives on v8.
6
+
7
+ ## Starting point
8
+
9
+ - About 88 GB a week of CDN egress, about 52% cache hit rate.
10
+ - One listing page at 13 MB of HTML was 46% of a day's egress on its own.
11
+ - On a second VTEX storefront audited the same way, the origin was about 41% of a cluster's
12
+ cost, almost all egress.
13
+
14
+ ## What happened, in order
15
+
16
+ **1. The broad first cut.** Capped listing size at 48 products, set cache headers per path, took
17
+ tracking params out of the loader cache key, blocked aggressive crawlers (about 26% of bandwidth
18
+ was crawlers stacking filter combinations), redirected URLs with three or more stacked filters to
19
+ the clean path, and fixed layout shift (home desktop CLS from 0.42 to 0.0025).
20
+
21
+ **2. The hit rate dropped, from 52% to 38%.** CDN telemetry showed three causes curl had not:
22
+ top-level category links answered a 307 with no cache headers, so every main-menu click went to
23
+ origin; a static sprite answered `Vary: If-None-Match`, splitting its cache by ETag; listing TTLs
24
+ were too short. The device was also dropped from the listing key, since listings rendered the same
25
+ for every device.
26
+ *v8:* trap 5 (redirects), trap 4 (`Vary`), trap 3 (device split) in `egress-traps.md`.
27
+
28
+ **3. Every returning visitor was private.** The site's middleware bypassed the cache when the
29
+ *request* carried the checkout cookie, which VTEX sets for almost every returning visitor, even
30
+ with an empty cart. Checking the *response* for a new cookie instead fixed it.
31
+ *v8:* `loggedIn` in `buildSegment` must read the sign-in cookie only (`cache-keys.md`, rule 3).
32
+
33
+ **4. Payload trim.** Warm responses still averaged 180 KB compressed, because a HIT serves whatever
34
+ the miss produced. The product graph carried about 32 installment price entries per offer, and each
35
+ color swatch carried a full product.
36
+
37
+ | Page | Before | After |
38
+ |---|---|---|
39
+ | Best-sellers listing, raw HTML | 28.7 MB | 2.89 MB (−89.9%) |
40
+ | Same page, `UnitPriceSpecification` count | 63,744 | 585 (−99.1%) |
41
+ | Campaign listing, raw HTML | 5.84 MB | 1.77 MB (−69.7%) |
42
+
43
+ Cards were trimmed to the two price entries they read; the product detail page, the one consumer of
44
+ the full graph, was left alone. The same audit found the CDN's "cache by device type" rule was off,
45
+ so mobile HTML could be served to desktop.
46
+ *v8:* trap 8 and `deco-storefront-performance`.
47
+
48
+ **5. A consolidation, a revert, a re-land.** Three listing sections were merged into one with one
49
+ cached payload, plus a custom "last good copy" and failure backoff on top of the loader cache. The
50
+ upstream search returns `null` instead of throwing for some queries. The merged loader turned that
51
+ into a valid-looking empty result, the cache kept it for 30 minutes, and mobile users saw an empty
52
+ listing. Reverted four hours later. The re-land threw on `null` (errors were not cached), dropped
53
+ the custom layer, and kept the sections separate: an in-request dedupe still gave one upstream
54
+ call per render, and a failure now emptied one section instead of the whole page.
55
+ *v8:* rule 5 (store only clean 200s, `x-deco-degraded`) and single-flight in `cache-keys.md`.
56
+
57
+ **Last: the cache that held one key.** The loader cache had a single 8.4 MB entry. Every cached
58
+ loader gated its key on "anonymous visitor", and the platform's segment cookie marks a visitor as
59
+ not anonymous as soon as it carries any `utm_*` field, so about 99% of real traffic skipped the
60
+ cache. Gating on the fields that change the response (sales channel privacy, campaigns, price
61
+ tables, region) and keying on those fields only fixed it. Probes for 3 listings × 7 visitor
62
+ profiles then asserted that every profile hit the same entry.
63
+ *v8:* rules 1 to 3 in `cache-keys.md`, the fingerprint probe in `perf-guardrails-e2e.md`.
64
+
65
+ ## Outcome
66
+
67
+ Projected 25 to 30 GB a week, from about 88: roughly a 65–70% drop, over 11 merged changes and two
68
+ reverts.
69
+
70
+ ## Lessons
71
+
72
+ 1. A HIT is not the goal. The key must exist for real traffic, the stored body must be small, and
73
+ nothing may split the entry for no reason.
74
+ 2. Test the failure path. Most of the regressions were "the upstream returned something odd and
75
+ we cached it".
76
+ 3. Do not build a cache on top of a cache. A per-process "last good" copy diverges between
77
+ processes and hides failures.
78
+ 4. Check what the CDN actually does. A header that looks right in curl is not proof that the CDN
79
+ caches by it. A diagnostic response header that echoes what the CDN saw found the device rule
80
+ in minutes.
81
+ 5. One merged section is one failure domain. Keep sections that can fail separately apart.
82
+ 6. Be exact about request cookies vs response cookies when a cookie decides cacheability.
@@ -0,0 +1,153 @@
1
+ # Traps that kill hit rate or raise egress
2
+
3
+ Check them in this order. The first ones make pages uncacheable, and an uncacheable page costs on
4
+ every visit: a 6 MB page served from the cache costs no render, a 150 KB page never cached costs
5
+ one render and one set of upstream calls per view. Later traps also give misleading signals until
6
+ the earlier ones are fixed.
7
+
8
+ Each trap has a symptom, a probe (commands in `verification.md`), and a fix.
9
+
10
+ ## 1. The page is never stored
11
+
12
+ **Symptom.** `X-Cache: BYPASS` on every request to a public page. Read `X-Cache-Reason`:
13
+
14
+ | Reason | What to look at |
15
+ |---|---|
16
+ | `private-response` | A `Set-Cookie` on the render (a loader or section writing a cookie), or `Cache-Control: private/no-store` from a route or a server function. Find who sets it. Move cookie writes to a POST handler or private server function. |
17
+ | `private` | `buildSegment` returned `loggedIn: true`. Check which cookie it reads. A cookie every returning visitor has (cart, checkout, session id) makes almost all traffic private. Read the cookie the sign-in flow sets, never "any cookie present". |
18
+ | `status:<code>` | The render was not a 200. A 404 for a real page means routing; a redirect status means the page itself redirects. |
19
+ | `degraded` | A loader failed and the page set `x-deco-degraded`. Fix the upstream, or the condition that sets it. |
20
+ | `profile:<name>` | The URL matched `private` or `none`, or a profile with edge `fresh` 0. Check `pageProfile` for a rule that is too broad. |
21
+
22
+ No `X-Cache` at all on a page means `pageCache` never ran: a preview (draft cookie or
23
+ `?__draft=`), an `Authorization` header, a `HEAD` request, `vite dev`, or your `routes` answered it.
24
+
25
+ ## 2. Tracking-param poisoning
26
+
27
+ **Symptom.** One visitor's `gclid` or `utm_*` value shows up in the HTML other visitors get;
28
+ attribution is wrong; or ad traffic misses while plain traffic hits.
29
+
30
+ **Cause.** The key drops tracking params (`cache-keys.md`), but the page was rendered from the raw
31
+ URL. Anything that echoes the URL (canonical or `og:url` built from the request, analytics
32
+ payloads, pagination links, router state embedded in the HTML) carries the value. The example
33
+ stores that render under the clean key, so everyone gets it.
34
+
35
+ Server functions have the same problem one level down: the page path inside `payload` can carry
36
+ tracking params. The example strips only `skuId` and `idsku` from it.
37
+
38
+ **Probe.** Request `?gclid=POISON42` until it is stored, then the clean URL, and grep for
39
+ `POISON42`. It must be 0.
40
+
41
+ **Fix, in order of preference.**
42
+ 1. Do not echo the raw query into the page. Build canonical and pagination URLs from the
43
+ parameters the page uses.
44
+ 2. In `pageCache`, let a request that carried a tracking param read the clean entry but never
45
+ write it (skip `store`). This was v7's guard; the v8 example does not do it, so add it yourself
46
+ if your pages echo the URL.
47
+ 3. Strip tracking params from page paths inside the server-function `payload` in
48
+ `canonicalPayload`, and from any URL the browser builds from `location.search` for a
49
+ client-side fetch.
50
+
51
+ ## 3. The key splits for nothing
52
+
53
+ **Symptom.** Hit rate low on pages that are clearly public, with many distinct `X-Cache-Segment`
54
+ or URL variants per path.
55
+
56
+ - **Region.** A `buildSegment` part from the CDN's geo header splits every URL by region. Keep
57
+ only parts the HTML varies by.
58
+ - **Device.** Fine when mobile and desktop HTML differ. Wasteful when they don't.
59
+ - **Unlisted query params.** A new campaign param, a sort default spelled two ways, a crawler that
60
+ stacks filters in random order. Look at the raw URLs behind the misses.
61
+ - **Assignments.** Every running test multiplies entries. Retire finished tests.
62
+
63
+ ## 4. `Vary` splits or blocks the cache
64
+
65
+ `Vary` tells every cache in the path to keep one copy per value of each listed request header.
66
+ `Vary: Cookie` or `Vary: User-Agent` on a public page means one copy per visitor or per browser
67
+ build in any cache that honors it. `Vary: If-None-Match` (seen from static-file servers) splits by
68
+ ETag, which defeats a year-long TTL.
69
+
70
+ The example sets `Vary: Accept-Encoding` on the answers it gives from its cache or a fresh store,
71
+ replacing what the app sent. A `BYPASS` answer keeps the app's `Vary`, and so do your `routes`
72
+ answers. The worker sets `Vary: Accept-Encoding` on fingerprinted assets and on `/fonts/`. Any
73
+ other file (a sprite or icon in `public/` without a hash in its name) is not an asset to the worker:
74
+ it goes through `pageCache` like a page. Previews get `Vary: Cookie`, which is correct for them.
75
+ Probe public URLs and static files for any other token.
76
+
77
+ ## 5. Redirects
78
+
79
+ CMS redirects are answered by the worker before your `routes` and before `pageCache`. They carry
80
+ no `Cache-Control`, leave with `CDN-Cache-Control: no-store`, and are measured on one
81
+ `http.route`, `redirect`, with `cache` `BYPASS`.
82
+
83
+ Each one is a Worker invocation, not a page render: no commerce upstream is called, and the
84
+ redirects block body is kept per isolate once fetched. That is cheap. It only matters when
85
+ main-navigation links point at a redirecting URL, so every click pays a round trip. Fix the links
86
+ first.
87
+
88
+ If you cache redirects in front of the worker, cache only those that stay on the same host and
89
+ protocol and do not point at themselves. A cached leg of a redirect loop freezes the loop.
90
+
91
+ ## 6. Hidden variants rendered in full
92
+
93
+ **Symptom.** The HTML carries N copies of a grid or menu, and CSS or an A/B script shows one.
94
+ `html-anatomy.mjs` lists the same blob N times.
95
+
96
+ **Fix.** Render the active variant on the server. Each other variant is an empty wrapper that
97
+ loads its content through a cacheable GET only when it becomes visible. A `display:none` element
98
+ never intersects, so it never loads. "Render everything, hide with CSS" is acceptable only for
99
+ something as small as a label. `deco-variants` covers variants that stay cacheable.
100
+
101
+ ## 7. Calls on every page view that can't be cached, or that create state
102
+
103
+ **Symptom.** Every view fires a POST or a `no-store` GET, or a cookieless visitor gets a new
104
+ upstream cart (`Set-Cookie` for a cart id on a request with no cookies).
105
+
106
+ **Fix.**
107
+ - No cart cookie means no cart: return an empty cart without calling the upstream.
108
+ - Keep that response private anyway (`markPrivate()`): the URL is shared, and an empty cart
109
+ stored for one visitor would be served to a shopper who has items.
110
+ - Don't fire a session or profile POST when there is no auth cookie and nothing to change.
111
+ - Check third-party scripts in the browser's network panel. Some create carts too.
112
+
113
+ ## 8. Payload bloat that compression hides
114
+
115
+ **Symptom.** Pages of several MB raw. Compressed size looks fine, but every miss renders and
116
+ transfers it, every client-side navigation fetches its data again, and parse and hydration time
117
+ grow. A cache HIT does not mean a small response.
118
+
119
+ Usual causes, as `html-anatomy.mjs` ranks them:
120
+ - Full product objects in serialized page data when a card needs ten fields. Map to a small card
121
+ model in the loader, before anything is cached or rendered.
122
+ - The same product serialized once per size or color button. Emit it once and reference it by id.
123
+ - Analytics payloads per card (`data-event` attributes). Send the shared part once.
124
+ - One script inlined per component instance. Emit the code once; pass each instance's props.
125
+
126
+ `deco-storefront-performance` has the trimming method and which fields each consumer reads.
127
+
128
+ ## 9. Traffic you asked the browser to make
129
+
130
+ - Fetches on mount for UI that is closed (drawers, store locators). Fetch on open.
131
+ - Prefetch or prerender rules your site adds. A hover can download a whole page and its scripts.
132
+ Keep them conservative on dense menus.
133
+ - A page's own data fetched again right after a cached HTML load, with no interaction. Find what
134
+ triggers it before shipping; it doubles the transfer of that page.
135
+
136
+ ## 10. Crawlers
137
+
138
+ A crawler stacking filter combinations creates unique URLs that never hit. One measured audit
139
+ found about a quarter of bandwidth came from crawlers. That is a WAF and bot-management job
140
+ (`deco-bot-management`, `deco-cloudflare-waf` in decocms/skills), not a cache key change.
141
+
142
+ ## PR review checklist
143
+
144
+ - [ ] A new or changed loader on a cacheable page depends only on props and the URL's real
145
+ params. No request headers other than cookies for private data.
146
+ - [ ] A loader that can fail or return nothing sets `x-deco-degraded`.
147
+ - [ ] No cookie written while rendering a cacheable page.
148
+ - [ ] `buildSegment` adds only parts the HTML varies by. `loggedIn` reads the sign-in cookie.
149
+ - [ ] No raw query string echoed into the HTML.
150
+ - [ ] Variant UI: only the active variant rendered on the server.
151
+ - [ ] New per-view request: a cacheable GET, and it creates no state for anonymous visitors.
152
+ - [ ] `html-anatomy.mjs` before and after on the heaviest page: nothing repeated N times.
153
+ - [ ] Changed key: lookup, store and purge still use the same function; tests updated.
@@ -0,0 +1,60 @@
1
+ # Next.js: the same rules on @decocms/nextjs
2
+
3
+ `@decocms/nextjs` caches nothing either. Caching is Next's own (ISR, the full route cache) and
4
+ whatever CDN sits in front. The binding's job is to make that safe: a cached page must never be a
5
+ preview, and must never be keyed on the visitor. The setup itself is in `deco-nextjs-site`.
6
+
7
+ ## What `@decocms/nextjs/proxy` does
8
+
9
+ `draftProxy(proxyCms, options)` is the whole flow for a site without a proxy of its own. A site
10
+ with one calls `decideDraft`, `decideVisitor`, `decideAssignments`, the `*RequestHeaders` helpers
11
+ and `applyDraft` / `applyVisitor` itself.
12
+
13
+ | Request | What happens | Cache effect |
14
+ |---|---|---|
15
+ | Any draft signal (`?__draft=`, `off` included, or the draft cookie) | Rewritten onto the dynamic draft route (`/_draft/<path>`, mounted as `app/%5Fdraft/...`) | Never cached. `Cache-Control: max-age=0, no-cache, must-revalidate`, `Vary: Cookie`, `X-Robots-Tag: noindex, nofollow` |
16
+ | A published CMS page, with `options.assignments(request)` true | Rewritten onto `/_assignments/<assignments>/<path>` (`rewriteToAssignmentsRoute`) | Next keeps one cached page per set of assignments. The visitor id is never in the path |
17
+ | Anything else | Forwarded with `x-deco-version`, `x-deco-visitor`, `x-deco-assignments` | Your route decides |
18
+
19
+ On the assignments route the page builds its client with `assignedClient(cms, segment)` from
20
+ `@decocms/nextjs/server`, which reads no request, so Next can cache it:
21
+
22
+ ```tsx
23
+ export const revalidate = 600;
24
+ export async function generateStaticParams() {
25
+ return [];
26
+ }
27
+ export default async function Page({ params }) {
28
+ const { assignments, path } = await params;
29
+ const client = await assignedClient(cms, assignments);
30
+ if (!client) notFound();
31
+ // …
32
+ }
33
+ ```
34
+
35
+ With `revalidate = 600`, a page can be about ten minutes stale; the first request after that
36
+ still gets the old page while Next renders again.
37
+
38
+ ## The visitor URL vs the cached route
39
+
40
+ When the content has saved tests or campaigns, the proxy marks the response to the URL the visitor
41
+ asked for `Cache-Control: private, no-cache`. Next caches the rewritten route, but the original
42
+ URL answers differently by cookie and by moment, so a CDN in front must not keep it under that
43
+ URL.
44
+
45
+ A CDN that should cache in front of Next keys on the request's assignments, never the visitor:
46
+ `assignmentsKey(await decideAssignments(proxyCms, draft, visitor))`, `""` when there are none.
47
+ `assignmentsKey` is exported from `@decocms/nextjs/proxy` with the same output as the TanStack
48
+ worker's.
49
+
50
+ ## What carries over from the TanStack references
51
+
52
+ - `cache-keys.md`: everything except the example's `cacheKey` and `pageCache` code. Tracking
53
+ params, segments, never storing degraded or empty pages, private responses, single-flight.
54
+ - `egress-traps.md`: all traps; read `X-Cache` and `X-Cache-Reason` only if your CDN or code sets
55
+ them. Next's own response headers tell you whether a page came from its cache.
56
+ - `verification.md`: the probes, with your CDN's headers in place of the example's.
57
+
58
+ What does not carry over: `createDecoWorker`, `pageCache`, `cacheVersion`, `__cseg` and
59
+ `decoServerFnFetch`, and the example's purge route. On Next, a release reaching cached pages is a
60
+ question of `revalidate` and Next's own invalidation.