@decocms/blocks 8.10.0 → 8.12.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (210) hide show
  1. package/dist/index.d.ts +1 -1
  2. package/dist/index.d.ts.map +1 -1
  3. package/dist/index.js.map +1 -1
  4. package/dist/protocol/conformance/blockMetaVectors.json +80 -0
  5. package/dist/protocol/index.d.ts +5 -2
  6. package/dist/protocol/index.d.ts.map +1 -1
  7. package/dist/protocol/index.js +5 -2
  8. package/dist/protocol/index.js.map +1 -1
  9. package/dist/v8/blockMeta.d.ts +33 -4
  10. package/dist/v8/blockMeta.d.ts.map +1 -1
  11. package/dist/v8/blockMeta.js +70 -13
  12. package/dist/v8/blockMeta.js.map +1 -1
  13. package/dist/v8/cli/index.d.ts +1 -0
  14. package/dist/v8/cli/index.d.ts.map +1 -1
  15. package/dist/v8/cli/index.js +1 -0
  16. package/dist/v8/cli/index.js.map +1 -1
  17. package/dist/v8/cli/run.d.ts +2 -0
  18. package/dist/v8/cli/run.d.ts.map +1 -1
  19. package/dist/v8/cli/run.js +30 -1
  20. package/dist/v8/cli/run.js.map +1 -1
  21. package/dist/v8/cli/skills.d.ts +25 -0
  22. package/dist/v8/cli/skills.d.ts.map +1 -0
  23. package/dist/v8/cli/skills.js +70 -0
  24. package/dist/v8/cli/skills.js.map +1 -0
  25. package/dist/v8/client.d.ts +6 -4
  26. package/dist/v8/client.d.ts.map +1 -1
  27. package/dist/v8/client.js +26 -70
  28. package/dist/v8/client.js.map +1 -1
  29. package/dist/v8/cms.d.ts.map +1 -1
  30. package/dist/v8/cms.js +1 -2
  31. package/dist/v8/cms.js.map +1 -1
  32. package/dist/v8/contentIndex.d.ts +18 -7
  33. package/dist/v8/contentIndex.d.ts.map +1 -1
  34. package/dist/v8/contentIndex.js +46 -17
  35. package/dist/v8/contentIndex.js.map +1 -1
  36. package/dist/v8/draftChanges.d.ts.map +1 -1
  37. package/dist/v8/draftChanges.js +4 -1
  38. package/dist/v8/draftChanges.js.map +1 -1
  39. package/dist/v8/index.d.ts +1 -1
  40. package/dist/v8/index.d.ts.map +1 -1
  41. package/dist/v8/remoteLoader.d.ts +4 -2
  42. package/dist/v8/remoteLoader.d.ts.map +1 -1
  43. package/dist/v8/remoteLoader.js +13 -3
  44. package/dist/v8/remoteLoader.js.map +1 -1
  45. package/dist/v8/types.d.ts +47 -7
  46. package/dist/v8/types.d.ts.map +1 -1
  47. package/package.json +3 -2
  48. package/skills/deco-apps/SKILL.md +82 -0
  49. package/skills/deco-apps/references/algolia.md +51 -0
  50. package/skills/deco-apps/references/commerce-types.md +132 -0
  51. package/skills/deco-apps/references/instrumented-fetch.md +144 -0
  52. package/skills/deco-apps/references/magento.md +55 -0
  53. package/skills/deco-apps/references/messaging.md +76 -0
  54. package/skills/deco-apps/references/shopify.md +69 -0
  55. package/skills/deco-apps/references/vendored-loaders.md +135 -0
  56. package/skills/deco-apps/references/vtex-cookies-auth.md +146 -0
  57. package/skills/deco-apps/references/vtex.md +150 -0
  58. package/skills/deco-apps/references/wake.md +75 -0
  59. package/skills/deco-cms-schema/SKILL.md +80 -0
  60. package/skills/deco-cms-schema/references/annotations.md +147 -0
  61. package/skills/deco-cms-schema/references/content-hygiene.md +91 -0
  62. package/skills/deco-cms-schema/references/formats-and-widgets.md +112 -0
  63. package/skills/deco-cms-schema/references/shapes-that-break-the-form.md +165 -0
  64. package/skills/deco-cms-schema/references/types-to-fields.md +112 -0
  65. package/skills/deco-go-live/SKILL.md +127 -0
  66. package/skills/deco-go-live/references/content-releases.md +90 -0
  67. package/skills/deco-go-live/references/process.md +106 -0
  68. package/skills/deco-go-live/references/proxy-headers-checkout.md +139 -0
  69. package/skills/deco-go-live/references/qa-checklist-template.md +150 -0
  70. package/skills/deco-go-live/references/qa-inventory.md +120 -0
  71. package/skills/deco-go-live/references/react-spa.md +183 -0
  72. package/skills/deco-go-live/references/seo-analytics.md +114 -0
  73. package/skills/deco-go-live/references/traffic-ramp.md +87 -0
  74. package/skills/deco-go-live/references/worker-runtime.md +93 -0
  75. package/skills/deco-go-live/scripts/preflight.sh +221 -0
  76. package/skills/deco-images-media/SKILL.md +64 -0
  77. package/skills/deco-images-media/references/asset-upload.md +191 -0
  78. package/skills/deco-images-media/references/components-per-binding.md +167 -0
  79. package/skills/deco-images-media/references/providers-and-cdn.md +145 -0
  80. package/skills/deco-images-media/references/quality-and-lcp.md +93 -0
  81. package/skills/deco-images-media/references/troubleshooting.md +147 -0
  82. package/skills/deco-images-media/references/video.md +122 -0
  83. package/skills/deco-make-editable/SKILL.md +94 -0
  84. package/skills/deco-make-editable/references/a11y-and-e2e.md +104 -0
  85. package/skills/deco-make-editable/references/content-shapes.md +203 -0
  86. package/skills/deco-make-editable/references/from-figma.md +110 -0
  87. package/skills/deco-make-editable/references/i18n-fields.md +112 -0
  88. package/skills/deco-make-editable/references/inventory.md +79 -0
  89. package/skills/deco-make-editable/references/pixel-parity.md +175 -0
  90. package/skills/deco-make-editable/references/seeding-content.md +119 -0
  91. package/skills/deco-nextjs-site/SKILL.md +74 -0
  92. package/skills/deco-nextjs-site/references/caching.md +116 -0
  93. package/skills/deco-nextjs-site/references/metadata-seo.md +100 -0
  94. package/skills/deco-nextjs-site/references/proxy-and-drafts.md +177 -0
  95. package/skills/deco-nextjs-site/references/rendering.md +172 -0
  96. package/skills/deco-nextjs-site/references/setup.md +190 -0
  97. package/skills/deco-nextjs-site/references/studio-bridge.md +130 -0
  98. package/skills/deco-site-authoring/SKILL.md +75 -0
  99. package/skills/deco-site-authoring/references/lazy-blocks.md +155 -0
  100. package/skills/deco-site-authoring/references/loaders.md +192 -0
  101. package/skills/deco-site-authoring/references/pages.md +158 -0
  102. package/skills/deco-site-authoring/references/review-before-publish.md +95 -0
  103. package/skills/deco-site-authoring/references/sections.md +158 -0
  104. package/skills/deco-site-authoring/references/seo.md +116 -0
  105. package/skills/deco-site-workflow/SKILL.md +101 -0
  106. package/skills/deco-site-workflow/references/check.md +116 -0
  107. package/skills/deco-site-workflow/references/cli-reference.md +106 -0
  108. package/skills/deco-site-workflow/references/content-layout.md +93 -0
  109. package/skills/deco-site-workflow/references/content-sync.md +146 -0
  110. package/skills/deco-site-workflow/references/delivery.md +51 -0
  111. package/skills/deco-site-workflow/references/deploy.md +87 -0
  112. package/skills/deco-site-workflow/references/schema.md +173 -0
  113. package/skills/deco-site-workflow/references/serve-and-studio.md +138 -0
  114. package/skills/deco-storefront-caching/SKILL.md +67 -0
  115. package/skills/deco-storefront-caching/references/cache-keys.md +129 -0
  116. package/skills/deco-storefront-caching/references/case-study.md +82 -0
  117. package/skills/deco-storefront-caching/references/egress-traps.md +153 -0
  118. package/skills/deco-storefront-caching/references/nextjs.md +60 -0
  119. package/skills/deco-storefront-caching/references/perf-guardrails-e2e.md +123 -0
  120. package/skills/deco-storefront-caching/references/verification.md +136 -0
  121. package/skills/deco-storefront-caching/references/worker-page-cache.md +160 -0
  122. package/skills/deco-storefront-caching/scripts/html-anatomy.mjs +97 -0
  123. package/skills/deco-storefront-performance/SKILL.md +81 -0
  124. package/skills/deco-storefront-performance/references/cls-third-party.md +90 -0
  125. package/skills/deco-storefront-performance/references/hydration.md +116 -0
  126. package/skills/deco-storefront-performance/references/loaders-n-plus-1.md +107 -0
  127. package/skills/deco-storefront-performance/references/navigation-ux.md +130 -0
  128. package/skills/deco-storefront-performance/references/payload-trim.md +163 -0
  129. package/skills/deco-storefront-performance/references/render-location.md +152 -0
  130. package/skills/deco-storefront-performance/references/request-dedupe.md +147 -0
  131. package/skills/deco-storefront-performance/references/trace-reading.md +79 -0
  132. package/skills/deco-storefront-performance/references/worker-memory.md +176 -0
  133. package/skills/deco-tanstack-site/SKILL.md +68 -0
  134. package/skills/deco-tanstack-site/references/document-and-security.md +155 -0
  135. package/skills/deco-tanstack-site/references/router-and-navigation.md +137 -0
  136. package/skills/deco-tanstack-site/references/routes-and-pages.md +183 -0
  137. package/skills/deco-tanstack-site/references/server-functions.md +123 -0
  138. package/skills/deco-tanstack-site/references/setup.md +153 -0
  139. package/skills/deco-tanstack-site/references/worker-entry.md +152 -0
  140. package/skills/deco-v7-to-v8-migration/SKILL.md +123 -0
  141. package/skills/deco-v7-to-v8-migration/references/caching-and-privacy.md +10 -0
  142. package/skills/deco-v7-to-v8-migration/references/content.md +25 -0
  143. package/skills/deco-v7-to-v8-migration/references/editor-forms.md +27 -0
  144. package/skills/deco-v7-to-v8-migration/references/faststore.md +40 -0
  145. package/skills/deco-v7-to-v8-migration/references/framework-code.md +53 -0
  146. package/skills/deco-v7-to-v8-migration/references/hosted-releases.md +16 -0
  147. package/skills/deco-v7-to-v8-migration/references/import-map.md +81 -0
  148. package/skills/deco-v7-to-v8-migration/references/legacy-names.md +33 -0
  149. package/skills/deco-v7-to-v8-migration/references/manual-steps.md +10 -0
  150. package/skills/deco-v7-to-v8-migration/references/native-apps.md +43 -0
  151. package/skills/deco-v7-to-v8-migration/references/nextjs.md +19 -0
  152. package/skills/deco-v7-to-v8-migration/references/parity.md +66 -0
  153. package/skills/deco-v7-to-v8-migration/references/rendering.md +13 -0
  154. package/skills/deco-v7-to-v8-migration/references/running-the-script.md +29 -0
  155. package/skills/deco-v7-to-v8-migration/references/script-steps.md +13 -0
  156. package/skills/deco-v7-to-v8-migration/references/server-functions.md +15 -0
  157. package/skills/deco-v7-to-v8-migration/references/sibling-port.md +11 -0
  158. package/skills/deco-v7-to-v8-migration/references/site-code.md +15 -0
  159. package/skills/deco-v7-to-v8-migration/references/telemetry.md +10 -0
  160. package/skills/deco-v7-to-v8-migration/references/verify.md +23 -0
  161. package/skills/deco-v7-to-v8-migration/scripts/apps.ts +297 -0
  162. package/skills/deco-v7-to-v8-migration/scripts/asyncRendering.ts +73 -0
  163. package/skills/deco-v7-to-v8-migration/scripts/blockMap.ts +584 -0
  164. package/skills/deco-v7-to-v8-migration/scripts/checkContentReads.ts +32 -0
  165. package/skills/deco-v7-to-v8-migration/scripts/ciSchemaCheck.ts +145 -0
  166. package/skills/deco-v7-to-v8-migration/scripts/compat.ts +357 -0
  167. package/skills/deco-v7-to-v8-migration/scripts/content.ts +121 -0
  168. package/skills/deco-v7-to-v8-migration/scripts/contentReads.ts +157 -0
  169. package/skills/deco-v7-to-v8-migration/scripts/experiments.ts +81 -0
  170. package/skills/deco-v7-to-v8-migration/scripts/framework.ts +61 -0
  171. package/skills/deco-v7-to-v8-migration/scripts/imageCopy.ts +276 -0
  172. package/skills/deco-v7-to-v8-migration/scripts/imageModule.ts +285 -0
  173. package/skills/deco-v7-to-v8-migration/scripts/imports.ts +942 -0
  174. package/skills/deco-v7-to-v8-migration/scripts/invoke.ts +624 -0
  175. package/skills/deco-v7-to-v8-migration/scripts/legacyNames.ts +45 -0
  176. package/skills/deco-v7-to-v8-migration/scripts/main.ts +59 -0
  177. package/skills/deco-v7-to-v8-migration/scripts/matchers.ts +41 -0
  178. package/skills/deco-v7-to-v8-migration/scripts/migrate.ts +180 -0
  179. package/skills/deco-v7-to-v8-migration/scripts/redirects.ts +455 -0
  180. package/skills/deco-v7-to-v8-migration/scripts/report.ts +50 -0
  181. package/skills/deco-v7-to-v8-migration/scripts/scaffold.ts +1119 -0
  182. package/skills/deco-v7-to-v8-migration/scripts/secrets.ts +35 -0
  183. package/skills/deco-v7-to-v8-migration/scripts/sectionLoaders.ts +216 -0
  184. package/skills/deco-v7-to-v8-migration/scripts/siteSettings.ts +261 -0
  185. package/skills/deco-v7-to-v8-migration/scripts/stubs.ts +388 -0
  186. package/skills/deco-v7-to-v8-migration/scripts/tsconfig.json +7 -0
  187. package/skills/deco-v7-to-v8-migration/scripts/vendor.ts +249 -0
  188. package/skills/deco-v7-to-v8-migration/scripts/vtexInvoke.ts +240 -0
  189. package/skills/deco-v7-to-v8-migration/scripts/walk.ts +30 -0
  190. package/skills/deco-variants/SKILL.md +57 -0
  191. package/skills/deco-variants/references/caching-variants.md +63 -0
  192. package/skills/deco-variants/references/custom-matchers.md +83 -0
  193. package/skills/deco-variants/references/draft-preview.md +59 -0
  194. package/skills/deco-variants/references/experiments-and-campaigns.md +104 -0
  195. package/skills/deco-variants/references/multivariate.md +85 -0
  196. package/skills/deco-variants/references/v7-matchers.md +71 -0
  197. package/src/index.ts +1 -1
  198. package/src/protocol/conformance/blockMetaVectors.json +80 -0
  199. package/src/protocol/index.ts +8 -1
  200. package/src/v8/blockMeta.ts +75 -11
  201. package/src/v8/cli/index.ts +1 -0
  202. package/src/v8/cli/run.ts +35 -1
  203. package/src/v8/cli/skills.ts +91 -0
  204. package/src/v8/client.ts +32 -77
  205. package/src/v8/cms.ts +1 -2
  206. package/src/v8/contentIndex.ts +49 -19
  207. package/src/v8/draftChanges.ts +5 -1
  208. package/src/v8/index.ts +1 -1
  209. package/src/v8/remoteLoader.ts +13 -3
  210. package/src/v8/types.ts +48 -7
