@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,116 @@
1
+ # SEO and JSON-LD
2
+
3
+ A page's title, description, canonical and structured data come from its `seo` field.
4
+ It is a block like any other, resolved on the server before the response is sent, so
5
+ crawlers and people get the same HTML. There is no deferred SEO section, no HTMX
6
+ head-support, and no separate bot render on v8.
7
+
8
+ ## The `seo` field
9
+
10
+ The built-in `page` has an optional `seo` field. Studio offers any block that returns:
11
+
12
+ - `Seo` from `@decocms/blocks`: `{ title: string; description: string }`, or
13
+ - an object whose fields are all optional, with a string `title` or `description`
14
+ (a richer type of the site's own, such as a `PageSeo` with `canonical` and `jsonLDs`).
15
+
16
+ A loader whose result has required fields (a post with a required `title` and
17
+ `excerpt`) is content, not SEO, and is not offered.
18
+
19
+ The smallest setup is the one in the examples: a block that returns its input.
20
+
21
+ ```ts
22
+ export default {
23
+ seo: (input: Seo) => input,
24
+ // ...sections
25
+ } satisfies Blocks;
26
+ ```
27
+
28
+ The page loader resolves `page.seo` (after starting every section, so SEO does not
29
+ delay them), and the route turns it into tags: `head()` on TanStack Start,
30
+ `generateMetadata` on Next.js. Without `seo`, the root layout's defaults apply. The
31
+ head wiring is in the `deco-tanstack-site` and `deco-nextjs-site` skills.
32
+
33
+ ## Feed SEO from the same loader as the page
34
+
35
+ On a product or listing page, the title, description, canonical and JSON-LD come from
36
+ the same product or listing the page shows. Do not fetch it twice, and do not type it
37
+ by hand into content.
38
+
39
+ Write an SEO block that takes the same param as the section and resolves the same
40
+ loader through the current client:
41
+
42
+ ```ts
43
+ import { currentClient } from "@decocms/blocks";
44
+ import type { Product } from "@decocms/compat-v7/commerce/types";
45
+
46
+ export interface PageSeo {
47
+ title?: string;
48
+ description?: string;
49
+ canonical?: string;
50
+ noIndexing?: boolean;
51
+ jsonLDs?: Record<string, unknown>[];
52
+ }
53
+
54
+ export interface ProductSeoProps {
55
+ /** @ignore */
56
+ slug?: string;
57
+ /** @title Title template, %s is the product name */
58
+ titleTemplate?: string;
59
+ }
60
+
61
+ export async function productSeo({ slug, titleTemplate = "%s" }: ProductSeoProps): Promise<PageSeo> {
62
+ const client = currentClient(); // before any await
63
+ const [product, error] = await client.resolve<Product>({ __resolveType: "product-by-slug", slug });
64
+ if (error || !product) return { noIndexing: true };
65
+ return {
66
+ title: titleTemplate.replace("%s", product.name ?? ""),
67
+ description: product.description,
68
+ jsonLDs: [{ "@context": "https://schema.org", ...product }],
69
+ };
70
+ }
71
+ ```
72
+
73
+ ```json
74
+ "seo": { "__resolveType": "product-seo", "titleTemplate": "%s | Store" }
75
+ ```
76
+
77
+ The page loader passes `slug` to `seo` the same way it passes it to the sections (see
78
+ [pages.md](./pages.md)). Both resolve `product-by-slug` with the same inputs on the
79
+ same client, so the upstream call runs once and both get the same object (see
80
+ [loaders.md](./loaders.md)). If they pass different inputs (one adds a field the other
81
+ does not), they make two calls. Keep the loader inputs identical.
82
+
83
+ For a listing page, do the same with the listing loader. `ProductListingPage` and
84
+ `ProductDetailsPage` in `@decocms/compat-v7/commerce/types` carry an optional `seo`
85
+ (`title`, `description`, `canonical`, `noIndexing`) when the platform provides one, and
86
+ `canonicalFromBreadcrumblist` in `@decocms/compat-v7/commerce/utils/canonical` returns
87
+ the `item` URL of the breadcrumb with the highest `position`.
88
+
89
+ ## JSON-LD
90
+
91
+ - Emit each structured-data object once, as `<script type="application/ld+json">`. If
92
+ the route emits `jsonLDs` from `seo`, no section should render the same object again.
93
+ - Escape `<` in the serialized JSON (`JSON.stringify(x).replace(/</g, "\\u003c")`), so
94
+ a product description with `</script>` cannot end the tag.
95
+ - Product JSON-LD from a platform `Product` is large. Trim it to what rich results use
96
+ (name, image, description, sku, brand, offers with price, currency and availability,
97
+ aggregate rating) before you serialize it.
98
+ - A block that renders nothing and only feeds data (fonts, a JSON-LD helper) can take
99
+ its data as `Lazy<T>`, so nothing is fetched when it is not used. See
100
+ [lazy-blocks.md](./lazy-blocks.md).
101
+
102
+ ## Checklist for a site
103
+
104
+ 1. The root layout sets a default title, description, `og:site_name` and `lang`.
105
+ 2. Every page has `seo`, or relies on the defaults on purpose.
106
+ 3. Product and listing pages use an SEO block that resolves the same loader, with the
107
+ same inputs, as the main section.
108
+ 4. Empty listing pages and not-found products set `noIndexing` (or the route returns
109
+ 404). Drafts are already sent with `X-Robots-Tag: noindex, nofollow` by the
110
+ bindings' draft response headers.
111
+ 5. A canonical URL is set on pages that can be reached with tracking or filter params.
112
+ 6. JSON-LD appears once per object.
113
+ 7. Check one page of each type with `curl -s <url> | grep -E "<title|og:|ld\+json|canonical"`.
114
+ v8 sends the same HTML to bots and people, so one request is enough.
115
+
116
+ Coverage audits, `robots.txt` and sitemaps are not part of this skill.
@@ -0,0 +1,101 @@
1
+ ---
2
+ name: deco-site-workflow
3
+ description: "End-to-end workflow for a site on @decocms/blocks 8 with the `deco` CLI it ships. Covers where content lives (.deco/index.ts, .deco/schema.gen.json, .deco/blocks, block names and files), generating the schema (`deco schema`, `--check`, `--watch`) and sending it to Studio (`deco schema push`, run on every production deploy with a DECO_TOKEN), validating content (`deco check` against production, a draft or a revision), syncing content (`pull`, `diff`, `push --draft`, `drafts`, `publish`, `releases`, rollback), editing a site in deco Studio now that `deco serve` is gone (8.10+), how published releases reach the site from the CDN, every command, flag, env var (DECO_SITE, DECO_TOKEN, DECO_STUDIO_URL, DECO_STUDIO_ORIGIN) and exit code. Load it when setting up or deploying a v8 site, when Studio asks you to send the schema or connect deco serve, when a deco command fails or exits non-zero, when `deco check` fails, or when content differs between Studio, a draft, local dev and production."
4
+ ---
5
+
6
+ # Deco site workflow (@decocms/blocks 8)
7
+
8
+ A v8 site has two things that change on different schedules:
9
+
10
+ - **Code**: the block map in `.deco/index.ts` and the functions it registers. It ships with a deploy.
11
+ `deco schema` turns its types into `.deco/schema.gen.json`, which Studio uses to draw forms.
12
+ - **Content**: saved blocks (JSON). With `createCMS({ blocks, site })` the site reads them at runtime
13
+ from the delivery CDN. Studio and the `deco` CLI write drafts. Only `deco publish` (or Studio's
14
+ publish) makes a draft live, and no deploy is needed.
15
+
16
+ The `deco` CLI is the `bin` of `@decocms/blocks`. It connects the two: it sends the schema to Studio,
17
+ checks content against the code, and moves content between `.deco/blocks` and Studio.
18
+
19
+ This skill covers the 8.10+ CLI (content on the CDN). `deco serve` was removed in 8.10.0. See
20
+ [serve-and-studio.md](./references/serve-and-studio.md).
21
+
22
+ ## When to load what
23
+
24
+ | Reference | Load it when |
25
+ |---|---|
26
+ | [`references/schema.md`](./references/schema.md) | Studio says to send the schema; forms are missing or stale; wiring `deco schema push` into CI or the deploy; `deco schema` fails |
27
+ | [`references/serve-and-studio.md`](./references/serve-and-studio.md) | Studio says to connect `deco serve`; connecting a site to Studio; the page doesn't load or edit inside Studio; a draft link shows production |
28
+ | [`references/content-sync.md`](./references/content-sync.md) | Editing content from the terminal: `pull`, `diff`, `push --draft`, conflicts, `drafts`, `publish`, `releases`, rollback |
29
+ | [`references/check.md`](./references/check.md) | `deco check` prints errors or warnings, or you want it as a gate |
30
+ | [`references/content-layout.md`](./references/content-layout.md) | What each file in `.deco/` is, block names and file names, `__resolveType`, references, the built-in blocks, what goes in git |
31
+ | [`references/delivery.md`](./references/delivery.md) | A publish doesn't show on the site; a site fails with `LOADER_FAILED`; how the CDN, polling and draft previews work |
32
+ | [`references/deploy.md`](./references/deploy.md) | Setting up CI and the deploy: order of schema push, check and publish; where `DECO_SITE`, `DECO_TOKEN` and other secrets live |
33
+ | [`references/cli-reference.md`](./references/cli-reference.md) | The exact flags, env vars, exit codes, `--json` output and common error lines of every command |
34
+
35
+ ## The loop, in commands
36
+
37
+ ```bash
38
+ # code changed
39
+ deco schema # .deco/index.ts -> .deco/schema.gen.json (commit it)
40
+ deco check # production content against this code
41
+ # ...deploy, then on production only:
42
+ deco schema push # Studio's forms follow the deployed code
43
+
44
+ # content from the terminal
45
+ deco pull # production into .deco/blocks (or --draft=<name>)
46
+ # edit .deco/blocks/*.json
47
+ deco diff
48
+ deco push --draft=my-change # never goes live; prints a preview link
49
+ deco check --draft=my-change # the draft as a whole, against this code
50
+ deco publish --draft=my-change # goes live; no deploy
51
+ ```
52
+
53
+ Every command finds `.deco/` by walking up from the current folder (or takes `--root`). Every command
54
+ takes `--json`.
55
+
56
+ ## Exit codes
57
+
58
+ | Code | Meaning | What to do |
59
+ |---|---|---|
60
+ | 0 | ok | |
61
+ | 1 | failed (check errors, bad file, missing schema, CDN 4xx) | Read the message |
62
+ | 2 | conflict on `deco push` | Pull again, or push with `--ours` / `--theirs` |
63
+ | 3 | auth: no token, or Studio answered 401/403 | Set `DECO_TOKEN`, or `npx decocms auth login` |
64
+ | 4 | network: Studio or CDN unreachable, timed out, or 5xx | Retry later |
65
+ | 5 | busy: Studio answered 429, 503 `unavailable` or 409 `production_moved` | Run the same command again |
66
+ | 64 | usage: unknown command or flag, no `DECO_SITE`, no `.deco/` for a remote command | Fix the command line or config |
67
+
68
+ ## Get these skills into a site
69
+
70
+ From 8.11.0, `@decocms/blocks` ships the skills of `.agents/skills/` and the CLI copies them into the
71
+ site, offline:
72
+
73
+ ```bash
74
+ npx deco skills install # into .claude/skills/<skill>/
75
+ npx deco skills install --dir=.agents/skills # elsewhere; relative to the folder that contains .deco/
76
+ ```
77
+
78
+ It finds `.deco/` like every command (walk up, or `--root`; none found exits 1) and takes `--json`
79
+ (`{ ok, dir, version, skills }`). Each shipped skill's folder is deleted and copied again, so files
80
+ from an older version go away; folders of skills it doesn't ship are left alone. Run it again after
81
+ upgrading `@decocms/blocks`. On 8.10 or older, copy the folders from `.agents/skills/` on `main`.
82
+
83
+ ## Related skills
84
+
85
+ - `deco-cms-schema`: how a Props type becomes a form, and the shapes that break it.
86
+ - `deco-site-authoring`: writing sections, pages and loaders.
87
+ - `deco-tanstack-site` / `deco-nextjs-site`: wiring `createCMS`, routes, the worker, the Studio bridge.
88
+ - `deco-make-editable`: turning hardcoded content into blocks and seeding it with `deco push`.
89
+ - `deco-variants`: multivariate blocks, tests and campaigns.
90
+ - `deco-storefront-caching`: page caches keyed on the content revision.
91
+ - `deco-v7-to-v8-migration`: sites still on v7 or on bundled content.
92
+ - `deco-control-plane-ops` (decocms/skills): env vars, secrets and deploys on deco's hosting.
93
+
94
+ ## Rules
95
+
96
+ - Never commit a token. `DECO_TOKEN` lives in CI secrets or your shell, not in `.env` files in git.
97
+ - `deco push` never publishes. Only `deco publish` goes live. Check the draft before you publish it.
98
+ - Commit `.deco/schema.gen.json`. For a site with `DECO_SITE`, keep `.deco/blocks/` and
99
+ `.deco/pull.json` out of git: they are a working copy of Studio's content.
100
+ - Push the schema only from production deploys. A preview branch that pushes makes Studio's forms
101
+ describe code that isn't live.
@@ -0,0 +1,116 @@
1
+ # `deco check`: content against code
2
+
3
+ `deco check` validates saved blocks against `.deco/schema.gen.json`, the schema of the code in your
4
+ folder. It writes nothing, generates no schema and loads no TypeScript. So run `deco schema` first,
5
+ or it checks against a stale file.
6
+
7
+ ## Which content it checks
8
+
9
+ | Command | Checks | Needs |
10
+ |---|---|---|
11
+ | `deco check` with `DECO_SITE` set | **Production**: the live release, read from the CDN | `DECO_SITE`; no token |
12
+ | `deco check` with no `DECO_SITE` anywhere | The local `.deco/blocks` (a bundled site) | nothing |
13
+ | `deco check --draft=<name>` | Production with that draft on top | `DECO_SITE` and a token |
14
+ | `deco check --revision=<id>` | One published revision (ids from `deco releases`) | `DECO_SITE` |
15
+
16
+ `--draft` and `--revision` together are a usage error (64). A malformed id is
17
+ `"<id>" isn't a revision id (deco releases lists them)` (64). An id the CDN doesn't have is
18
+ `no revision <id> on the CDN` (1).
19
+
20
+ **Trap:** on a hosted site, plain `deco check` ignores your local edits in `.deco/blocks`. It checks
21
+ production. To check edits, push them to a draft and run `deco check --draft=<name>`. Pushing never
22
+ publishes, so this is safe.
23
+
24
+ It prints `checking production (revision <id>)` (or the draft or revision), then problems grouped by
25
+ file, then a summary:
26
+
27
+ ```text
28
+ .deco/blocks/Home.json
29
+ sections[2].title: 214 characters, max 60
30
+ warning: sections[4]: can never be picked: variants[0] has an always rule
31
+ 39 saved blocks checked: 1 error, 1 warning
32
+ ```
33
+
34
+ Exit 0 when there are no errors (warnings don't fail it), 1 otherwise. With `--json`, stdout is
35
+ `{ ok, blocks, errors, warnings, problems: [{ file, path, message, severity }] }`.
36
+
37
+ ## Use it as a gate
38
+
39
+ - **Before a deploy:** `deco schema && deco check` checks that the live content fits the new code. A
40
+ removed block type, a renamed or newly required field shows up here, before the deploy breaks pages.
41
+ - **Before a publish:** `deco check --draft=<name>`. `deco publish` doesn't check.
42
+ - **Before a rollback:** `deco check --revision=<id>`.
43
+
44
+ Where these go in CI: [deploy.md](./deploy.md).
45
+
46
+ ## Field errors
47
+
48
+ Each line is `<path>: <message>`, with the path inside the block (`sections[2].title`).
49
+
50
+ | Message | Means | Fix |
51
+ |---|---|---|
52
+ | `required` | The type requires a field the content lacks | Add it, or make the field optional in the type |
53
+ | `unknown field` | The content has a field no type declares | Delete it, or add it to the type |
54
+ | `214 characters, max 60` / `min` | String length outside the type's limits | Shorten the text or relax the limit |
55
+ | `5, max 3` / `min`, `must be under`, `must be over` | Number out of range | |
56
+ | `4 items, max 3` / `min` | List length out of range | |
57
+ | `"xl" isn't one of "sm", "md", "lg"` | Not an allowed option | Use one of them, or add it to the type |
58
+ | `expected a string, got a number` | Wrong JSON type | |
59
+ | `"…" isn't a valid date-time` | Format check (`date`, `date-time`, `uri`) | ISO dates with an offset; absolute URLs |
60
+ | `doesn't match the pattern …` | Pattern check | |
61
+ | `doesn't match any allowed form` | A union where no branch fits | Compare with each branch of the type |
62
+
63
+ How types and JSDoc tags turn into these rules is the `deco-cms-schema` skill.
64
+
65
+ ## Block errors
66
+
67
+ | Message | Means | Fix |
68
+ |---|---|---|
69
+ | `no saved block or block type "<name>"` | `__resolveType` names nothing: a deleted saved block still referenced, or a type the code no longer exports | Remove the reference, restore the block, or deploy the type first |
70
+ | `"<type>" doesn't fit here: its function doesn't return this field's type` | A block in a field whose type it doesn't produce | Use a block of the right kind |
71
+ | `"<type>" doesn't fit here: this field takes a plain value` | A block where a plain value is expected | Write the value |
72
+ | `saved block "<name>" (a "<type>") doesn't fit here: …` | A reference to a saved block of the wrong kind | Reference another block |
73
+ | `this field is Lazy<T>: wrap the value in a lazy block` / `a lazy block only fits a Lazy<T> field` | Lazy fields need `{ "__resolveType": "lazy", "value": … }`, and only they take one | Wrap or unwrap |
74
+ | `references form a cycle: A → B → A` | Saved blocks that reference each other | Break the loop |
75
+ | `saved block "<name>" has the name of an alias` (or `of a built-in block`, `of a block type`) | Saved block names share one namespace with block types, built-ins and v7 aliases | Rename it |
76
+ | `missing __resolveType: a saved block names the function it calls` | The file has no `__resolveType` | Add it |
77
+ | `"<path>" is also the path of "<other>"` / `matches the same URLs as …` | Two pages (or two redirect `from`s) route the same URLs | Change one path |
78
+ | `a rule must be a block whose function returns a boolean` | A variant `rule` that isn't a matcher | |
79
+ | `a variant's value must be a lazy block` | Variant values are wrapped in `lazy` | |
80
+ | `no test "<name>" in the saved block "experiments": this rule is always false` | An `experiment` rule names a missing test | Add the test or fix the name |
81
+ | `no campaign "<name>" in the saved block "campaigns": this rule is always false` | Same, for campaigns | |
82
+ | `unknown block type "date": …` | The prerelease `date` rule | Use a `campaign` rule as the message says |
83
+ | `unknown block type "secret"` (or `telemetry`, `analytics`, `date-windows`) `: …` | A removed built-in | Follow the message. Secrets belong in the deploy platform, read by code |
84
+
85
+ ## Warnings
86
+
87
+ | Message | Fix |
88
+ |---|---|
89
+ | `can never be picked: variants[i] has an always rule` | Variants after an `always` rule are dead: reorder or delete |
90
+ | `this campaign rule names no campaign, so it is always false: …` | Name a campaign |
91
+ | `the campaign "<key>" ends before it starts, so it never runs: …` | Fix the dates |
92
+ | `not routed; move it into the redirects block` | A per-rule `redirect` block: move its rule into `Redirects` |
93
+ | `v7 redirect block (type …) isn't routed: …` | Fold its rules into `Redirects` and delete it |
94
+ | `another redirects block, "<name>", is the one routed; this one is ignored. …` | Keep one `redirects` block |
95
+ | `"CMS" is the name of the CMS settings block …`, `"experiments" is the saved block every experiment rule reads …` | A saved block uses a reserved role name with the wrong type: rename it |
96
+ | `the block map has its own "<name>", in place of the built-in: …` | Your block map replaces a built-in. Rename yours unless you mean it |
97
+ | `the site editor now keeps the addresses this site can be previewed on, …` | Delete the old `preview` field from the `CMS` block |
98
+
99
+ ## File problems
100
+
101
+ | Message | Severity | Fix |
102
+ |---|---|---|
103
+ | `invalid JSON: …` | error | Fix the file |
104
+ | `a saved block must be a JSON object` | error | |
105
+ | `not a valid entry name (…); rename the file` | error | See the name rules in [content-layout.md](./content-layout.md) |
106
+ | `subfolders of .deco/blocks aren't read` | warning | Move the file up |
107
+ | `another spelling of "<name>"; <file> wins` | warning | Delete the other spelling |
108
+
109
+ A file error also stops `deco push` and `deco diff` before they send or compare anything.
110
+
111
+ ## Schema file problems
112
+
113
+ | Message | Fix |
114
+ |---|---|
115
+ | `no <root>/.deco/schema.gen.json; run deco schema first` | `deco schema` |
116
+ | `… has no top-level "blocksMajor"; expected "blocksMajor": 8. …` | Regenerate with the v8 CLI, commit |
@@ -0,0 +1,106 @@
1
+ # `deco` CLI reference (@decocms/blocks 8.10+)
2
+
3
+ The `deco` bin ships in `@decocms/blocks` (`npx deco`, `bunx deco`, or `deco` in package scripts).
4
+ The same commands are importable from `@decocms/blocks/cli` (`runCli`, `schema`, `check`,
5
+ `content`).
6
+
7
+ ## Commands
8
+
9
+ | Command | Flags | Does |
10
+ |---|---|---|
11
+ | `deco login` | | Prints how to log in: `npx decocms auth login --target=<studio>`, or set `DECO_TOKEN` to a Studio API key in CI. It doesn't log you in |
12
+ | `deco pull` | `--draft=<name>`, `--force` | Production, or production plus a draft, into `.deco/blocks` |
13
+ | `deco diff` | `--draft=<name>` | `.deco/blocks` against what was pulled, or against a draft |
14
+ | `deco push` | `--draft=<name>` (required), `--ours` \| `--theirs`, `--prune` | Changed blocks into a draft, as one save; deletes only with `--prune` |
15
+ | `deco publish` | `--draft=<name>` (required), `--message=<text>` | Makes a draft live |
16
+ | `deco drafts` | `list` \| `new <name>` \| `discard <name>` \| `url <name>` | Manage drafts |
17
+ | `deco releases` | `--cursor=<cursor>` | Published revisions, newest first, 50 a page |
18
+ | `deco check` | `--draft=<name>` \| `--revision=<id>` | Content against `.deco/schema.gen.json` |
19
+ | `deco content` | `--watch` | `.deco/blocks` into `.deco/blocks.gen.ts`, for content without a site |
20
+ | `deco schema` | `--watch` \| `--check` | `.deco/index.ts` into `.deco/schema.gen.json` |
21
+ | `deco schema push` | | Uploads `.deco/schema.gen.json` to Studio |
22
+ | `deco skills install` | `--dir=<path>` | 8.11.0+. Copies the agent skills this `@decocms/blocks` ships into `.claude/skills/<skill>/` (or `--dir`, relative to the folder that contains `.deco/`). Replaces each shipped skill's folder whole, leaves other folders alone, no network. No `.deco/`: exit 1 |
23
+ | `deco help`, `--help`, `-h` | | Usage (exit 0). No command at all prints usage and exits 64 |
24
+
25
+ Details: [content-sync.md](./content-sync.md) (pull, diff, push, drafts, publish, releases),
26
+ [check.md](./check.md), [schema.md](./schema.md).
27
+
28
+ `deco serve` (removed in 8.10.0), `deco dev`, `deco build`, `deco generate` and `deco migrate` are not
29
+ commands: `unknown command "<name>"`, exit 64. See [serve-and-studio.md](./serve-and-studio.md).
30
+
31
+ ## Flags every command takes
32
+
33
+ | Flag | Does |
34
+ |---|---|
35
+ | `--root <dir>` | The folder that contains `.deco/` (else: walk up from the current folder) |
36
+ | `--json` | stdout carries exactly one JSON object; everything a person reads goes to stderr |
37
+ | `--color` / `--no-color` | Force colour on or off (default: on when stdout and stderr are terminals and no `--json`) |
38
+
39
+ Flag values take `--name=value` or `--name value`. Boolean flags take no value
40
+ (`--force=true` is a usage error). Unknown flags and extra arguments are usage errors (64).
41
+
42
+ ## Environment
43
+
44
+ | Variable | Used for | Default |
45
+ |---|---|---|
46
+ | `DECO_SITE` | The Studio site of every remote command | none. Looked up in the environment, then `.env`, `.dev.vars`, `wrangler.jsonc`, `wrangler.json`, `wrangler.toml` (`vars.DECO_SITE`) in the root |
47
+ | `DECO_TOKEN` | Bearer token for Studio (a Studio API key) | the output of `npx decocms auth token --target=<DECO_STUDIO_URL>` |
48
+ | `DECO_STUDIO_URL` | Studio API base | `https://studio.decocms.com` |
49
+
50
+ Reads of production and of past revisions go to `https://delivery.decocms.com` with no token. Drafts
51
+ are resolved through Studio, so they need one.
52
+
53
+ ## Exit codes
54
+
55
+ | Code | Name | When |
56
+ |---|---|---|
57
+ | 0 | ok | |
58
+ | 1 | failed | `deco check` found errors; `deco schema` had errors or `--check` found the file missing or stale; a bad local file; the CDN answered 4xx; Studio answered another 4xx; any other failure |
59
+ | 2 | conflict | `deco push`: a block changed in the draft since your pull |
60
+ | 3 | auth | No token; Studio answered 401 or 403; a save refused as unauthorized |
61
+ | 4 | network | Studio or the CDN unreachable or timed out (Studio 120 s, CDN 10 s); a 5xx |
62
+ | 5 | busy | Studio answered 429, 503 `unavailable`, or 409 `production_moved`; a save stopped part way. Run the same command again |
63
+ | 64 | usage | Unknown command or flag, bad flag value, bad draft or revision name, missing `--draft`, no `DECO_SITE`, no `.deco/` for a remote command |
64
+
65
+ `deco check` and the local commands exit 1 (not 64) when no `.deco/` is found.
66
+
67
+ ## `--json`
68
+
69
+ Success: `{ "ok": true, …result }`. Failure:
70
+
71
+ ```json
72
+ { "ok": false, "exitCode": 2, "error": { "code": "conflict", "message": "…" }, "conflicts": { … } }
73
+ ```
74
+
75
+ `error.code` values worth matching: `usage`, `not_logged_in`, `unauthorized`, `network`,
76
+ `unavailable`, `conflict`, `unpushed_changes`, `not_pulled`, `too_large`, `invalid_local_block`,
77
+ `invalid_config`, `revision_not_found`, `block_not_found`, `no_schema`, `invalid_schema`,
78
+ `check_failed`, `bad_answer`, `http_<status>`, and Studio's own codes (such as `production_moved`).
79
+
80
+ Per command, the result carries:
81
+
82
+ | Command | Fields |
83
+ |---|---|
84
+ | `pull` | `draft`, `revision`, `blocks` (count) |
85
+ | `diff` | `draft`, `revision`, `changes: [{ name, status }]` (`changed`, `new`, `deleted`) |
86
+ | `push` | `draft`, `pushed`, `batches`, `tookTheirs`, `previewUrl`, `pointer` |
87
+ | `publish` | `draft`, `result` (`published` or `up-to-date`), `revision`, `previous` (when published), `draftEmptied`, `changes` |
88
+ | `drafts` | `list`: `drafts`. `new`: `draft`. `discard`: `draft`, `discarded`. `url`: `draft`, `previewUrl`, `pointer` |
89
+ | `releases` | `live`, `revisions: [{ id, status, meta }]` (`status`: `current`, `listed`, `unreadable`), `nextCursor` |
90
+ | `check` | `blocks`, `errors`, `warnings`, `problems` |
91
+ | `schema push` | `etag`, `blocksMajor` |
92
+ | `skills install` | `dir` (absolute), `version`, `skills` (names, sorted) |
93
+ | `login` | `command` |
94
+
95
+ ## Common errors before any command runs
96
+
97
+ | Message | Exit | Fix |
98
+ |---|---|---|
99
+ | `no .deco/ found from <dir>; run inside your app or pass --root` | 64 (remote) / 1 | `cd` into the app or `--root` |
100
+ | `no .deco/ in <dir>; pass the folder that contains .deco/ as --root` | 64 / 1 | Fix `--root` |
101
+ | `no Studio site: set DECO_SITE …` | 64 | Set `DECO_SITE` |
102
+ | `DECO_SITE (from <source>) isn't a site name: "<value>"` | 64 | Letters, digits, `.`, `_`, `-` |
103
+ | `wrangler.jsonc: invalid JSON: …` | 1 | The CLI parses wrangler files to find `DECO_SITE` |
104
+ | `not logged in to <studio>; run: npx decocms auth login --target=<studio>` | 3 | Log in, or set `DECO_TOKEN` |
105
+ | `Studio answered 401: … (check DECO_TOKEN, or log in again with npx decocms auth login)` | 3 | New token |
106
+ | `Studio (<url>) unreachable (…)` / `timed out`, `the CDN (…) unreachable (…)` | 4 | Network; retry |
@@ -0,0 +1,93 @@
1
+ # Where content lives
2
+
3
+ ## The `.deco/` folder
4
+
5
+ Every `deco` command finds the folder that contains `.deco/` by walking up from the current folder,
6
+ or takes `--root <dir>`. That folder is the **root**: the CLI also reads `.env`, `.dev.vars` and
7
+ `wrangler.*` there.
8
+
9
+ | Path | Written by | In git? | What it is |
10
+ |---|---|---|---|
11
+ | `.deco/index.ts` (or `.tsx`) | you | yes | The block map: `export default { hero, … } satisfies Blocks`. Each key is a block type. |
12
+ | `.deco/schema.gen.json` | `deco schema` | yes | Forms and validation, from the block map's types. Declares `"blocksMajor": 8`. |
13
+ | `.deco/blocks/*.json` | `deco pull`, you | hosted site: no. Bundled site: yes | Saved blocks, one file per block. |
14
+ | `.deco/pull.json` | `deco pull`, `deco push` | no | What was pulled: per block, its hash and the draft precondition. The base of `deco diff` and `deco push`. |
15
+ | `.deco/blocks.gen.ts` | `deco content` | no (generate it in `predev`/`prebuild`) | The content module, only for content without a site. |
16
+
17
+ A **hosted** site (`createCMS({ blocks, site })`) reads content from the CDN, so `.deco/blocks` is a
18
+ working copy that `deco pull` fills. A **bundled** site (`createCMS({ blocks, content })`, as in the
19
+ repo's examples and in a site still moving off v7) commits `.deco/blocks`, turns it into
20
+ `.deco/blocks.gen.ts` with `deco content`, and needs a deploy for every content change. Moving from
21
+ bundled to hosted: [serve-and-studio.md](./serve-and-studio.md), Steps 1 and 3.
22
+
23
+ ## Block names and files
24
+
25
+ A saved block's **name** is its file name, decoded: `encodeURIComponent(name) + ".json"`, directly in
26
+ `.deco/blocks/`. Studio, the CLI and the runtime share this one rule (`@decocms/blocks/protocol/keys`).
27
+
28
+ - No subfolders. A file in a subfolder is reported: `subfolders of .deco/blocks aren't read`.
29
+ - The file holds one JSON object, written as `JSON.stringify(block, null, 2)` plus a newline.
30
+ - A name can't be empty, contain `..`, a backslash or NUL, start with `.`, be `__proto__`, be a
31
+ Windows device name (`con`, `nul`, `com1`…), end in a source extension (`.ts`, `.tsx`, `.js`…), or
32
+ encode to more than 250 bytes.
33
+ - Two files that decode to the same name: one wins (the one with a `path`, then the one that took
34
+ more decoding, then the lowest file name). The others are reported as
35
+ `another spelling of "<name>"; <file> wins`. Delete the losers.
36
+ - A name of a built-in block (below) can't be a saved block.
37
+
38
+ ## Inside a block
39
+
40
+ Every block is an object with `__resolveType`. The rest are its props.
41
+
42
+ ```json
43
+ {
44
+ "__resolveType": "page",
45
+ "name": "About",
46
+ "path": "/about",
47
+ "sections": [
48
+ { "__resolveType": "Header" },
49
+ { "__resolveType": "hero", "title": "Who we are" },
50
+ { "__resolveType": "Footer" }
51
+ ]
52
+ }
53
+ ```
54
+
55
+ `__resolveType` is one of:
56
+
57
+ - **a block type**: a key of the block map (`hero`);
58
+ - **a built-in**: `lazy`, `multivariate`, `always`, `never`, `experiment`, `campaign`, `page`,
59
+ `redirect`, `redirects`, `cms-settings`, `split-traffic`, `calendar`;
60
+ - **a legacy alias**: a v7 type name the runtime maps to a v8 one (see `deco-v7-to-v8-migration`);
61
+ - **a saved block's name**: a **reference**. `{ "__resolveType": "Header" }` uses the saved block
62
+ `Header`. Other keys next to it override the saved props for this use only. This is how a header or
63
+ footer is shared by every page: change the saved block once.
64
+
65
+ `deco check` reports a `__resolveType` that is none of these as `no saved block or block type "<name>"`.
66
+ This is usually a deleted block that something still references.
67
+
68
+ ## Blocks with a fixed role
69
+
70
+ | Saved block | Type | Role |
71
+ |---|---|---|
72
+ | any name, with `path` | `page` | A routed page: `name`, `path`, `sections`, optional `seo` |
73
+ | `Redirects` (by convention) | `redirects` | The site's one list of redirect rules. Only one `redirects` block is routed: the first by name |
74
+ | `CMS` | `cms-settings` | CMS settings (telemetry, analytics). Studio edits it. Its body is inline in the release index |
75
+ | `experiments` | `split-traffic` | A/B tests. Every `experiment` rule reads it |
76
+ | `campaigns` | `calendar` | Scheduled campaigns. Every `campaign` rule reads it |
77
+
78
+ Variants (`multivariate`), rules, tests and campaigns are the `deco-variants` skill. `lazy` and
79
+ `Lazy<T>` fields are in `deco-site-authoring`. Two page paths, or two redirect `from`s, that match the
80
+ same URLs are a `deco check` error.
81
+
82
+ ## On the CDN
83
+
84
+ What `deco publish` creates, under `https://delivery.decocms.com/sites/<site>/`:
85
+
86
+ - `blocks/<hash>.json`: a block body, stored once by content hash and never changed.
87
+ - `revisions/<id>/index.json`: a release. It maps each name to its hash, plus `type`, `path` and
88
+ `refs` (the names it references), so routing and the reference walk need no body.
89
+ - `latest.json`: a copy of the current release's index, plus `previewHosts`.
90
+ - `drafts/<slug>/…`: a draft's `index.json` (the names it holds) and one file per changed block.
91
+
92
+ Revision ids look like `<12 hex>-<uuidv7>`. `deco releases` lists them. How the site reads all this:
93
+ [delivery.md](./delivery.md).