@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,177 @@
1
+ # The proxy and draft previews
2
+
3
+ The proxy (`src/proxy.ts`, Next 16's name for middleware) decides once per
4
+ request what the request reads. The pages only render that decision. This
5
+ split is what lets published pages stay cached while Studio previews render
6
+ fresh.
7
+
8
+ ## What the proxy decides
9
+
10
+ | Step | Function (`@decocms/nextjs/proxy`) | Result |
11
+ |---|---|---|
12
+ | Version | `decideDraft(proxyCms, request)` | A Studio link's draft or old release on an allowed host, its preview moment (`__at`) and switched tests and campaigns (`__test`, `__campaign`), the cookie to set |
13
+ | Visitor | `decideVisitor(request, draft)` | The `deco_segment` cookie, or a new visitor. Its cookie is sent on a first visit only, never when the request renders a draft or an old release |
14
+ | Tests and campaigns | `decideAssignments(proxyCms, draft, visitor)` | Each test of the saved `experiments` block on or off, each campaign of the saved `campaigns` block running or not. Missing blocks give none, never an error |
15
+
16
+ It forwards them to the page on request headers, always removing copies sent
17
+ from outside:
18
+
19
+ | Header | Set by |
20
+ |---|---|
21
+ | `x-deco-version` | `draftRequestHeaders(request, draft)` |
22
+ | `x-deco-visitor` | `visitorRequestHeaders(headers, visitor)` |
23
+ | `x-deco-assignments` | `assignmentsRequestHeaders(headers, assignments)` |
24
+
25
+ On the response, `applyDraft(response, draft)` sets the draft cookie and, on
26
+ any preview, `Cache-Control: max-age=0, no-cache, must-revalidate`,
27
+ `Vary: Cookie` and `X-Robots-Tag: noindex, nofollow`. `applyVisitor` sets the
28
+ visitor cookie.
29
+
30
+ ## The proxy
31
+
32
+ ```ts
33
+ // src/proxy.ts
34
+ import {
35
+ applyDraft, applyVisitor, assignmentsRequestHeaders, decideAssignments, decideDraft,
36
+ decideVisitor, draftRequestHeaders, isAssignmentsRoutePath, isDraftRoutePath,
37
+ rewriteToAssignmentsRoute, rewriteToDraftRoute, visitorRequestHeaders,
38
+ } from "@decocms/nextjs/proxy";
39
+ import { type NextRequest, NextResponse } from "next/server";
40
+ import { proxyCms } from "./cms.proxy";
41
+
42
+ export async function proxy(request: NextRequest) {
43
+ const { pathname } = request.nextUrl;
44
+ // Only the rewrites below may reach these routes.
45
+ if (isDraftRoutePath(pathname) || isAssignmentsRoutePath(pathname)) {
46
+ return new NextResponse("Not found", { status: 404 });
47
+ }
48
+ const draft = await decideDraft(proxyCms, request);
49
+ const visitor = decideVisitor(request, draft);
50
+ const assigned = isCmsPage(pathname)
51
+ ? await rewriteToAssignmentsRoute(proxyCms, request, draft, visitor)
52
+ : null;
53
+ if (assigned) return applyVisitor(applyDraft(assigned, draft), visitor);
54
+ const assignments = await decideAssignments(proxyCms, draft, visitor);
55
+ const headers = assignmentsRequestHeaders(
56
+ visitorRequestHeaders(draftRequestHeaders(request, draft), visitor),
57
+ assignments,
58
+ );
59
+ const response =
60
+ rewriteToDraftRoute(request, draft, visitor, assignments) ??
61
+ NextResponse.next({ request: { headers } });
62
+ return applyVisitor(applyDraft(response, draft), visitor);
63
+ }
64
+
65
+ // The app's own routes, outside the CMS.
66
+ function isCmsPage(pathname: string): boolean {
67
+ return pathname !== "/blog";
68
+ }
69
+
70
+ // Next's own files must not go through the proxy: rewritten, every script and style is a 404.
71
+ export const config = { matcher: ["/((?!_next/|favicon.ico).*)"] };
72
+ ```
73
+
74
+ - `rewriteToAssignmentsRoute` returns `null` for a preview, so a preview
75
+ falls through to `rewriteToDraftRoute`.
76
+ - `rewriteToDraftRoute` returns `null` when the request carries no draft
77
+ signal; the request then goes on with the forwarded headers.
78
+ - `isCmsPage` is the site's own. Routes the app owns (a blog index, an API
79
+ route) render as before and still get the forwarded headers.
80
+
81
+ **A site with no proxy logic of its own** exports
82
+ `draftProxy(proxyCms, options)` instead:
83
+
84
+ ```ts
85
+ export const proxy = draftProxy(proxyCms, {
86
+ assignments: (request) => isCmsPage(request.nextUrl.pathname),
87
+ });
88
+ ```
89
+
90
+ `assignments` picks the paths rewritten to the assignments route (default:
91
+ none) and makes direct hits on that route a 404. `rewrite` picks which
92
+ previews go to the draft route (default: all); return `false` for a route
93
+ that is already dynamic and binds the draft itself.
94
+
95
+ ## The draft route
96
+
97
+ ```tsx
98
+ // src/app/%5Fdraft/[[...path]]/page.tsx
99
+ import { DraftPreviewIndicator } from "@decocms/nextjs";
100
+ import { bindDraft, type SearchParams } from "@decocms/nextjs/server";
101
+ import { cms } from "../../../cms";
102
+ import { openPage, pathnameFor } from "../../../open-page.server";
103
+ import { PageView } from "../../PageView";
104
+
105
+ export const dynamic = "force-dynamic";
106
+
107
+ type Props = { params: Promise<{ path?: string[] }>; searchParams: Promise<SearchParams> };
108
+
109
+ export default async function DraftPage({ params, searchParams }: Props) {
110
+ await bindDraft(cms, { searchParams: await searchParams });
111
+ const opened = await openPage(pathnameFor((await params).path));
112
+ return (
113
+ <>
114
+ <PageView {...opened} />
115
+ <DraftPreviewIndicator />
116
+ </>
117
+ );
118
+ }
119
+ ```
120
+
121
+ - The folder is `%5Fdraft`. A literal `_draft` folder is private in Next and
122
+ never routes.
123
+ - `bindDraft(cms, { searchParams })` binds, for this request: the page's own
124
+ `?__draft=` (`off` ends the preview), else `x-deco-version`, else the draft
125
+ cookie, each checked against the preview hosts. It also binds the visitor
126
+ and the assignments the proxy forwarded (on the current release, only when
127
+ it saves an `experiments` or `campaigns` block, and a test at 0% stays
128
+ off). It returns whether a version was bound.
129
+ - `contentClient(cms)` then builds `cms.client({ version, experiments, campaigns })`
130
+ from what was bound. Create one per request. `openPage` in
131
+ [rendering.md](./rendering.md) calls it.
132
+ - `DraftPreviewIndicator` renders the "Preview mode" badge only when a draft
133
+ is bound. Render it inside the page, after `bindDraft`, never in a layout:
134
+ a layout may render before the page binds. `exitHref` overrides where
135
+ "Exit preview" goes (default: the current URL with `?__draft=off`).
136
+ - A layout under the draft route that reads content
137
+ (`app/%5Fdraft/layout.tsx`) calls `bindDraft(cms)` and `contentClient(cms)`
138
+ without `searchParams`; it reads the forwarded headers.
139
+ - `activeDraftPointer()` from `@decocms/nextjs/server` returns the bound
140
+ version, or `null` on the current release.
141
+
142
+ ## Preview hosts
143
+
144
+ A draft link previews only on hosts the CMS allows: the `previewHosts`
145
+ Studio writes into the current release's metadata, plus
146
+ `createCMS({ preview: { hosts } })`. The host is the one the visitor asked
147
+ for (`x-forwarded-host`, else `host`).
148
+
149
+ | Situation | Who may preview |
150
+ |---|---|
151
+ | A site whose release lists `previewHosts` | Those hosts and `preview.hosts` |
152
+ | No release on the CDN yet, or one published before Studio wrote the list | Every host |
153
+ | No `site` and no `preview.hosts` | Every host |
154
+ | The release metadata can't be read (network, 5xx, bad file) | Only `preview.hosts`, until a read succeeds |
155
+
156
+ On a host that may not preview, the page renders the release. `?__draft=off`
157
+ ends a preview on any host.
158
+
159
+ `preview.draftHosts` replaces the hosts a draft pointer may point at
160
+ (default: `.decocms.com` and loopback).
161
+
162
+ ## Debugging a draft that shows the published page
163
+
164
+ 1. Is the request reaching the proxy? Check the `matcher`.
165
+ 2. Is the host allowed? Compare `x-forwarded-host` or `host` with the release's
166
+ `previewHosts` and `preview.hosts`. Add a local host such as `localhost`
167
+ to `preview.hosts` to preview in development.
168
+ 3. Does the page call `bindDraft` before reading content, on the draft route?
169
+ 4. Does the page show a notice (`data-deco-preview-unavailable`) instead of
170
+ the "Preview mode" badge? The link's draft can no longer be read (deleted,
171
+ or the drafts host failing). The page renders the release, with that
172
+ notice instead of an error page.
173
+ 5. Is a CDN or a `headers()` rule caching responses that carry `?__draft=` or
174
+ the `__deco_draft` cookie? Draft responses must not be stored.
175
+
176
+ Studio links, draft names and `deco push --draft`: load `deco-site-workflow`.
177
+ Variant previews with `__test` and `__campaign`: load `deco-variants`.
@@ -0,0 +1,171 @@
1
+ # Reading and rendering a page
2
+
3
+ Pages are Server Components. They get one content client, match the path,
4
+ follow redirects, resolve the page block and render its sections. The same
5
+ function serves the draft route, the assignments route and
6
+ `generateMetadata`.
7
+
8
+ ## The client
9
+
10
+ | Where | Client | Why |
11
+ |---|---|---|
12
+ | Assignments route (published CMS pages) | `await assignedClient(cms, segment)` | Built from the path segment, reads no request, so Next can cache the page. `null` for a segment the proxy never writes: answer `notFound()` |
13
+ | Draft route, and the app's own dynamic routes | `contentClient(cms)`, after `await bindDraft(...)` | Built from what `bindDraft` bound from the request and the proxy's headers |
14
+
15
+ Both come from `@decocms/nextjs/server`. Create a client per request. A client
16
+ runs each block function once per distinct input and memoizes the result, so
17
+ results are shared and read-only: copy before changing one.
18
+
19
+ ## The page function
20
+
21
+ ```ts
22
+ // src/open-page.server.ts
23
+ import "server-only";
24
+ import { cache, type ReactNode } from "react";
25
+ import { notFound, permanentRedirect, redirect } from "next/navigation";
26
+ import { matchRoute, type Page } from "@decocms/blocks";
27
+ import { assignedClient, contentClient } from "@decocms/nextjs/server";
28
+ import { cms } from "./cms";
29
+
30
+ export const openPage = cache(async (pathname: string, assignments?: string) => {
31
+ const c = assignments === undefined ? contentClient(cms) : await assignedClient(cms, assignments);
32
+ if (!c) notFound();
33
+
34
+ const [routes, routesError] = await c.routes();
35
+ if (routesError) throw routesError;
36
+ const match = matchRoute(pathname, { routes });
37
+ // Start downloading the page's blocks while the redirects block loads.
38
+ if (match.kind === "match") c.prefetch(match.entry.name);
39
+
40
+ const [redirects, redirectsError] = await c.redirects();
41
+ if (redirectsError) throw redirectsError;
42
+ const moved = matchRoute(pathname, { routes: [], redirects });
43
+ if (moved.kind === "redirect") {
44
+ if (moved.status === 301 || moved.status === 308) permanentRedirect(moved.location);
45
+ redirect(moved.location);
46
+ }
47
+ if (match.kind !== "match") notFound();
48
+
49
+ const [page, error] = await c.resolve<Page<ReactNode>>(match.entry.name);
50
+ if (error) throw error;
51
+ return page;
52
+ });
53
+
54
+ export const pathnameFor = (segments: string[] = []) =>
55
+ "/" + segments.map(encodeURIComponent).join("/");
56
+ ```
57
+
58
+ Why each step is there:
59
+
60
+ - **`cache()`** from React: `generateMetadata` and the page call `openPage`
61
+ with the same arguments in one request; they share one result.
62
+ - **`routes()`** reads `{ name, path }` of every page from the content index,
63
+ without page bodies. Do not route with `list("page")`: it fetches every
64
+ page and warns outside production.
65
+ - **`matchRoute(pathname, { routes, redirects })`** returns
66
+ `{ kind: "match", entry, params }`, `{ kind: "redirect", location, status }`
67
+ or `{ kind: "not-found" }`. Exact segments win over `:params`, params over a
68
+ trailing `*`. `match.params` holds the matched params.
69
+ - **`prefetch(name)`** starts fetching the page and everything it references
70
+ in one parallel wave, with the redirects block. It never throws.
71
+ - **Redirects** run before the not-found. Statuses are 301, 302, 307 or 308.
72
+ Next's `permanentRedirect` answers 308 and `redirect` 307.
73
+ - **`resolve(name)`** runs the page: `seo` and every block in `sections` are
74
+ resolved, so `sections` holds what each block function returned.
75
+
76
+ The example app also routes a custom block type (blog posts that carry a
77
+ `path`): it adds `(await c.list<Post>("post"))` to the routes it matches and
78
+ renders a matched post without resolving it.
79
+
80
+ ## Results and errors
81
+
82
+ `resolve`, `list`, `routes` and `redirects` return a tuple instead of
83
+ throwing: `[value, null]` or `[null, CMSError]`. (`revision()` is the
84
+ exception: it rejects when content can't load.) `CMSError` has `code`, `message`, `path` (where in the
85
+ tree, such as `["sections", 2, "product"]`) and, for function failures,
86
+ `cause`.
87
+
88
+ | Code | Meaning |
89
+ |---|---|
90
+ | `NOT_FOUND` | No saved block by that name |
91
+ | `UNKNOWN_BLOCK` | A `__resolveType` not in the block map |
92
+ | `CYCLE` | Blocks reference each other in a loop |
93
+ | `BLOCK_FAILED` | A block function threw |
94
+ | `LOADER_FAILED` | The content didn't load. On a site with `site`, its `cause` is a `ContentUnavailableError` until the first load succeeds |
95
+
96
+ Throwing the error renders Next's error boundary. Decide per page whether a
97
+ failed block should fail the page or be skipped.
98
+
99
+ ## Rendering sections
100
+
101
+ ```tsx
102
+ // src/app/PageView.tsx
103
+ import { StudioPage } from "@decocms/nextjs";
104
+ import { Fragment, type ReactNode } from "react";
105
+ import type { Page } from "@decocms/blocks";
106
+
107
+ export function PageView({ page }: { page: Page<ReactNode> }) {
108
+ return (
109
+ <main>
110
+ {page.sections.map((section, index) => (
111
+ <Fragment key={index}>{section}</Fragment>
112
+ ))}
113
+ <StudioPage pathTemplate={page.path} />
114
+ </main>
115
+ );
116
+ }
117
+ ```
118
+
119
+ - A section function returns a React element, so the page renders the list
120
+ as is. A site may return descriptors instead (`{ component, props }`) and
121
+ map them itself; `Page<Section>` takes either.
122
+ - `StudioPage` renders a `<meta>` that tells the Studio bridge which page
123
+ template is on screen. See [studio-bridge.md](./studio-bridge.md).
124
+ - Sections are Server Components by default. Put interactive parts in a
125
+ `"use client"` component the section renders (the example's `ProductHero`
126
+ renders a client `CartButton`). Props passed to a client component must be
127
+ serializable.
128
+ - A client component that calls `useSearchParams()` renders on the client up
129
+ to its nearest `<Suspense>` on a cached page. Wrap it.
130
+ - A block prop that is a `lazy` block arrives as a function
131
+ `() => Promise<T>` that resolves only when called. Lazy blocks and loading
132
+ states: load `deco-site-authoring`.
133
+
134
+ ## The two routes
135
+
136
+ ```tsx
137
+ // src/app/%5Fassignments/[assignments]/[[...path]]/page.tsx
138
+ import { openPage, pathnameFor } from "../../../../open-page.server";
139
+ import { PageView } from "../../../PageView";
140
+
141
+ export const revalidate = 600;
142
+ export async function generateStaticParams() {
143
+ return [];
144
+ }
145
+
146
+ type Props = { params: Promise<{ assignments: string; path?: string[] }> };
147
+
148
+ export default async function Page({ params }: Props) {
149
+ const { assignments, path } = await params;
150
+ return <PageView page={await openPage(pathnameFor(path), assignments)} />;
151
+ }
152
+ ```
153
+
154
+ The draft route is the same page with `bindDraft` first and
155
+ `DraftPreviewIndicator` after; see [proxy-and-drafts.md](./proxy-and-drafts.md).
156
+ Why the assignments route looks like this: [caching.md](./caching.md).
157
+
158
+ ## Routes the app owns
159
+
160
+ A route outside the CMS (a blog index, an account page) calls
161
+ `await bindDraft(cms)` (with `{ searchParams }` on a page) and then reads with
162
+ `contentClient(cms)`, which uses the version, visitor and assignments the
163
+ proxy forwarded. Leave it out of the proxy's `isCmsPage` so it is not
164
+ rewritten. `bindDraft` reads request headers, so Next renders the route per
165
+ request.
166
+
167
+ `contentClient` only reads what `bindDraft` bound. Called without it, it
168
+ reads the current release with no visitor: every test is off, and campaigns
169
+ are checked against the current time.
170
+
171
+ Writing sections, loaders and page blocks: load `deco-site-authoring`.
@@ -0,0 +1,190 @@
1
+ # Setup
2
+
3
+ How a Next.js App Router app becomes a v8 Deco site. The reference app is
4
+ `examples/nextjs-binding-smoke`; copy from it rather than from memory.
5
+
6
+ ## Packages
7
+
8
+ | Package | Why |
9
+ |---|---|
10
+ | `@decocms/blocks` | The CMS (`createCMS`, `matchRoute`, types), the `deco` CLI (its `bin`), `@decocms/blocks/image` |
11
+ | `@decocms/nextjs` | The Next helpers. Same version as `@decocms/blocks` |
12
+ | `next` 16, `react` 19 | Peers of `@decocms/nextjs` (Node 24 or later). Install `react-dom` 19 with them, as any Next app does |
13
+ | `server-only` | Optional. The example marks its server modules with it |
14
+ | `@opentelemetry/api` | Optional peer, for the request metric only |
15
+
16
+ `@decocms/nextjs` has six entry points. Each is a separate subpath so the
17
+ proxy never loads React:
18
+
19
+ | Import | Used from |
20
+ |---|---|
21
+ | `@decocms/nextjs/proxy` | `src/proxy.ts` |
22
+ | `@decocms/nextjs/server` | Server Components (it reads `next/headers`) |
23
+ | `@decocms/nextjs` | Layouts and pages: `StudioBridge`, `StudioPage`, `DraftPreviewIndicator`, names and Studio origins |
24
+ | `@decocms/nextjs/config` | `next.config` (CommonJS, so `require()` works too) |
25
+ | `@decocms/nextjs/image-loader` | The next/image `loaderFile` |
26
+ | `@decocms/nextjs/instrumentation` | `src/instrumentation.ts` |
27
+
28
+ ## Files
29
+
30
+ | File | What it holds |
31
+ |---|---|
32
+ | `.deco/index.tsx` | The block map: the default export, `satisfies Blocks` |
33
+ | `.deco/blocks/*.json` | Saved content, one block per file |
34
+ | `.deco/schema.gen.json` | Written by `deco schema`. Commit it. Do not edit |
35
+ | `.deco/blocks.gen.ts` | Written by `deco content`, only for content without `site`. Do not edit |
36
+ | `src/cms.config.ts` | Every `createCMS` option except `blocks` |
37
+ | `src/cms.ts` | `cms = createCMS({ blocks, ...cmsConfig })` for pages |
38
+ | `src/cms.proxy.ts` | `proxyCms = createCMS({ blocks: {}, ...cmsConfig })` for the proxy |
39
+ | `src/proxy.ts` | See [proxy-and-drafts.md](./proxy-and-drafts.md) |
40
+ | `src/app/%5Fassignments/[assignments]/[[...path]]/page.tsx` | Every published CMS page. See [caching.md](./caching.md) |
41
+ | `src/app/%5Fdraft/[[...path]]/page.tsx` | Every preview. See [proxy-and-drafts.md](./proxy-and-drafts.md) |
42
+ | `src/app/layout.tsx` | The root layout, with `<StudioBridge site="…" />` |
43
+ | `src/image-loader.ts` | The next/image loader |
44
+ | `src/instrumentation.ts` | The request metric |
45
+
46
+ ## The block map
47
+
48
+ A saved block's `__resolveType` names a key of the block map. The function
49
+ gets the block's resolved props and returns what the page renders: a React
50
+ element for a section, plain data for anything else.
51
+
52
+ ```tsx
53
+ // .deco/index.tsx
54
+ import type { Blocks, Seo } from "@decocms/blocks";
55
+ import ProductHero from "../src/ProductHero";
56
+ import PromoBanner from "../src/PromoBanner";
57
+ import type { ProductHeroProps, PromoBannerProps } from "../src/model";
58
+
59
+ export default {
60
+ seo: (input: Seo) => input,
61
+ "promo-banner": (input: PromoBannerProps) => <PromoBanner {...input} />,
62
+ "product-hero": (input: ProductHeroProps) => <ProductHero {...input} />,
63
+ } satisfies Blocks;
64
+ ```
65
+
66
+ - The key is the block's identity in content. Renaming it breaks every saved
67
+ block that uses it.
68
+ - The CMS adds built-in blocks to every map: `lazy`, `multivariate`, `always`,
69
+ `never`, `experiment`, `campaign`, `page`, `redirect`, `redirects`,
70
+ `cms-settings`, `split-traffic`, `calendar`. Do not reuse those names.
71
+ - The Props type of each function is the Studio form. `deco schema` reads it
72
+ from `.deco/index.tsx` (or `.deco/index.ts`). Form details: load
73
+ `deco-cms-schema`.
74
+
75
+ **Editability check.** A section that renders literal text in JSX looks
76
+ right and cannot be edited in Studio. For every section, check that what an
77
+ editor should change comes from its props, and that the block map points at
78
+ the real component with its real Props type, not a static copy.
79
+
80
+ ## The two CMS handles
81
+
82
+ ```ts
83
+ // src/cms.config.ts
84
+ export const cmsConfig = { site: "my-store" };
85
+
86
+ // src/cms.ts
87
+ import { createCMS } from "@decocms/blocks";
88
+ import blocks from "../.deco";
89
+ import { cmsConfig } from "./cms.config";
90
+ export const cms = createCMS({ blocks, ...cmsConfig });
91
+
92
+ // src/cms.proxy.ts
93
+ import { createCMS } from "@decocms/blocks";
94
+ import { cmsConfig } from "./cms.config";
95
+ export const proxyCms = createCMS({ blocks: {}, ...cmsConfig });
96
+ ```
97
+
98
+ `createCMS` keeps one instance per process for each `site` (or, without
99
+ `site`, each content module), so both handles share content and release
100
+ checks. Each handle keeps its own block map. The proxy's handle has no block map, so no
101
+ section code lands in the proxy bundle.
102
+
103
+ Where content comes from:
104
+
105
+ - **With `site`** (Studio's site slug): the site's latest release on the
106
+ delivery CDN, loaded at runtime and checked again every `interval` (default
107
+ and minimum 60 000 ms). Passing `content` too throws.
108
+ - **Without `site`**: pass `content`, the module `deco content` writes from
109
+ `.deco/blocks` (`import content from "../.deco/blocks.gen"`). Used by tests
110
+ and the examples.
111
+
112
+ Other options: `preview: { hosts, draftHosts }` (see
113
+ [proxy-and-drafts.md](./proxy-and-drafts.md)), `telemetry` (`false`, or
114
+ `{ endpoint, headers }` for an OTLP/HTTP collector), and `token`, a
115
+ server-only secret that sends telemetry to the hosted collector and needs
116
+ `site`. Never import `token` into client code.
117
+
118
+ ## next.config
119
+
120
+ ```ts
121
+ // next.config.ts
122
+ import { withDeco } from "@decocms/nextjs/config";
123
+
124
+ export default withDeco({
125
+ images: { loader: "custom", loaderFile: "./src/image-loader.ts" },
126
+ });
127
+ ```
128
+
129
+ `withDeco(nextConfig, options?)` adds two things and nothing about hosting:
130
+
131
+ - `draftHeaders` (default on): two header rules placed before the site's own
132
+ `headers()`. A request with `?__draft=` or the `__deco_draft` cookie gets
133
+ `Cache-Control: max-age=0, no-cache, must-revalidate`, `Vary: Cookie` and
134
+ `X-Robots-Tag: noindex, nofollow`. Next sets `Cache-Control` and `Vary`
135
+ itself on dynamic pages, so only `X-Robots-Tag` is sure to arrive from these
136
+ rules; the proxy's `applyDraft` sets all three.
137
+ - `studioOrigins` (default on): Studio's hosts in `allowedDevOrigins`, so
138
+ `next dev` serves Studio its dev assets.
139
+
140
+ Turn either off with `withDeco(config, { draftHeaders: false, studioOrigins: false })`.
141
+
142
+ ## Scripts
143
+
144
+ Run the CLI before Next (the example does the same through a small script):
145
+
146
+ ```json
147
+ "predev": "deco schema && deco content",
148
+ "prebuild": "deco schema && deco content"
149
+ ```
150
+
151
+ Drop `deco content` when the site uses `site`. Use `deco schema --check` in
152
+ CI to fail on a stale schema, and `deco schema push` on production deploys so
153
+ Studio draws the forms. Order and secrets: load `deco-site-workflow`.
154
+
155
+ If the host installs only `dependencies` in production builds, keep
156
+ `@decocms/blocks` there: the `deco` bin comes from it and `prebuild` needs it.
157
+
158
+ ## Images
159
+
160
+ ```ts
161
+ // src/image-loader.ts
162
+ import { createImageUrl, decoCdn } from "@decocms/blocks/image";
163
+ import { createDecoImageLoader, nextImageOptimizer } from "@decocms/nextjs/image-loader";
164
+
165
+ const imageUrl = createImageUrl({ providers: [decoCdn({ fit: "contain" })] });
166
+ export default createDecoImageLoader(imageUrl, { fallback: nextImageOptimizer });
167
+ ```
168
+
169
+ The first provider that takes a source builds its URL. A commerce site lists
170
+ its platform's helpers (`@decocms/apps-vtex/image`,
171
+ `@decocms/apps-shopify/image`) before `decoCdn`. Any other source goes to
172
+ `fallback`: `nextImageOptimizer` sends it through `/_next/image`; without a
173
+ fallback the `src` comes back unchanged. next/image's `quality` may also be a
174
+ named tier (`low`, `medium`, `high`, `original`); `nextImageOptimizer` sends
175
+ them as 60, 70, 80 and 100.
176
+ Providers, quality and LCP: load `deco-images-media`.
177
+
178
+ ## Request metric
179
+
180
+ ```ts
181
+ // src/instrumentation.ts
182
+ export { register } from "@decocms/nextjs/instrumentation";
183
+ ```
184
+
185
+ `register` turns Next's own request span into `http.server.request.duration`
186
+ in the CMS's telemetry, labelled by `http.route`, `http.request.method`,
187
+ `status_class` and `cache` (`DRAFT` or `BYPASS`). It records nothing without
188
+ a telemetry destination, and does nothing on the Edge runtime. A site with its
189
+ own OpenTelemetry setup adds `serverRequestSpanProcessor()` to its span
190
+ processors instead, because only one tracer provider can be registered.
@@ -0,0 +1,130 @@
1
+ # The Studio bridge
2
+
3
+ Studio's site editor shows the site in an iframe. The bridge is what lets it
4
+ scroll to a section, reload the page after a save and load its own editor
5
+ code into the page. On Next it is one component in the root layout.
6
+
7
+ ## Wiring
8
+
9
+ ```tsx
10
+ // src/app/layout.tsx
11
+ import { StudioBridge } from "@decocms/nextjs";
12
+ import type { ReactNode } from "react";
13
+
14
+ export default function RootLayout({ children }: { children: ReactNode }) {
15
+ return (
16
+ <html lang="en">
17
+ <body>
18
+ {children}
19
+ <StudioBridge site="my-store" />
20
+ </body>
21
+ </html>
22
+ );
23
+ }
24
+ ```
25
+
26
+ `StudioBridge` renders two inline scripts and uses no hooks, so a Server
27
+ Component renders it as is. It reads no request, so it does not stop the root
28
+ layout from being cached.
29
+
30
+ | Prop | Default | What it does |
31
+ |---|---|---|
32
+ | `site` | required | The site's name in Studio |
33
+ | `editShortcut` | `true` | "." (or Ctrl+Shift+E) on a page outside Studio opens it in Studio's editor; Ctrl or Cmd+"." in a new tab |
34
+ | `studioOrigins` | `DECO_STUDIO_ORIGIN`, else Studio's production and staging origins | The exact origins the Studio channel trusts |
35
+ | `nonce` | none | The CSP nonce for the inline scripts |
36
+ | `page` | none | The page on screen; a `StudioPage` on the page wins |
37
+
38
+ ## What it does
39
+
40
+ - **The bridge script** answers Studio's scroll-to-section and rerender
41
+ messages, only from a parent window at one of Studio's origins. Outside a
42
+ frame it answers no message and only listens for the "." shortcut.
43
+ - **The Studio channel** runs on every page, production included (about
44
+ 0.7 kB gzipped). Framed by a trusted origin, it posts `{ type: "deco:ready" }`
45
+ and imports a module only when the answer `{ type: "deco:load", url }`
46
+ comes from exactly one trusted origin and names a URL on that origin. Not
47
+ framed, or framed by anyone else, it does nothing. It never evaluates a
48
+ script Studio sends. Message types are in `@decocms/blocks/protocol`.
49
+
50
+ ## Which page "." opens
51
+
52
+ The root layout does not re-render on navigation, so it cannot know which
53
+ page is on screen. Each CMS page renders a marker next to its sections:
54
+
55
+ ```tsx
56
+ import { StudioPage } from "@decocms/nextjs";
57
+
58
+ <StudioPage pathTemplate={page.path} />
59
+ ```
60
+
61
+ `pathTemplate` is the page block's `path` as `matchRoute` matched it
62
+ (`/:slug/p`, not `/summer-shirt/p`). An optional `id` names the page block.
63
+ Without the marker, Studio picks the page from the URL.
64
+
65
+ ## Content Security Policy
66
+
67
+ A site with a CSP must allow Studio's origins in `script-src` (the channel
68
+ imports Studio's modules) and in `frame-ancestors` (Studio frames the site).
69
+ `withStudioCsp(directives, options?)` from `@decocms/nextjs` adds them:
70
+
71
+ ```ts
72
+ // next.config.ts
73
+ import { withStudioCsp } from "@decocms/nextjs";
74
+ import { withDeco } from "@decocms/nextjs/config";
75
+
76
+ const csp = withStudioCsp("script-src 'self' 'unsafe-inline'; object-src 'none'").join("; ");
77
+
78
+ export default withDeco({
79
+ headers: async () => [
80
+ { source: "/:path*", headers: [{ key: "Content-Security-Policy", value: csp }] },
81
+ ],
82
+ });
83
+ ```
84
+
85
+ - It adds the origins to `script-src` and `script-src-elem`. A policy that
86
+ restricts scripts only through `default-src` gets a `script-src` with
87
+ `default-src`'s sources plus Studio's.
88
+ - It adds `frame-ancestors` with Studio's only when the policy has none. A
89
+ site's own `frame-ancestors` is kept as is: add Studio's yourself.
90
+ - Options: `studioOrigins`, `frameAncestors` (other editors allowed to frame
91
+ the site), `dev: true` (loopback may frame the site),
92
+ `addFrameAncestors: false`.
93
+ - Pass the same `nonce` to `StudioBridge` when the policy uses nonces.
94
+
95
+ A site that builds its headers in the proxy can set the same value there.
96
+
97
+ ## A local or staging Studio
98
+
99
+ Set `DECO_STUDIO_ORIGIN` to a comma-separated list of exact origins (for
100
+ example `http://localhost:3000`). It replaces the default list for the
101
+ channel and for `withStudioCsp`. Each entry must be an exact http(s) origin;
102
+ anything else (a path, a wildcard) is dropped. An empty `studioOrigins={[]}`
103
+ turns the channel off.
104
+
105
+ `withDeco` adds Studio's hosts to `allowedDevOrigins`, so `next dev` serves
106
+ its dev assets when Studio frames a local site.
107
+
108
+ ## Names for the site's own code
109
+
110
+ `@decocms/nextjs` exports what the proxy, the pages and `withDeco` use, for a
111
+ route that sets its own headers: `DRAFT_PARAM` (`__draft`), `DRAFT_COOKIE`
112
+ (`__deco_draft`), `VERSION_HEADER` (`x-deco-version`), `VISITOR_HEADER`
113
+ (`x-deco-visitor`), `ASSIGNMENTS_HEADER` (`x-deco-assignments`),
114
+ `draftResponseHeaders(...)`, `STUDIO_ORIGIN`, `STUDIO_ORIGINS`,
115
+ `STUDIO_FRAME_ANCESTORS`, `DEFAULT_STUDIO_ORIGINS`, `isStudioOrigin(origin)`,
116
+ `studioOrigins(option?)` and `withStudioCsp(...)`.
117
+
118
+ ## When Studio can't drive the page
119
+
120
+ 1. Is `StudioBridge` in the root layout's `<body>`, on every route?
121
+ 2. Does the CSP allow Studio in `script-src` and `frame-ancestors`? Look for
122
+ CSP errors in the framed page's console.
123
+ 3. Does an `X-Frame-Options` header block framing? Remove it in favor of
124
+ `frame-ancestors`.
125
+ 4. Is Studio on a non-default origin? Set `DECO_STUDIO_ORIGIN` on the server.
126
+ 5. Does "." open the wrong page? Render `StudioPage` with the matched
127
+ `path` template.
128
+
129
+ Connecting a local site to Studio and the `deco` CLI side: load
130
+ `deco-site-workflow`.