@@ -0,0 +1,146 @@
1
+ # Edit content from the terminal
2
+
3
+ The remote commands move content between `.deco/blocks` and Studio's hosted CMS for the site named by
4
+ `DECO_SITE`. Reads of published content and drafts go to the public CDN. Writes go through the Studio
5
+ API with your token. Nothing retries on its own, and nothing goes live except `deco publish`.
6
+
7
+ Token and site setup: [schema.md](./schema.md), Steps 2 and 3.
8
+
9
+ ## The edit loop
10
+
11
+ ```bash
12
+ deco pull # or: deco pull --draft=summer-sale
13
+ # edit .deco/blocks/*.json (or add files)
14
+ deco diff # what you changed since the pull
15
+ deco push --draft=summer-sale # one save; prints "preview: <link>"
16
+ deco check --draft=summer-sale # the whole draft against the code
17
+ # open the preview link and look at the pages
18
+ deco publish --draft=summer-sale --message="Summer sale banners"
19
+ ```
20
+
21
+ Adding a page, as an example: pull, copy an existing page's file (it already references the shared
22
+ `Header` and `Footer` blocks), give the copy a new file name, `name` and `path`, change its
23
+ `sections`, then diff, push, check and preview. Use a block type that is in the deployed code, or
24
+ `deco check` fails and Studio has no form for it. What a page's props mean is `deco-site-authoring`.
25
+
26
+ ## pull
27
+
28
+ `deco pull [--draft=<name>] [--force]`
29
+
30
+ - Without `--draft`: writes production (the live release) into `.deco/blocks`. With it: production
31
+ with that draft's changes on top.
32
+ - Makes the folder hold exactly that content: it writes each block and **removes every other block
33
+ file**.
34
+ - Writes `.deco/pull.json`: per block, its hash and its version in the draft.
35
+ - Refuses when the folder has changes not pushed:
36
+ `.deco/blocks has 3 changes not pushed (A, B, C); push them, or pull with --force to overwrite them`
37
+ (exit 1). `--force` overwrites them.
38
+ - Prints `pulled 42 blocks from production (revision <id>)` or `… from draft <name> (over revision <id>)`.
39
+
40
+ ## diff
41
+
42
+ `deco diff [--draft=<name>]`
43
+
44
+ - Without `--draft`: what `.deco/blocks` changes against `.deco/pull.json`, shown against what was
45
+ pulled (or, after a draft pull, against that draft **as it is now**, which the label says).
46
+ `nothing pulled yet: run deco pull` (exit 1) when there is no `pull.json`.
47
+ - With `--draft`: the folder against that draft as it is now, ignoring `pull.json`.
48
+ - One line per block: `M` changed, `A` new, `D` deleted, each with a field diff. Then
49
+ `3 changes against …` or `no changes against …`.
50
+
51
+ ## push
52
+
53
+ `deco push --draft=<name> [--ours | --theirs] [--prune]`
54
+
55
+ - Creates the draft if it doesn't exist (`created draft <name>`).
56
+ - Sends only blocks changed since the pull. A block that already equals what the draft shows is
57
+ skipped. With no `pull.json`, every file is new.
58
+ - **Deletes are sent only with `--prune`.** Without it the push names what it skipped:
59
+ `not sent: 1 deleted block (Old); push with --prune to send deletes`.
60
+ - Each block carries a precondition: its version in the draft when you pulled. If someone changed
61
+ it since, nothing of the save is written and the push **exits 2**:
62
+
63
+ ```text
64
+ conflict: Home: changed by <user> at <time>; theirs (-) against yours (+)
65
+ 1 block changed in draft summer-sale while you pushed; nothing of this save was written. Pull again, or push with --ours (keep yours) or --theirs (take theirs)
66
+ ```
67
+
68
+ - `--ours`: send yours again over theirs.
69
+ - `--theirs`: write their version into `.deco/blocks` for the conflicting blocks and send the rest.
70
+ - `--ours` and `--theirs` together is a usage error (64).
71
+ - Pushing to a draft other than the one you pulled drops the preconditions: a name that draft already
72
+ changed comes back as a conflict.
73
+ - One push is one save. It must fit **500 blocks and 8 MiB**, and each block **1 MiB**. Otherwise
74
+ nothing is sent: `the 812 changed blocks don't fit one save (…); push fewer at a time`, or
75
+ `block "<name>" is larger than a save can carry (1048576 bytes a block)`. To push a large folder,
76
+ move part of the files out, push, move them back, push again: blocks already pushed are recorded in
77
+ `pull.json` and skipped.
78
+ - Busy Studio (exit 5): `Studio is busy (…); 120 blocks saved, the rest not, run deco push again`.
79
+ Run it again; what landed is recorded.
80
+ - A file that isn't a valid block stops the push before anything is sent (exit 1), for example
81
+ `.deco/blocks/Home.json: invalid JSON: …`.
82
+ - Prints `pushed 3 blocks to draft summer-sale` and `preview: <link>`.
83
+
84
+ `deco push` does not run `deco check`. Run `deco check --draft=<name>` after it.
85
+
86
+ ## drafts
87
+
88
+ | Command | Does |
89
+ |---|---|
90
+ | `deco drafts list` | Each draft: name, who created it, via what, when (`no drafts` when none) |
91
+ | `deco drafts new <name>` | Creates it (`draft <name> already exists` if it does) and prints its preview link, when Studio has one |
92
+ | `deco drafts discard <name>` | Deletes the draft and its changes |
93
+ | `deco drafts url <name>` | Prints the preview URL; or the pointer, to open as `?__draft=<pointer>` on the site; or `draft <name> has no object yet: push to it first` |
94
+
95
+ Draft names: letters, digits and `/ . _ -` after the first character, at most 255. Anything else is
96
+ exit 64: `"<value>" isn't a draft name: …`.
97
+
98
+ ## publish
99
+
100
+ `deco publish --draft=<name> [--message=<text>]`
101
+
102
+ - Prints what the draft changes against production (same `M`/`A`/`D` view), then publishes.
103
+ - `published revision <id>; it is live`. The site follows within about a minute
104
+ ([delivery.md](./delivery.md)). No deploy.
105
+ - `nothing to publish: production already has every block of draft <name>` when there is nothing.
106
+ - A draft saved during the publish is not emptied, and the CLI warns:
107
+ `draft <name> was saved during the publish, so it wasn't emptied: it still holds its blocks`.
108
+ - Exit 5 when production moved during the publish (Studio's `production_moved`): run it again.
109
+ - It does not run `deco check`. Run `deco check --draft=<name>` first.
110
+
111
+ ## releases and rollback
112
+
113
+ `deco releases [--cursor=<cursor>]` lists published revisions, newest first, 50 a page:
114
+
115
+ ```text
116
+ <id> current 2026-11-06T21:10:38Z <author> via <via> draft summer-sale "Summer sale banners"
117
+ <id> 2026-11-05T… <author> via <via> rollback to <id>
118
+ <id> unreadable (its meta.json couldn't be read)
119
+ more: deco releases --cursor=<cursor>
120
+ ```
121
+
122
+ `current` marks the revision `latest.json` names.
123
+
124
+ There is no rollback command in the CLI; rollbacks are made in Studio. A rollback publishes a new
125
+ revision that re-applies an old one, and `deco releases` shows it as `rollback to <id>`. Before you roll back,
126
+ check that the old content still fits the code that is deployed now:
127
+
128
+ ```bash
129
+ deco check --revision=<id>
130
+ ```
131
+
132
+ A rollback to content that uses a block type the code no longer has breaks those pages. Fix forward
133
+ with a draft instead in that case.
134
+
135
+ ## Errors worth recognizing
136
+
137
+ | Message | Exit | Meaning |
138
+ |---|---|---|
139
+ | `no Studio site: set DECO_SITE …` | 64 | No `DECO_SITE` anywhere ([schema.md](./schema.md)) |
140
+ | `no .deco/ found from <dir>; run inside your app or pass --root` | 64 | Wrong folder |
141
+ | `deco push needs --draft=<name>` | 64 | `push` and `publish` always need a draft |
142
+ | `not logged in to …; run: npx decocms auth login --target=…` | 3 | No token |
143
+ | `Studio answered <status>: <message>` | 1, 3, 4 or 5 | Studio's own error, mapped to an exit code ([cli-reference.md](./cli-reference.md)) |
144
+ | `the CDN has no revision <id>` | 1 | `pull.json` names a revision the CDN doesn't have: pull again |
145
+ | `.deco/pull.json isn't one deco pull wrote; run deco pull` | 1 | Corrupt or hand-edited `pull.json` |
146
+ | `Studio refused the save: …` | 1 or 3 | Studio rejected the content or the token |
@@ -0,0 +1,51 @@
1
+ # How published content reaches the site
2
+
3
+ With `createCMS({ blocks, site })`, content is never in the bundle. The site reads it at runtime from
4
+ `https://delivery.decocms.com/sites/<site>/`, over plain HTTP with no credential. The CDN layout is in
5
+ [content-layout.md](./content-layout.md#on-the-cdn).
6
+
7
+ ## The release index
8
+
9
+ - The first request loads `latest.json`, the current release's index. Requests that arrive meanwhile
10
+ share that one load. Each fetch has 10 s.
11
+ - If that first load fails, a 404 included (the site was never published), clients answer
12
+ `LOADER_FAILED` with a `ContentUnavailableError` cause. There is no bundled fallback and never an
13
+ empty site. A failed load isn't kept: the next request tries again.
14
+ - After that, the CMS checks for a new release in the background every `interval` (default and
15
+ minimum 60 000 ms, plus or minus up to 10 s). A request starts the check and never waits for it. The
16
+ check sends `If-None-Match`, so an unchanged index is a 304.
17
+ - A read is adopted only if its `sequence` is higher than the one held, so a stale CDN answer never
18
+ moves the site backwards. A failed check keeps the last good index.
19
+
20
+ So a publish shows on a given isolate within about 70 s, without a deploy.
21
+
22
+ ## Blocks
23
+
24
+ - A request walks the routes and references in the index, then fetches the bodies it needs by hash
25
+ (`blocks/<hash>.json`) in one parallel wave. A body never changes, so it is cached per isolate in an
26
+ LRU of 32 MiB of JSON. Concurrent requests share one fetch per hash.
27
+ - Each request pins the index it started with.
28
+ - Right after a publish, a page whose new blocks aren't cached yet is served from the previous index
29
+ while they load in the background. The next request gets the new content.
30
+ - An index or a body over 16 MiB is refused.
31
+
32
+ ## Drafts and old releases
33
+
34
+ - A draft request (`?__draft=…` or the draft cookie) always revalidates at the CDN and never shares the
35
+ isolate's cached copy. It checks for the latest release once, so a preview shows a release published
36
+ a moment ago.
37
+ - A link with a release id in place of a draft (Studio's "Preview this version") reads
38
+ `revisions/<id>/index.json`. The last three such indexes are kept in memory.
39
+ - Previews only open on allowed hosts: see [serve-and-studio.md](./serve-and-studio.md#step-5-previews-in-studio-and-on-your-machine).
40
+ - The TanStack worker never hands a preview to the site's page cache and answers it with
41
+ `Cache-Control: max-age=0, no-cache, must-revalidate`, `Vary: Cookie` and `noindex`.
42
+
43
+ ## When a publish doesn't show
44
+
45
+ | Check | Meaning |
46
+ |---|---|
47
+ | `deco releases`: is your revision `current`? | If not, the publish didn't happen or someone published after you |
48
+ | `curl -s https://delivery.decocms.com/sites/<site>/latest.json` and compare `revision` | The CDN has it; the site may not have polled yet. Wait about a minute |
49
+ | The page comes from your page cache | Key the cache on the content revision (`cacheVersion(cms, buildHash, url)` from `@decocms/tanstack/worker`). See `deco-storefront-caching` |
50
+ | The content is read outside the CMS client | Code that imports `.deco/blocks/*.json` directly, or a build script that reads `.deco/blocks`, stays on the last deploy. Read it through the client |
51
+ | The site runs without `site` | A bundled site (`content`) changes only with a deploy |
@@ -0,0 +1,87 @@
1
+ # Deploy: order, CI and secrets
2
+
3
+ Code ships with a deploy. Content ships with a publish. The schema is how Studio learns about the
4
+ code. Each of the three can break the others if they go out in the wrong order.
5
+
6
+ ## Variables and secrets
7
+
8
+ | Name | Read by | Secret? | Where it lives |
9
+ |---|---|---|---|
10
+ | `DECO_SITE` | the CLI; your code, to pass `createCMS({ site })` | no | `wrangler.jsonc` `vars` (Workers), `.env`, or CI env. The CLI also reads `.dev.vars` |
11
+ | `DECO_TOKEN` | the CLI only | **yes** | CI secrets, or your shell. Never in the site's runtime env or in git |
12
+ | `DECO_STUDIO_URL` | the CLI only | no | Unset, except for a local or staging Studio |
13
+ | `DECO_STUDIO_ORIGIN` | the bindings, at runtime | no | Unset, except to trust a local Studio's origin |
14
+ | the site token passed as `createCMS({ token })` | your code | **yes** | A runtime secret (for example a Worker secret). Only for hosted telemetry |
15
+
16
+ Commerce keys and other upstream credentials are runtime secrets of the deploy platform, read by code
17
+ and passed as params. Content never holds secrets: `deco check` rejects the old `secret` blocks. On
18
+ deco's own hosting, how env vars and secrets are set is `deco-control-plane-ops` (decocms/skills).
19
+
20
+ `DECO_TOKEN` is a Studio API key. Without it, the CLI runs `npx decocms auth token`, which works on a
21
+ laptop after `npx decocms auth login` but not in CI.
22
+
23
+ ## Which commands need what
24
+
25
+ | Command | `DECO_SITE` | Token |
26
+ |---|---|---|
27
+ | `deco schema`, `deco schema --check`, `deco content` | no | no |
28
+ | `deco check` (production) | yes (else it checks local `.deco/blocks`) | no |
29
+ | `deco check --revision` | yes | no |
30
+ | `deco pull`, `deco diff` (production) | yes | no |
31
+ | `deco pull --draft`, `deco diff --draft`, `deco check --draft`, `deco push`, `deco publish`, `deco drafts`, `deco releases`, `deco schema push` | yes | yes |
32
+
33
+ ## The production pipeline
34
+
35
+ ```text
36
+ pull request: deco schema --check
37
+ production: install -> deco schema --check -> deco check -> deploy -> deco schema push
38
+ ```
39
+
40
+ - `deco schema --check` fails when the committed schema doesn't match the code.
41
+ - `deco check` checks the **live content** against the **new code**, before the deploy. It catches a
42
+ removed block type, a renamed field or a newly required field while production still runs the old
43
+ code.
44
+ - `deco schema push` runs **after** the deploy succeeds, so Studio's forms never describe code that
45
+ isn't live, and only on production. A preview deploy that pushes would let editors save content the
46
+ live code can't render.
47
+
48
+ GitHub Actions and other platforms: [schema.md](./schema.md#step-5-push-it-on-every-production-deploy).
49
+
50
+ A content publish from Studio can also break the next deploy's `deco check` (an editor saves something
51
+ the next code rejects). That is the gate working: fix the content in a draft, or the code.
52
+
53
+ ## Changes that touch both code and content
54
+
55
+ **Content needs new code** (a new section, a new field):
56
+
57
+ 1. Merge and deploy the code. The pipeline pushes the schema.
58
+ 2. Edit in Studio, or `deco push --draft=<name>`.
59
+ 3. `deco check --draft=<name>`, preview, `deco publish --draft=<name>`.
60
+
61
+ Publishing first would put content in production that the live code can't resolve.
62
+
63
+ **Code removes or narrows something content uses** (delete a block type, rename a field, make a field
64
+ required):
65
+
66
+ 1. Publish content that no longer uses it, or that fills the new field.
67
+ 2. Deploy the code. The pipeline's `deco check` passes only after step 1.
68
+
69
+ To find what uses a block type, `deco pull` and grep `.deco/blocks` for `"__resolveType": "<type>"`
70
+ and for references to the saved blocks of that type.
71
+
72
+ **First deploy of a hosted site:** publish a first release before the deploy that sets `site`, or
73
+ every page fails with `LOADER_FAILED`. See [serve-and-studio.md](./serve-and-studio.md#step-3-publish-a-first-release-before-you-deploy-with-site).
74
+
75
+ ## Rollback
76
+
77
+ - Code: redeploy the previous build. Then run `deco schema && deco schema push` from that commit so
78
+ Studio's forms match it again.
79
+ - Content: the CLI has no rollback command; roll back in Studio. First run `deco check --revision=<id>`
80
+ against the code that is live.
81
+ See [content-sync.md](./content-sync.md#releases-and-rollback).
82
+
83
+ ## Page caches
84
+
85
+ A page cache must key on the content revision, or a publish doesn't show until entries expire. The
86
+ TanStack helper `cacheVersion(cms, buildHash, page.url)` gives `<build>.<revision>`. Cache design is
87
+ `deco-storefront-caching`.
@@ -0,0 +1,173 @@
1
+ # Send the schema to Studio
2
+
3
+ Studio draws its editor forms from a schema the site sends. Studio never runs your code. If it has
4
+ no schema for the site, or an old one, its forms are missing or wrong. This page takes a site from
5
+ "Studio asks for the schema" to "every production deploy sends it", with nothing else to read.
6
+
7
+ ## What the schema is
8
+
9
+ - `.deco/index.ts` (or `.deco/index.tsx`) default-exports the **block map**: an object of named
10
+ functions. Each function's first parameter type becomes a form.
11
+ - `deco schema` reads that file with the site's own TypeScript and writes `.deco/schema.gen.json`.
12
+ The file declares `"blocksMajor": 8`. Studio treats a site as v8 only from that field.
13
+ - `deco schema push` uploads that file to Studio for the site named by `DECO_SITE`.
14
+
15
+ How a Props type maps to fields (JSDoc tags, widgets, shapes that break a form) is the
16
+ `deco-cms-schema` skill.
17
+
18
+ ## Step 1: generate it
19
+
20
+ Requirements: `@decocms/blocks` 8 and `typescript` (a peer dependency) installed in the site.
21
+
22
+ ```bash
23
+ npx deco schema
24
+ ```
25
+
26
+ On success it prints one line:
27
+
28
+ ```text
29
+ wrote .deco/schema.gen.json from index.ts (12 sections, 3 loaders, 0 matchers, 2 pages, 1 content types)
30
+ ```
31
+
32
+ (`unchanged` instead of `wrote` when the file was already up to date.) Commit
33
+ `.deco/schema.gen.json`.
34
+
35
+ If the schema has errors, the file is **not written**, so the committed file never holds a half-right
36
+ form. Fix the errors it prints and run it again. Common lines:
37
+
38
+ | Message | Fix |
39
+ |---|---|
40
+ | `no .deco/ found from <dir>; run inside your app or pass --root` | Run from the app folder, or `--root <dir>` |
41
+ | `no .deco/index.ts (or .deco/index.tsx) in <root>; it holds your block map` | Create the block map |
42
+ | `.deco/index.ts: no default export; export your block map as the default` | `export default { … } satisfies Blocks` |
43
+ | `.deco/index.ts: "<key>" isn't a function` | Every value in the map must be a function |
44
+ | `deco schema reads your types with TypeScript, which isn't installed: …` | Add `typescript` to devDependencies |
45
+ | warning `"<key>": its props are typed any, so its form is empty` | Type the first parameter |
46
+ | warning `"<key>": returns any, so it isn't offered for any field` | Type the return value |
47
+ | warning `"<key>": its first parameter isn't an object of props, so its form is empty` | Take one props object |
48
+ | `"<key>": has a "path" field but its type doesn't extend Route (name: string; path: string)` | A `path` field makes a block routable: give its type `name` and `path`, or rename the field |
49
+
50
+ Run `deco schema` before `dev` and `build`, so the file follows the code:
51
+
52
+ ```json
53
+ {
54
+ "scripts": {
55
+ "predev": "deco schema",
56
+ "prebuild": "deco schema"
57
+ }
58
+ }
59
+ ```
60
+
61
+ `deco schema --watch` regenerates on every `.ts`/`.tsx` change (it skips `node_modules`, `dist`,
62
+ `.git*` and `*.gen.ts`, and also watches files outside the root that the block map imports, such as
63
+ monorepo packages). Stop it with ctrl-c.
64
+
65
+ ## Step 2: tell the CLI which site
66
+
67
+ The CLI reads `DECO_SITE`, first match wins:
68
+
69
+ 1. the environment;
70
+ 2. `.env`, then `.dev.vars`, in the folder that contains `.deco/`;
71
+ 3. `vars.DECO_SITE` in `wrangler.jsonc`, `wrangler.json`, then `wrangler.toml` (the `[vars]` table or
72
+ a top-level inline `vars = { … }`), same folder.
73
+
74
+ The value is Studio's site name: letters, digits, `.`, `_`, `-`, starting with a letter or digit.
75
+ Studio finds the organization from the site; the CLI never takes one. A `DECO_SITE` committed in
76
+ `wrangler.jsonc` `vars` (or another file in the list) is found in CI too, with no extra setup.
77
+
78
+ Missing everywhere: exit 64 with
79
+ `no Studio site: set DECO_SITE in the environment, or in <root>'s .env, .dev.vars, or vars.DECO_SITE of wrangler.jsonc, wrangler.json or wrangler.toml (looked in that order)`.
80
+
81
+ ## Step 3: a token
82
+
83
+ The CLI sends `Authorization: Bearer <token>` to Studio. It takes the token from:
84
+
85
+ 1. `DECO_TOKEN`, when set (use a Studio API key; this is the CI path);
86
+ 2. else the output of `npx decocms auth token --target=<DECO_STUDIO_URL>` (Studio CLI's session; the
87
+ CLI has no login of its own). Log in once with `npx decocms auth login --target=https://studio.decocms.com`.
88
+ `deco login` prints that command.
89
+
90
+ No token: exit 3, `not logged in to https://studio.decocms.com; run: npx decocms auth login --target=https://studio.decocms.com`.
91
+ A token Studio rejects: exit 3, `Studio answered 401: … (check DECO_TOKEN, or log in again with npx decocms auth login)`.
92
+ A 403 is also exit 3: Studio refused the token for this site.
93
+
94
+ `DECO_STUDIO_URL` changes the Studio API base (default `https://studio.decocms.com`). Leave it unset
95
+ unless you run a local or staging Studio.
96
+
97
+ ## Step 4: push it
98
+
99
+ ```bash
100
+ npx deco schema push
101
+ ```
102
+
103
+ It reads `.deco/schema.gen.json` as it is on disk (it does not regenerate it) and sends it to Studio.
104
+ Success:
105
+
106
+ ```text
107
+ pushed .deco/schema.gen.json (a v8 schema)
108
+ ```
109
+
110
+ `(not a v8 schema)` means the file has no `"blocksMajor": 8`: an older generator wrote it. Run
111
+ `deco schema` again, commit, push again.
112
+
113
+ | Message | Exit | Fix |
114
+ |---|---|---|
115
+ | `no .deco/schema.gen.json; run deco schema first` | 1 | Run `deco schema` |
116
+ | `.deco/schema.gen.json: invalid JSON: …` | 1 | Regenerate it |
117
+ | `deco schema push takes no --watch or --check` | 64 | Drop the flag |
118
+ | `Studio (…) unreachable (…)` / `timed out` | 4 | Network; retry |
119
+
120
+ Reload Studio. The forms now follow the pushed schema.
121
+
122
+ ## Step 5: push it on every production deploy
123
+
124
+ Studio should describe the code that is live. So push from the job that deploys production, after
125
+ the deploy succeeds, and never from preview branches. In pull requests, check that the committed file
126
+ is current instead.
127
+
128
+ GitHub Actions, as a sketch (adapt the install and deploy steps to the site):
129
+
130
+ ```yaml
131
+ # .github/workflows/deploy.yml
132
+ on:
133
+ push:
134
+ branches: [main]
135
+ jobs:
136
+ deploy:
137
+ runs-on: ubuntu-latest
138
+ env:
139
+ DECO_TOKEN: ${{ secrets.DECO_TOKEN }} # a Studio API key
140
+ # DECO_SITE: my-store # only if it isn't in wrangler.* vars or .env
141
+ steps:
142
+ - uses: actions/checkout@v4
143
+ - run: npm ci
144
+ - run: npx deco schema --check # committed file matches the code
145
+ - run: npx deco check # live content fits this code
146
+ - run: npm run deploy # your deploy
147
+ - run: npx deco schema push # Studio's forms follow what just went live
148
+ ```
149
+
150
+ ```yaml
151
+ # pull requests
152
+ - run: npx deco schema --check
153
+ ```
154
+
155
+ `deco schema --check` writes nothing. It exits 1 when the file is missing or stale and prints what
156
+ moved, for example `sections: new in code: hero` or `2 schema definitions changed (fields or
157
+ choices)`, then `Run \`deco schema\` and commit .deco/schema.gen.json.` It exits 0 with
158
+ `.deco/schema.gen.json is up to date with index.ts`.
159
+
160
+ If the deploy runs somewhere else (Cloudflare Workers Builds, a hosting control plane), run
161
+ `deco schema push` in that platform's production deploy command after the deploy, with `DECO_TOKEN`
162
+ as a secret build variable. Where deco's hosting keeps env vars and secrets is in
163
+ `deco-control-plane-ops` (decocms/skills). The ordering with `deco check` and `deco publish` is in
164
+ [deploy.md](./deploy.md).
165
+
166
+ ## Checklist
167
+
168
+ - [ ] `typescript` installed; `deco schema` prints `wrote` or `unchanged`
169
+ - [ ] `.deco/schema.gen.json` committed, with `"blocksMajor": 8`
170
+ - [ ] `DECO_SITE` resolvable from the app folder
171
+ - [ ] `deco schema push` prints `(a v8 schema)`
172
+ - [ ] Production deploy job runs `deco schema push` with `DECO_TOKEN` from secrets
173
+ - [ ] Pull requests run `deco schema --check`
@@ -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.