@decocms/blocks 8.10.0 → 8.11.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (163) hide show
  1. package/dist/v8/cli/index.d.ts +1 -0
  2. package/dist/v8/cli/index.d.ts.map +1 -1
  3. package/dist/v8/cli/index.js +1 -0
  4. package/dist/v8/cli/index.js.map +1 -1
  5. package/dist/v8/cli/run.d.ts +2 -0
  6. package/dist/v8/cli/run.d.ts.map +1 -1
  7. package/dist/v8/cli/run.js +30 -1
  8. package/dist/v8/cli/run.js.map +1 -1
  9. package/dist/v8/cli/skills.d.ts +25 -0
  10. package/dist/v8/cli/skills.d.ts.map +1 -0
  11. package/dist/v8/cli/skills.js +70 -0
  12. package/dist/v8/cli/skills.js.map +1 -0
  13. package/package.json +3 -2
  14. package/skills/deco-apps/SKILL.md +82 -0
  15. package/skills/deco-apps/references/algolia.md +51 -0
  16. package/skills/deco-apps/references/commerce-types.md +132 -0
  17. package/skills/deco-apps/references/instrumented-fetch.md +144 -0
  18. package/skills/deco-apps/references/magento.md +55 -0
  19. package/skills/deco-apps/references/messaging.md +76 -0
  20. package/skills/deco-apps/references/shopify.md +69 -0
  21. package/skills/deco-apps/references/vendored-loaders.md +135 -0
  22. package/skills/deco-apps/references/vtex-cookies-auth.md +146 -0
  23. package/skills/deco-apps/references/vtex.md +150 -0
  24. package/skills/deco-apps/references/wake.md +75 -0
  25. package/skills/deco-cms-schema/SKILL.md +80 -0
  26. package/skills/deco-cms-schema/references/annotations.md +147 -0
  27. package/skills/deco-cms-schema/references/content-hygiene.md +91 -0
  28. package/skills/deco-cms-schema/references/formats-and-widgets.md +112 -0
  29. package/skills/deco-cms-schema/references/shapes-that-break-the-form.md +165 -0
  30. package/skills/deco-cms-schema/references/types-to-fields.md +112 -0
  31. package/skills/deco-go-live/SKILL.md +127 -0
  32. package/skills/deco-go-live/references/content-releases.md +90 -0
  33. package/skills/deco-go-live/references/process.md +106 -0
  34. package/skills/deco-go-live/references/proxy-headers-checkout.md +139 -0
  35. package/skills/deco-go-live/references/qa-checklist-template.md +150 -0
  36. package/skills/deco-go-live/references/qa-inventory.md +120 -0
  37. package/skills/deco-go-live/references/react-spa.md +183 -0
  38. package/skills/deco-go-live/references/seo-analytics.md +114 -0
  39. package/skills/deco-go-live/references/traffic-ramp.md +87 -0
  40. package/skills/deco-go-live/references/worker-runtime.md +93 -0
  41. package/skills/deco-go-live/scripts/preflight.sh +221 -0
  42. package/skills/deco-images-media/SKILL.md +64 -0
  43. package/skills/deco-images-media/references/asset-upload.md +191 -0
  44. package/skills/deco-images-media/references/components-per-binding.md +167 -0
  45. package/skills/deco-images-media/references/providers-and-cdn.md +145 -0
  46. package/skills/deco-images-media/references/quality-and-lcp.md +93 -0
  47. package/skills/deco-images-media/references/troubleshooting.md +147 -0
  48. package/skills/deco-images-media/references/video.md +122 -0
  49. package/skills/deco-make-editable/SKILL.md +94 -0
  50. package/skills/deco-make-editable/references/a11y-and-e2e.md +104 -0
  51. package/skills/deco-make-editable/references/content-shapes.md +198 -0
  52. package/skills/deco-make-editable/references/from-figma.md +110 -0
  53. package/skills/deco-make-editable/references/i18n-fields.md +112 -0
  54. package/skills/deco-make-editable/references/inventory.md +79 -0
  55. package/skills/deco-make-editable/references/pixel-parity.md +175 -0
  56. package/skills/deco-make-editable/references/seeding-content.md +119 -0
  57. package/skills/deco-nextjs-site/SKILL.md +74 -0
  58. package/skills/deco-nextjs-site/references/caching.md +116 -0
  59. package/skills/deco-nextjs-site/references/metadata-seo.md +100 -0
  60. package/skills/deco-nextjs-site/references/proxy-and-drafts.md +177 -0
  61. package/skills/deco-nextjs-site/references/rendering.md +171 -0
  62. package/skills/deco-nextjs-site/references/setup.md +190 -0
  63. package/skills/deco-nextjs-site/references/studio-bridge.md +130 -0
  64. package/skills/deco-site-authoring/SKILL.md +75 -0
  65. package/skills/deco-site-authoring/references/lazy-blocks.md +155 -0
  66. package/skills/deco-site-authoring/references/loaders.md +192 -0
  67. package/skills/deco-site-authoring/references/pages.md +156 -0
  68. package/skills/deco-site-authoring/references/review-before-publish.md +95 -0
  69. package/skills/deco-site-authoring/references/sections.md +158 -0
  70. package/skills/deco-site-authoring/references/seo.md +116 -0
  71. package/skills/deco-site-workflow/SKILL.md +92 -0
  72. package/skills/deco-site-workflow/references/check.md +116 -0
  73. package/skills/deco-site-workflow/references/cli-reference.md +104 -0
  74. package/skills/deco-site-workflow/references/content-layout.md +93 -0
  75. package/skills/deco-site-workflow/references/content-sync.md +146 -0
  76. package/skills/deco-site-workflow/references/delivery.md +51 -0
  77. package/skills/deco-site-workflow/references/deploy.md +87 -0
  78. package/skills/deco-site-workflow/references/schema.md +173 -0
  79. package/skills/deco-site-workflow/references/serve-and-studio.md +138 -0
  80. package/skills/deco-storefront-caching/SKILL.md +67 -0
  81. package/skills/deco-storefront-caching/references/cache-keys.md +129 -0
  82. package/skills/deco-storefront-caching/references/case-study.md +82 -0
  83. package/skills/deco-storefront-caching/references/egress-traps.md +153 -0
  84. package/skills/deco-storefront-caching/references/nextjs.md +60 -0
  85. package/skills/deco-storefront-caching/references/perf-guardrails-e2e.md +123 -0
  86. package/skills/deco-storefront-caching/references/verification.md +136 -0
  87. package/skills/deco-storefront-caching/references/worker-page-cache.md +160 -0
  88. package/skills/deco-storefront-caching/scripts/html-anatomy.mjs +97 -0
  89. package/skills/deco-storefront-performance/SKILL.md +81 -0
  90. package/skills/deco-storefront-performance/references/cls-third-party.md +90 -0
  91. package/skills/deco-storefront-performance/references/hydration.md +116 -0
  92. package/skills/deco-storefront-performance/references/loaders-n-plus-1.md +107 -0
  93. package/skills/deco-storefront-performance/references/navigation-ux.md +130 -0
  94. package/skills/deco-storefront-performance/references/payload-trim.md +163 -0
  95. package/skills/deco-storefront-performance/references/render-location.md +152 -0
  96. package/skills/deco-storefront-performance/references/request-dedupe.md +147 -0
  97. package/skills/deco-storefront-performance/references/trace-reading.md +79 -0
  98. package/skills/deco-storefront-performance/references/worker-memory.md +176 -0
  99. package/skills/deco-tanstack-site/SKILL.md +68 -0
  100. package/skills/deco-tanstack-site/references/document-and-security.md +155 -0
  101. package/skills/deco-tanstack-site/references/router-and-navigation.md +137 -0
  102. package/skills/deco-tanstack-site/references/routes-and-pages.md +183 -0
  103. package/skills/deco-tanstack-site/references/server-functions.md +123 -0
  104. package/skills/deco-tanstack-site/references/setup.md +153 -0
  105. package/skills/deco-tanstack-site/references/worker-entry.md +152 -0
  106. package/skills/deco-v7-to-v8-migration/SKILL.md +122 -0
  107. package/skills/deco-v7-to-v8-migration/references/caching-and-privacy.md +10 -0
  108. package/skills/deco-v7-to-v8-migration/references/content.md +25 -0
  109. package/skills/deco-v7-to-v8-migration/references/editor-forms.md +27 -0
  110. package/skills/deco-v7-to-v8-migration/references/faststore.md +40 -0
  111. package/skills/deco-v7-to-v8-migration/references/framework-code.md +53 -0
  112. package/skills/deco-v7-to-v8-migration/references/hosted-releases.md +16 -0
  113. package/skills/deco-v7-to-v8-migration/references/import-map.md +81 -0
  114. package/skills/deco-v7-to-v8-migration/references/legacy-names.md +33 -0
  115. package/skills/deco-v7-to-v8-migration/references/manual-steps.md +10 -0
  116. package/skills/deco-v7-to-v8-migration/references/native-apps.md +43 -0
  117. package/skills/deco-v7-to-v8-migration/references/nextjs.md +19 -0
  118. package/skills/deco-v7-to-v8-migration/references/parity.md +66 -0
  119. package/skills/deco-v7-to-v8-migration/references/rendering.md +13 -0
  120. package/skills/deco-v7-to-v8-migration/references/running-the-script.md +29 -0
  121. package/skills/deco-v7-to-v8-migration/references/script-steps.md +13 -0
  122. package/skills/deco-v7-to-v8-migration/references/server-functions.md +15 -0
  123. package/skills/deco-v7-to-v8-migration/references/sibling-port.md +11 -0
  124. package/skills/deco-v7-to-v8-migration/references/site-code.md +15 -0
  125. package/skills/deco-v7-to-v8-migration/references/telemetry.md +10 -0
  126. package/skills/deco-v7-to-v8-migration/references/verify.md +20 -0
  127. package/skills/deco-v7-to-v8-migration/scripts/apps.ts +297 -0
  128. package/skills/deco-v7-to-v8-migration/scripts/asyncRendering.ts +73 -0
  129. package/skills/deco-v7-to-v8-migration/scripts/blockMap.ts +584 -0
  130. package/skills/deco-v7-to-v8-migration/scripts/ciSchemaCheck.ts +145 -0
  131. package/skills/deco-v7-to-v8-migration/scripts/compat.ts +357 -0
  132. package/skills/deco-v7-to-v8-migration/scripts/content.ts +121 -0
  133. package/skills/deco-v7-to-v8-migration/scripts/experiments.ts +81 -0
  134. package/skills/deco-v7-to-v8-migration/scripts/framework.ts +61 -0
  135. package/skills/deco-v7-to-v8-migration/scripts/imageCopy.ts +276 -0
  136. package/skills/deco-v7-to-v8-migration/scripts/imageModule.ts +285 -0
  137. package/skills/deco-v7-to-v8-migration/scripts/imports.ts +942 -0
  138. package/skills/deco-v7-to-v8-migration/scripts/invoke.ts +624 -0
  139. package/skills/deco-v7-to-v8-migration/scripts/legacyNames.ts +45 -0
  140. package/skills/deco-v7-to-v8-migration/scripts/main.ts +59 -0
  141. package/skills/deco-v7-to-v8-migration/scripts/matchers.ts +41 -0
  142. package/skills/deco-v7-to-v8-migration/scripts/migrate.ts +176 -0
  143. package/skills/deco-v7-to-v8-migration/scripts/redirects.ts +455 -0
  144. package/skills/deco-v7-to-v8-migration/scripts/report.ts +50 -0
  145. package/skills/deco-v7-to-v8-migration/scripts/scaffold.ts +1119 -0
  146. package/skills/deco-v7-to-v8-migration/scripts/secrets.ts +35 -0
  147. package/skills/deco-v7-to-v8-migration/scripts/sectionLoaders.ts +216 -0
  148. package/skills/deco-v7-to-v8-migration/scripts/siteSettings.ts +261 -0
  149. package/skills/deco-v7-to-v8-migration/scripts/stubs.ts +388 -0
  150. package/skills/deco-v7-to-v8-migration/scripts/tsconfig.json +7 -0
  151. package/skills/deco-v7-to-v8-migration/scripts/vendor.ts +249 -0
  152. package/skills/deco-v7-to-v8-migration/scripts/vtexInvoke.ts +240 -0
  153. package/skills/deco-v7-to-v8-migration/scripts/walk.ts +30 -0
  154. package/skills/deco-variants/SKILL.md +57 -0
  155. package/skills/deco-variants/references/caching-variants.md +63 -0
  156. package/skills/deco-variants/references/custom-matchers.md +83 -0
  157. package/skills/deco-variants/references/draft-preview.md +59 -0
  158. package/skills/deco-variants/references/experiments-and-campaigns.md +104 -0
  159. package/skills/deco-variants/references/multivariate.md +85 -0
  160. package/skills/deco-variants/references/v7-matchers.md +71 -0
  161. package/src/v8/cli/index.ts +1 -0
  162. package/src/v8/cli/run.ts +35 -1
  163. package/src/v8/cli/skills.ts +91 -0
@@ -0,0 +1,165 @@
1
+ # Shapes that break the form
2
+
3
+ These shapes compile, pass review and generate a schema. They fail in front
4
+ of an editor, or in production on content an editor saved.
5
+
6
+ ## Nest a one-to-many relation. Never link it by a typed key.
7
+
8
+ If an item belongs to exactly one group, the items live inside the group.
9
+
10
+ ```ts
11
+ // Good: a column owns its links
12
+ /** @titleBy heading */
13
+ export interface FooterColumn {
14
+ /** @title Heading */
15
+ heading: string;
16
+ /** @title Links */
17
+ links: FooterLink[];
18
+ }
19
+
20
+ // Bad: two sibling arrays joined by a key the editor types from memory
21
+ tabs: { label: string; key: string }[];
22
+ cards: { caption: string; tabKey?: string }[];
23
+ ```
24
+
25
+ The bad shape fails three ways. The typed key has no autocomplete. A
26
+ mismatched key makes a card vanish from its tab with no visible error. And the
27
+ two arrays have to be kept in sync by hand. Use sibling arrays plus a key only
28
+ when the relation is really many-to-many, which is rare in editorial content.
29
+
30
+ ## Two sibling fields with the same anonymous inline type
31
+
32
+ ```ts
33
+ // Bad
34
+ collection?: { collectionId: string } | { skuId: string };
35
+ collection2?: { collectionId: string } | { skuId: string };
36
+ ```
37
+
38
+ Both fields produce identical inline schemas (the generator gives a shared
39
+ `$ref` only to named types). On the v7 Studio this shape made both fields
40
+ share one form state: typing into the first mirrored into the second, and it
41
+ shipped on live content. That bug has not been checked on the v8 Studio.
42
+
43
+ Either way, numbered sibling slots are the wrong shape. Use a list, so each
44
+ entry is its own node:
45
+
46
+ ```ts
47
+ /** @titleBy label */
48
+ export interface Companion {
49
+ /** @title Label */
50
+ label: string;
51
+ /** @title Collection ID */
52
+ collectionId?: string;
53
+ }
54
+
55
+ interface Props {
56
+ /** @title Companion products */
57
+ products?: Companion[];
58
+ }
59
+ ```
60
+
61
+ If saved content still uses the old fields, keep them with `@hide @deprecated`
62
+ until the content is migrated. See [content-hygiene.md](./content-hygiene.md).
63
+
64
+ ## Arrays from content can hold holes
65
+
66
+ The type says `T[]`. At runtime an entry can still be:
67
+
68
+ - `null`, saved in content, or returned by a block in that slot;
69
+ - an object with fields missing: an empty row an editor saved, or content
70
+ written before a field was added.
71
+
72
+ In v8, when a block inside an array resolves to `undefined` (for
73
+ example a `multivariate` with no matching rule), the resolver drops that entry
74
+ and the array gets shorter. `null` values are still kept.
75
+
76
+ `deco check` reports a `null` where the item type is not nullable, and missing
77
+ required fields. Run it, but do not count on it: content changes after deploy.
78
+
79
+ Compact once, where the data enters the component, before any `.map`,
80
+ `.filter` or `.find`:
81
+
82
+ ```ts
83
+ const isPresent = <T>(value: T | null | undefined): value is T => value != null;
84
+ const links = (props.links ?? []).filter(isPresent);
85
+ ```
86
+
87
+ Prefer a type guard like this over `.filter(Boolean)`. `Boolean` works at
88
+ runtime but does not narrow the type, so you cast afterwards. On a list of
89
+ primitives it also drops legitimate `0`, `""` and `false`.
90
+
91
+ This matters most in a section on every page (header, footer). One unhandled
92
+ hole there breaks every page, not one section.
93
+
94
+ How multivariate blocks are written and previewed is in the `deco-variants`
95
+ skill.
96
+
97
+ ## Variants: a union of types, not an enum plus dead fields
98
+
99
+ When a field can take really different structures, model it as a union of
100
+ named types, each with a `@title`. The editor picks a member and sees only
101
+ its fields, instead of an `aspectRatio` box that does nothing under every
102
+ other choice. See [types-to-fields.md](./types-to-fields.md) for how members
103
+ get their labels.
104
+
105
+ ```ts
106
+ /** @title Wide */
107
+ export interface WideLayout {
108
+ /** @hide */
109
+ kind: "wide";
110
+ /** @title Aspect ratio */
111
+ aspectRatio: string;
112
+ }
113
+
114
+ /** @title Contained */
115
+ export interface ContainedLayout {
116
+ // Nothing to set: this is the default crop. The literal keeps the type
117
+ // from being empty (see below).
118
+ /** @hide */
119
+ kind: "contained";
120
+ }
121
+
122
+ interface Props {
123
+ /** @title Layout */
124
+ layout?: WideLayout | ContainedLayout;
125
+ }
126
+ ```
127
+
128
+ Details that keep this safe on a section that already has content:
129
+
130
+ - **Do not leave a member empty.** In v8 an object field also offers every
131
+ block whose return type fits it (TypeScript assignability, see
132
+ [types-to-fields.md](./types-to-fields.md)). An empty interface accepts any
133
+ object, so every block that returns an object would show up as a choice.
134
+ A single string literal field fixes it. The generator gives a literal an
135
+ equal `default`, so the editor writes it into new entries, and a hidden
136
+ field with a default stays required.
137
+ - **Switch on the literal** at runtime (`layout?.kind === "wide"`), and treat
138
+ any other value as the default member.
139
+ - **Adding `kind` to a union that already has content** makes old entries
140
+ fail `deco check` (a required field is missing) until each saved value gets
141
+ its `kind`. Run `deco check` and fix the content in the same change.
142
+ - **Keep the prop optional.** Content saved before the union existed has no
143
+ value, and `deco check` would report a missing required field.
144
+ - **Title every member** in the editor's language.
145
+
146
+ When each member of a string union needs a matching value, pair it with a
147
+ `Record<Union, …>`. The compiler then refuses a new option without its
148
+ counterpart.
149
+
150
+ ```ts
151
+ type Tone = "light" | "dark";
152
+ const TONE_CLASS: Record<Tone, string> = { light: "bg-white", dark: "bg-black" };
153
+ ```
154
+
155
+ ## Free text is untrusted input
156
+
157
+ A text field is the one place TypeScript cannot help: the editor can type
158
+ anything. If the code parses it (a number, a JSON value, a facet key, a URL),
159
+ guard the parse at the consumer and fall back to a default. On a section
160
+ that renders on every page or on the home page, a bad value breaks the whole
161
+ page. One incident came from an editor typing a platform-specific facet key
162
+ into a free-text field.
163
+
164
+ If the value has a closed set of choices, make it a select instead
165
+ (a literal union or `@options`).
@@ -0,0 +1,112 @@
1
+ # What each TypeScript shape becomes
2
+
3
+ `typeToJsonSchema` in `packages/blocks/src/v8/cli/schema/typeToSchema.ts`
4
+ turns the props type into JSON Schema; Studio draws the form from that. When a
5
+ field comes out as the wrong kind, find its shape here, then read the block's
6
+ entry in `.deco/schema.gen.json` to confirm.
7
+
8
+ ## Primitives and selects
9
+
10
+ | Type | Field |
11
+ |---|---|
12
+ | `string` | Text (or a widget, see [formats-and-widgets.md](./formats-and-widgets.md)) |
13
+ | `number` | Number |
14
+ | `boolean`, `true \| false` | Boolean |
15
+ | `"a" \| "b"`, a string `enum` | Select: `type: "string"` with `enum`, in the order the type spells them |
16
+ | `1 \| 2 \| 3` | Number select |
17
+ | A single string literal, `kind: "image"` | `const` with an equal `default`, so new entries get the value |
18
+ | `T \| null`, `T \| undefined` | `T` with `nullable: true` |
19
+ | `prop?: T` | `T`, left out of `required` |
20
+ | `string & { brand }` | The primitive (`string`) |
21
+ | `any`, `unknown` | An empty schema: no usable field |
22
+
23
+ A literal union, written inline or through a type alias, lists its choices
24
+ in the order you wrote them, even when the checker met the literals in
25
+ another order.
26
+
27
+ ## Objects, lists and maps
28
+
29
+ | Type | Field |
30
+ |---|---|
31
+ | An interface or object type | A group of fields, in declaration order |
32
+ | `T[]` | A list of `T` |
33
+ | `A & B` (objects) | One group with the fields of both |
34
+ | `Record<string, T>` | A map: `additionalProperties` of `T` |
35
+ | `Record<string, any>` | A free-form map. It does not offer blocks |
36
+ | A type that contains itself (`Link { submenu?: Link[] }`) | A `$ref` to its shared definition |
37
+
38
+ ## Unions of objects: the variant picker
39
+
40
+ `A | B` where the members are objects becomes `anyOf`: the editor picks one
41
+ member and fills in that member's fields. Each member's label comes from, in
42
+ order:
43
+
44
+ 1. `@title` on the member's interface or type alias;
45
+ 2. the type's name (`WideLayout`);
46
+ 3. the value of the first literal property (`kind: "wide"` → "wide").
47
+
48
+ An anonymous member with none of these has no label. Give every member a
49
+ `@title` in the editor's language: the picker shows those strings.
50
+
51
+ A union that mixes primitives and objects (`string | Banner`) is also an
52
+ `anyOf`, of a text field and a group.
53
+
54
+ ## Sections, lazy values and blocks
55
+
56
+ | Type | Field |
57
+ |---|---|
58
+ | `ReactNode`, `ReactElement`, `JSX.Element` | A section picker |
59
+ | `ReactNode[]` | A list of sections |
60
+ | A render descriptor (`{ component; props }`) | A section picker |
61
+ | v7's opaque `Section` / `Section[]` (`type Section = any`) | A section picker / list |
62
+ | `Lazy<T>` | A `lazy` block whose `value` has the form of `T` |
63
+
64
+ An object or list field that a block can fill gets three kinds of choice:
65
+ a saved block ("Select from saved"), "Inline data" (the plain form), and every
66
+ block whose function's awaited return type fits the field. Sections and
67
+ matchers are never offered here. "Fits" is TypeScript assignability, not the
68
+ type's name. So a `products: Product[]` field offers every loader that returns
69
+ `Product[]`. Two exceptions:
70
+
71
+ - A type whose fields are all optional (`{ size?: number }`) would accept
72
+ almost any object. For such a type a block must return the same named type.
73
+ - A `Record<string, any>` field offers no blocks, because every block would
74
+ fit.
75
+
76
+ How to write lazy blocks and sections is in the `deco-site-authoring` skill.
77
+
78
+ ## Props that never reach the form
79
+
80
+ These are skipped:
81
+
82
+ - methods and other function-typed props (but `Lazy<T>` is a field);
83
+ - `__resolveType`, any name starting with `$`, and `@type`;
84
+ - React internals: `ref`, `then`, `catch`, `finally`, `$$typeof`, `_owner`,
85
+ `_store`;
86
+ - symbol keys;
87
+ - anything tagged `@ignore`.
88
+
89
+ Names starting with `_` are kept: `__title` labels a list entry, `_id` is
90
+ site data.
91
+
92
+ Platform types from the TypeScript lib (`URL`, `URLSearchParams`, `Request`,
93
+ `Response`, `Headers`, `AbortSignal`, `ReadableStream`, `WritableStream`,
94
+ `Blob`, `File`, `FormData`) become a hidden object. Nobody edits them in a
95
+ form.
96
+
97
+ ## `required`
98
+
99
+ A prop that is not optional is in `required`, unless it is hidden with no
100
+ default. `deco check` reports saved content missing a required field, and a
101
+ `null` where the type is not nullable. If old content may lack the field, make
102
+ it optional or give it a `@default`.
103
+
104
+ ## Whole-block warnings
105
+
106
+ `deco schema` warns, and the form is empty, when:
107
+
108
+ - the block's props are typed `any`;
109
+ - its first parameter is not an object (for example a string).
110
+
111
+ It also warns when a block returns `any`: that block is then not offered for
112
+ any field.
@@ -0,0 +1,127 @@
1
+ ---
2
+ name: deco-go-live
3
+ description: "Go-live and the first 72 hours for a site on @decocms/blocks 8 (mainly TanStack Start behind createDecoWorker from @decocms/tanstack/worker). Covers code and content freeze, the last content import as a draft (deco push --draft, deco check, deco publish), how releases reach the site from the CDN and how to roll back traffic, code and content (deco releases, Studio's make-current), the traffic ramp with abTestingRoutes from @decocms/compat-v7/tanstack/worker, Worker runtime limits (128 MB, shared state, deadlines, telemetry), go-live cache checks, proxied checkout headers (COOP, 304 and bfcache), React/SPA leftovers from Fresh ports, SEO, redirects and analytics parity, a read-only preflight script, and a QA checklist built from an inventory of the site's blocks and routes. Load it before a cutover, after a migration or a framework upgrade, to build a QA pass, or to chase a regression right after launch. Assumes the site already builds and renders."
4
+ ---
5
+
6
+ # Go-live check for a v8 site
7
+
8
+ Most items below come from a real incident on a store that already went live. Walk
9
+ it on the candidate (and on the real host) before the first byte of
10
+ production traffic, again on cutover day, and once more 24 to 72 hours later.
11
+ It is a double check, not a setup guide: wiring is in **deco-tanstack-site**
12
+ and **deco-nextjs-site**, the CLI flow in **deco-site-workflow**.
13
+
14
+ - 🔴 **Blocks go-live**: data leak, site down, checkout or revenue loss.
15
+ - 🟡 **Fix before ramping above 0%**: cache, SEO, analytics, performance.
16
+ - 🟢 **Watch after go-live**: monitor, compare with the old site.
17
+ - 🧪 needs a browser and a person looking at the result.
18
+
19
+ Record PASS / FAIL / N/A for every line in the go-live ticket. "Didn't check"
20
+ is not N/A.
21
+
22
+ ## When to load what
23
+
24
+ | Reference | Load it when |
25
+ |---|---|
26
+ | [`references/process.md`](./references/process.md) | Planning the freeze, the last content import, the CMS pass, cutover day or the first 72 hours |
27
+ | [`references/content-releases.md`](./references/content-releases.md) | Checking how a publish reaches the site, what it doesn't reach, or writing the rollback plan |
28
+ | [`references/traffic-ramp.md`](./references/traffic-ramp.md) | Splitting the production host between the new site and the old origin |
29
+ | [`references/worker-runtime.md`](./references/worker-runtime.md) | Memory errors, 524s, data shown to the wrong user, missing telemetry |
30
+ | [`references/proxy-headers-checkout.md`](./references/proxy-headers-checkout.md) | A proxied checkout, header differences with the old site, real-host-only bugs, redirect loops |
31
+ | [`references/react-spa.md`](./references/react-spa.md) | Something works after F5 but not after a click, hydration errors, stale chunks |
32
+ | [`references/seo-analytics.md`](./references/seo-analytics.md) | Tag-manager timing, indexing, soft 404s, the redirect sweep, sitemaps, search behavior |
33
+ | [`references/qa-inventory.md`](./references/qa-inventory.md) | Building a QA pass: list the blocks, routes, interactions and integrations first |
34
+ | [`references/qa-checklist-template.md`](./references/qa-checklist-template.md) | Filling the QA checklist from that inventory |
35
+
36
+ Cache keys, profiles and hit-rate work are in **deco-storefront-caching**;
37
+ render and upstream performance in **deco-storefront-performance**; parity with
38
+ a v7 site in **deco-v7-to-v8-migration**.
39
+
40
+ ## Quick start
41
+
42
+ ```bash
43
+ bash <path-to-this-skill>/scripts/preflight.sh \
44
+ <site-repo> https://<candidate-host> https://<old-site-host>
45
+ deco schema --check && deco check
46
+ ```
47
+
48
+ The script is read-only (greps and curls). It only catches what is greppable
49
+ or curl-able.
50
+
51
+ ## 1. Process (→ [process.md](./references/process.md))
52
+
53
+ - [ ] 🔴 **Code freeze on the old repo** with a date and a recorded `FREEZE_SHA`; every commit since the migration cut reconciled.
54
+ - [ ] 🔴 **Content freeze on the old CMS**; last import after the last edit, pushed as a draft, `deco check --draft=<name>` clean, then `deco publish`.
55
+ - [ ] 🔴 **Schemas match production**: same props and defaults; five-criteria parity.
56
+ - [ ] 🟡 **CMS pass** with the editors before go-live; draft preview works on their hosts.
57
+ - [ ] 🟡 **Inventory** of integrations not ported and of A/B tests whose variant code was never ported.
58
+
59
+ ## 2. Content and rollback (→ [content-releases.md](./references/content-releases.md))
60
+
61
+ - [ ] 🔴 `createCMS({ site })` on production; a cold start renders; no direct imports of `.deco/blocks/*.json` that a publish can't reach.
62
+ - [ ] 🔴 `"blocksMajor": 8` in `.deco/schema.gen.json`; `deco schema push` runs on production deploys.
63
+ - [ ] 🔴 **Rollback written and rehearsed** for traffic, code and content.
64
+ - [ ] 🟡 The content team knows a publish takes about a minute to show.
65
+
66
+ ## 3. Traffic ramp (→ [traffic-ramp.md](./references/traffic-ramp.md))
67
+
68
+ - [ ] 🔴 At 0%, the **fallback bucket** works through the worker: the worker 404s `/live/*` and `/deco/*` before the split, so old pages that call them break.
69
+ - [ ] 🔴 `shouldBypassAB` returns `true` for routes only the new site has.
70
+ - [ ] 🟡 Both buckets smoke-tested with `?_deco_bucket=worker|fallback`, including existing proxies.
71
+
72
+ ## 4. Worker runtime (→ [worker-runtime.md](./references/worker-runtime.md))
73
+
74
+ - [ ] 🔴 **No per-user state at module scope** (`new QueryClient()` outside `getRouter`, module `Map`s with user data).
75
+ - [ ] 🔴 **Memory under ~80% of 128 MB** in a load test; big responses streamed; no content in the bundle.
76
+ - [ ] 🟡 **Every upstream await has a deadline**; shared promises have one too.
77
+ - [ ] 🟡 Observability and CMS telemetry on; `service.version` set to the commit.
78
+ - [ ] 🟢 Memory compared after every `@decocms/*` bump.
79
+
80
+ ## 5. Cache (→ **deco-storefront-caching**)
81
+
82
+ - [ ] 🔴 **A signed-in shopper never gets a stored anonymous page**; nothing per-user is stored.
83
+ - [ ] 🟡 Anonymous pages set no cookie except the first-visit `deco_segment`, and the second request is `X-Cache: HIT`.
84
+ - [ ] 🟡 The cache key drops the paid-media parameters your traffic carries.
85
+ - [ ] 🟡 A failed loader marks the page degraded (`x-deco-degraded`) instead of caching "not found".
86
+
87
+ ## 6. Proxy, headers, checkout (→ [proxy-headers-checkout.md](./references/proxy-headers-checkout.md))
88
+
89
+ - [ ] 🔴 **Header diff old × new** on store pages and the proxied checkout; the worker's default COOP overridden where the old site sent none.
90
+ - [ ] 🔴 **The proxied checkout never answers 304** from a stored copy; 🧪 bfcache tested on a deployed preview.
91
+ - [ ] 🔴 Third-party checkout scripts **byte-compared** with the old site.
92
+ - [ ] 🔴 **Real-host-only bugs** checked with the production `Host`.
93
+ - [ ] 🟡 No self-redirect loops on encoded paths.
94
+
95
+ ## 7. React / SPA (→ [react-spa.md](./references/react-spa.md))
96
+
97
+ - [ ] 🔴 🧪 **Cart write then immediate navigation** to checkout keeps the change.
98
+ - [ ] 🔴 Fresh leftovers grep is clean (`window.STOREFRONT`, `hx-*`, `value=` without `onChange`).
99
+ - [ ] 🟡 🧪 Every inline-script component works when reached by **SPA click**.
100
+ - [ ] 🟡 🧪 Product → product by SPA: gallery keyed, no React #310; hook-order lint on.
101
+ - [ ] 🟡 🧪 Zero React #418 on mobile with the tag manager on.
102
+ - [ ] 🟡 Stale-chunk reload guard; intent-preload payload measured.
103
+ - [ ] 🟢 Old service worker unregistered by a self-unregistering `sw.js`.
104
+
105
+ ## 8. SEO, analytics, search (→ [seo-analytics.md](./references/seo-analytics.md))
106
+
107
+ - [ ] 🔴 **Tag manager loads from `<head>` without a gesture gate**; checkout cookies match the old site.
108
+ - [ ] 🔴 On the real host at 0%: **no `noindex`, no `Disallow: /`**; real 404 status codes.
109
+ - [ ] 🟡 Every analytics vendor mounted and receiving events the next day.
110
+ - [ ] 🟡 No duplicate `from` in the redirects block (`deco check` does not catch them), and a **sweep of every rule** against the old site.
111
+ - [ ] 🟡 Sitemap served by a real route and streamed.
112
+ - [ ] 🟡 Facet change resets `page`; autocomplete uses the typed term.
113
+
114
+ ## 9. Cutover day and after (→ [process.md](./references/process.md#cutover-day))
115
+
116
+ - [ ] 🔴 Deploy freeze during the window.
117
+ - [ ] 🔴 Split config before the route; smoke with each bucket forced.
118
+ - [ ] 🟡 Cache warmed by fetching **pages** with mobile and desktop user agents.
119
+ - [ ] 🟡 Traffic ladder with written gates.
120
+ - [ ] 🟢 Compare with the **same hour the day before**; keep removed endpoints alive for the HTML cache TTL; keep porting old-repo drift.
121
+
122
+ ## Related
123
+
124
+ - **deco-site-workflow**: `deco pull`, `push`, `drafts`, `publish`, `releases`, `schema push`.
125
+ - **deco-variants**: tests and campaigns, preview links with `__test` / `__campaign`.
126
+ - **ecommerce-qa** (decocms/storefront-skills): end-to-end purchase tests with `@decocms/qa`.
127
+ - **tools-reconcile-snapshot** (decocms/migrations; planned to move to the blocks 7.x branch as **deco-reconcile-snapshot**): old-repo drift since the cut.
@@ -0,0 +1,90 @@
1
+ # Content releases, publish timing and rollback
2
+
3
+ On v8, published content is a **release**: a revision Studio writes to the
4
+ delivery CDN. The worker does not bundle it and does not keep it in a KV
5
+ namespace. This file covers what to check about that path before go-live, and
6
+ how to roll back each layer.
7
+
8
+ ## How a release reaches the site
9
+
10
+ - `createCMS({ blocks, site })` reads the site's latest release from the delivery CDN at runtime. With `site`, passing `content` too is an error: content never comes from the bundle.
11
+ - The first client of an isolate loads the release index (10 s per fetch). Until a load succeeds, reads fail with a `ContentUnavailableError` cause. Test a cold start: the first request after a deploy must render.
12
+ - Each isolate checks for a newer release every `interval` (default and minimum 60 000 ms, plus or minus up to 10 s), at an idle moment, in the background. So a publish shows up within about a minute per isolate, and the first request after the interval may still render the previous release. Tell the content team; the old stack may have felt instant.
13
+ - A draft request checks for the latest release first (once per request), so a draft preview builds on what was published a moment ago.
14
+ - Block bodies are fetched by hash and kept in a per-isolate LRU bounded at 32 MB of JSON text. A hash always means the same body, so nothing there is invalidated.
15
+ - Without `site`, content is the module `deco content` writes (`.deco/blocks.gen.ts`), bundled into the worker, and every content change needs a deploy. Large content in the bundle costs memory on every isolate ([worker-runtime.md](./worker-runtime.md#memory-128-mb-per-isolate)).
16
+
17
+ Setting `site` and `token` (and the `DECO_SITE` / `DECO_SITE_TOKEN` values a
18
+ site passes to them) is covered in **deco-site-workflow** and, for a v7 site,
19
+ in **deco-v7-to-v8-migration**.
20
+
21
+ ### What a publish does not reach
22
+
23
+ A publish changes only what reads through the CMS client. Before go-live, grep
24
+ for content that bypasses it:
25
+
26
+ ```bash
27
+ grep -rnE "\.deco/blocks/[^\"']+\.json" src # direct JSON imports: frozen at the last deploy
28
+ grep -rn "blocks.gen" src # the bundled content module
29
+ grep -rln "readFileSync\|readdirSync" scripts 2>/dev/null | xargs grep -ln "\.deco/blocks" 2>/dev/null # build-time reads
30
+ ```
31
+
32
+ Route each through the client, or write down that it needs a deploy.
33
+
34
+ ### Page cache and releases
35
+
36
+ `cacheVersion(cms, buildHash, page.url)` from `@decocms/tanstack/worker` is
37
+ `<build>.<content revision>`, so a deploy or a publish moves the site's page
38
+ cache to new keys at once. A preview (`?__draft=`, `off` included, or the
39
+ draft cookie) never reaches `pageCache`, and an old release is never stored.
40
+ Cache keys and profiles are in **deco-storefront-caching**.
41
+
42
+ ## Check the release before you publish
43
+
44
+ ```bash
45
+ deco check # production against the local .deco/schema.gen.json
46
+ deco check --draft=<name> # a draft
47
+ deco check --revision=<id> # a published revision (ids from deco releases)
48
+ ```
49
+
50
+ `deco check` validates content against the local schema. Run it on the
51
+ commit you are about to deploy: a deploy that changes a section's props can
52
+ reject content that is already live.
53
+
54
+ The schema the site editor draws forms from must be the deployed one: `deco
55
+ schema push` on every production deploy (**deco-site-workflow**). The
56
+ committed `.deco/schema.gen.json` must carry `"blocksMajor": 8`, or `deco check`
57
+ fails and the editor treats the site as v7.
58
+
59
+ ## Redirects are content
60
+
61
+ The worker answers the redirects block (the saved block of type `redirects`)
62
+ before any route, including before an A/B split. They ship with a publish, not
63
+ with a deploy. Their rules and the sweep against the old site are in
64
+ [seo-analytics.md](./seo-analytics.md#redirect-sweep).
65
+
66
+ ## Rollback
67
+
68
+ Write down one path per layer before cutover, and rehearse each on the
69
+ candidate.
70
+
71
+ | Layer | How | Check |
72
+ |---|---|---|
73
+ | Traffic | Set the split ratio back to 0 in the host's KV entry, or remove the route ([traffic-ramp.md](./traffic-ramp.md)) | `x-deco-bucket: fallback` on a fresh visitor |
74
+ | Content | In Studio, make an earlier release current. It becomes a new revision with the next sequence, and isolates adopt it within the interval | `deco releases` lists it as `rollback to <id>`, marked `current` |
75
+ | Code | Roll back the Worker deployment (the Cloudflare dashboard's Deployments, as in this repo's `docs/runbooks/http-error-spike.md`) | `service.version` in telemetry flips back. It is `unknown` unless the site sets it in `telemetry.resource` (e.g. to the commit): set it before go-live |
76
+
77
+ A code rollback keeps the content that is live now. Before rolling code back,
78
+ check out the older commit and run `deco check`: if live content no longer
79
+ fits the older schema, roll content back first, or the older code renders it
80
+ wrong.
81
+
82
+ ## Telemetry
83
+
84
+ With `token` (or a `telemetry.endpoint`), the worker records
85
+ `http.server.request.duration` for every request, labelled with the page
86
+ template, method, status class, cache decision (`HIT`, `MISS`, `BYPASS`,
87
+ `DRAFT`) and device. Upstream calls made through `createInstrumentedFetch`
88
+ (`@decocms/blocks/fetch`) record `http.client.request.duration` per provider.
89
+ Without either, nothing is sent: confirm it is on before the ramp, or you
90
+ compare buckets blind.
@@ -0,0 +1,106 @@
1
+ # Process: freeze, parity, cutover, first 72 hours
2
+
3
+ Most go-live pain was not code. It was code or content changing on the old
4
+ site while the new one was being validated, or a cutover step done in the
5
+ wrong order.
6
+
7
+ ## Code freeze and reconcile
8
+
9
+ **What happened:** on one store the team kept shipping to the old repo after
10
+ the candidate was validated, and at cutover the new site was out of date. On
11
+ another there was no freeze for a month, and 4 to 5 features had to be pulled
12
+ out of commit history. After go-live, three old-repo PRs and an A/B variant
13
+ that was never ported still had to be ported.
14
+
15
+ - [ ] Agree a **freeze date** in writing: from that day until go-live, no code merges on the old repo.
16
+ - [ ] Record `FREEZE_SHA`: the old repo's `main` at the freeze.
17
+ - [ ] Reconcile every old-repo commit from the migration cut to `FREEZE_SHA` (the **tools-reconcile-snapshot** skill in decocms/migrations gives one diff per changed file). Port by hand. Skip generated files and saved content: content moves separately (below).
18
+ - [ ] After go-live, keep watching the old repo. Anything merged there is a port ticket.
19
+
20
+ ```bash
21
+ git -C <old-repo> log --oneline <CUT_SHA>..origin/main -- . ':!.deco/blocks' ':!static'
22
+ ```
23
+
24
+ ## Content freeze and the last import
25
+
26
+ On v8 the content lives in Studio releases, served from the delivery CDN.
27
+ The old CMS keeps changing until someone stops it. An import done at 07:00
28
+ misses an edit published at 08:00.
29
+
30
+ - [ ] Agree a **content freeze** on the old CMS, and do the last import after the content team's last publish.
31
+ - [ ] Bring the imported blocks in as a draft, check it, then publish it:
32
+
33
+ ```bash
34
+ deco push --draft=cutover # saves the blocks changed since the pull; prints the preview link
35
+ deco check --draft=cutover # the draft against .deco/schema.gen.json: 0 errors
36
+ deco publish --draft=cutover --message="cutover import"
37
+ deco releases # the new revision is "current"
38
+ ```
39
+
40
+ - [ ] After go-live, the old CMS is read-only. A one-way sync that keeps running overwrites edits made in Studio. On one store a leftover sync overwrote 21 blocks edited in the new CMS.
41
+ - [ ] Fix content problems **in code at the seam** (a guard, a default, a cap) when the next import would bring the bad value back.
42
+
43
+ `deco push`, `pull`, `diff` and drafts are covered in **deco-site-workflow**.
44
+
45
+ ## Structural parity (five criteria)
46
+
47
+ AI ports tend to rebuild components their own way. On one store, schemas were
48
+ changed, then the content import broke pages, because a component read the
49
+ same props differently on each side. Rule: **content stays the same and
50
+ components keep the interface they had in production.**
51
+
52
+ 1. **HTML**: same landmarks, headings, `rel` and prefetch attributes, and the `data-*` attributes tags read.
53
+ 2. **Schema**: same props, names, types and defaults. `deco schema`, then compare the Studio form with the old one (**deco-cms-schema**).
54
+ 3. **Wiring**: every prop reaches the DOM; every `__resolveType` in `.deco/blocks` exists in the block map. `deco check` reports unknown types and broken references.
55
+ 4. **Behavior**: open and close, add to cart, filters, forms, on desktop and mobile.
56
+ 5. **Visual**: spacing, layout, icons, animation (pixel diff per section; **deco-make-editable** has the method).
57
+
58
+ For a v7 site, the parity harness and the list of approved differences are in
59
+ **deco-v7-to-v8-migration**.
60
+
61
+ ## CMS pass
62
+
63
+ One hour with the people who edit the site, **before** go-live. The goal is
64
+ not training. Confirm that the props they edit are editable, the blocks they
65
+ pick still exist, and a draft preview works on the hosts they use (`deco
66
+ drafts url <name>` prints a draft's link).
67
+
68
+ ## Inventory of what was not ported
69
+
70
+ - [ ] List integrations disabled or stubbed in the port (back-in-stock, try-on, chat, reviews) and get sign-off.
71
+ - [ ] List the A/B tests running on the old site (testing tools, search vendors). A variant whose code exists only on the old site must be ported or paused.
72
+ - [ ] Grep the old repo for inline behaviors (`hx-on:` handlers, inline scripts). Each one must exist in the port. On one store an unported `hx-on:click` left an empty box on every page.
73
+
74
+ ## Cutover day
75
+
76
+ The safe pattern is a traffic split on the production host, not a switch of
77
+ DNS: the new worker takes every request and sends a share of visitors to the
78
+ old origin. Start at 0%, test the new bucket on the real domain, then ramp.
79
+ The v8 handler for this, and its traps, are in [traffic-ramp.md](./traffic-ramp.md).
80
+
81
+ 1. **Deploy freeze** for the window. Each deploy changes the build hash, which moves every page-cache key (`cacheVersion`), and leaves open tabs with missing chunks ([react-spa.md](./react-spa.md#stale-chunks-after-deploy)).
82
+ 2. **Split config first, then the route.** Write the KV entry for the host before the route sends traffic to the worker.
83
+ 3. **Smoke with each bucket forced** (`?_deco_bucket=worker` and `?_deco_bucket=fallback`): home, listing, product, search, login, cart, checkout, old landing pages, redirects, `robots.txt`, sitemap, tag manager.
84
+ 4. **Check the proxies** the site already has (checkout, `/api`, media) in both buckets.
85
+ 5. **Warm the cache** by fetching **pages** with a mobile and a desktop user agent, for the top URLs from analytics. Warming loaders does not warm HTML.
86
+ 6. **Traffic ladder** with written gates: 1% → 10% → 50% → 100%. At each step compare errors, `X-Cache` hit rate, 5xx rate, memory, and conversion per bucket.
87
+ 7. **Rollback** written down and rehearsed for each layer: traffic, code, content ([content-releases.md](./content-releases.md#rollback)).
88
+
89
+ ```bash
90
+ # warm-up: pages, both devices
91
+ while read -r path; do
92
+ for ua in "Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X) Mobile/15E148" \
93
+ "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) Chrome/139 Safari/537.36"; do
94
+ curl -s -o /dev/null -A "$ua" -w "%{http_code} %{time_total}s $path\n" "https://$HOST$path"
95
+ done
96
+ done < top-urls.txt
97
+ ```
98
+
99
+ ## First 72 hours
100
+
101
+ - Compare each metric with the **same hour the day before on the old site**, not with earlier the same day. Traffic shape changes by hour.
102
+ - When you remove an endpoint (telemetry, a beacon), keep it answering for at least the HTML cache TTL. Cached pages still call it.
103
+ - Feature flags: deploy the code that reads the new default first, then remove the old flag value.
104
+ - Path-filter CI jobs that run on every PR against a preview. One store's per-PR perf job cost 3,300 CI minutes a month and was deleted.
105
+ - Check each analytics vendor's own report against the same day last week ([seo-analytics.md](./seo-analytics.md#vendors-that-stop-silently)).
106
+ - Keep porting old-repo drift (see the freeze above).