@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,192 @@
1
+ # Loaders
2
+
3
+ On v8 a loader is a block function that returns data. There is no `loaders/` folder
4
+ convention, no `export const loader` next to a section, and no `(props, req, ctx)`
5
+ signature. A loader is a key in the block map like any other block.
6
+
7
+ ```ts
8
+ // src/catalog.ts
9
+ import type { Product } from "@decocms/compat-v7/commerce/types";
10
+
11
+ export async function productBySlug({ slug }: { slug: string }): Promise<Product> {
12
+ // call the platform client here (see the deco-apps skill)
13
+ }
14
+ ```
15
+
16
+ ```ts
17
+ // .deco/index.ts
18
+ export default {
19
+ "product-by-slug": productBySlug,
20
+ "product-card": (input: ProductCardProps) => <ProductCard {...input} />,
21
+ } satisfies Blocks;
22
+ ```
23
+
24
+ `deco schema` puts a key in the loaders group when its return type is not an element,
25
+ a descriptor or a boolean, and is not its own props type. A function that returns its
26
+ props unchanged (like `seo: (input: Seo) => input`) is content, or a page when its
27
+ props extend `Route`. Use whatever data types fit the site. The schema.org-shaped
28
+ commerce types (`Product`, `ProductDetailsPage`, `ProductListingPage`, `BreadcrumbList`)
29
+ are in `@decocms/compat-v7/commerce/types`.
30
+
31
+ ## How content plugs a loader into a section
32
+
33
+ A section prop with an object type accepts a plain value, or any block whose awaited
34
+ return type fits that type (TypeScript assignability). Studio offers those blocks as
35
+ choices for the field. In content:
36
+
37
+ ```json
38
+ {
39
+ "__resolveType": "product-card",
40
+ "title": "Summer collection",
41
+ "product": { "__resolveType": "product-by-slug", "slug": "summer-shirt" }
42
+ }
43
+ ```
44
+
45
+ The resolver runs `product-by-slug` first and calls `product-card` with the `Product`
46
+ it returned. So type section props by the data they render, not by the loader that
47
+ fetches it. Any loader that returns a `Product` then fits.
48
+
49
+ ## One run per distinct input, per client
50
+
51
+ A client (one per request) remembers each block function's result by its inputs:
52
+
53
+ - The same function with the same inputs runs once per client. Every place that asks
54
+ gets the same promise, including calls made at the same time. Key order in the inputs
55
+ does not matter.
56
+ - Different inputs run separately. A new client (the next request) runs again.
57
+ - Inputs that are not JSON (a function passed by code) are not remembered.
58
+
59
+ This is how a page shares one upstream call between the product section and its SEO
60
+ block (see [seo.md](./seo.md)). It also means results are shared. Never mutate a
61
+ loader's result. Copy it first.
62
+
63
+ This is per request only. Caching across requests is a job for the upstream client's
64
+ `fetch` (see the `deco-storefront-caching` skill), not for the block.
65
+
66
+ ## Route params and other request data
67
+
68
+ A block function gets its inputs and nothing else. To read request-dependent data:
69
+
70
+ - **Route params** come from `matchRoute` in the page loader, which passes them as
71
+ arguments to the top-level blocks it resolves (see [pages.md](./pages.md)). A nested
72
+ loader does not get them. The section that received the param resolves the loader
73
+ itself, through the current client:
74
+
75
+ ```ts
76
+ import { currentClient } from "@decocms/blocks";
77
+ import type { Product } from "@decocms/compat-v7/commerce/types";
78
+
79
+ export interface ProductDetailsProps {
80
+ /** @ignore */
81
+ slug?: string;
82
+ }
83
+
84
+ export async function productDetails({ slug }: ProductDetailsProps) {
85
+ const client = currentClient(); // before any await
86
+ const [product, error] = await client.resolve<Product>({
87
+ __resolveType: "product-by-slug",
88
+ slug,
89
+ });
90
+ if (error) throw error;
91
+ return { component: "product-details", props: { product } } as const;
92
+ }
93
+ ```
94
+
95
+ The call goes through the same client, so it shares the per-request memo with every
96
+ other block asking for the same slug. `@ignore` keeps `slug` out of the Studio form,
97
+ since editors do not fill it in. The page loader does.
98
+
99
+ - **Visitor, version and date**: `currentClient()` returns the client, with
100
+ `client.visitor`, `client.version` and `client.date`. Call it at the start of the
101
+ function, before any `await`. On runtimes without `AsyncLocalStorage` it is gone after
102
+ the first `await`, and it throws outside a block function.
103
+
104
+ - **Cookies, headers, device**: these are not block inputs. The binding reads them in
105
+ the page loader. Pass what a block needs as an argument, the same way as a param. A
106
+ block that depends on the request varies the cached page, so check with the
107
+ `deco-storefront-caching` skill first.
108
+
109
+ ## Secrets and clients
110
+
111
+ Content holds no secrets, and there is no `secret` block. Create the upstream client in
112
+ code from the deploy platform's secrets, and close over it:
113
+
114
+ ```ts
115
+ import { createInstrumentedFetch } from "@decocms/blocks/fetch";
116
+ import type { Review } from "./model"; // the site's own type
117
+
118
+ const reviewsFetch = createInstrumentedFetch({ provider: "reviews" });
119
+
120
+ export const productReviews =
121
+ (apiKey: string) =>
122
+ async ({ productId }: { productId: string }): Promise<Review[]> => {
123
+ const url = `https://reviews.example.com/v1/products/${encodeURIComponent(productId)}`;
124
+ const response = await reviewsFetch(url, {
125
+ operation: "reviews.list",
126
+ headers: { authorization: `Bearer ${apiKey}` },
127
+ });
128
+ if (!response.ok) throw new Error(`reviews: HTTP ${response.status}`);
129
+ return (await response.json()) as Review[];
130
+ };
131
+
132
+ // .deco/index.ts: "product-reviews": productReviews(reviewsApiKey),
133
+ ```
134
+
135
+ Editors choose `productId`. The key never enters content. A v7 `secret` block left in
136
+ content fails `deco check` with `unknown block type`, and the message says secrets live
137
+ in the deploy platform. The
138
+ `@decocms/apps-*` clients and how to configure them are in the `deco-apps` skill.
139
+
140
+ ## Fetching upstream
141
+
142
+ - Use the platform client from `@decocms/apps-*` when there is one.
143
+ - For an API of your own, wrap `fetch` with `createInstrumentedFetch` from
144
+ `@decocms/blocks/fetch`:
145
+
146
+ ```ts
147
+ import { createInstrumentedFetch } from "@decocms/blocks/fetch";
148
+
149
+ const reviewsFetch = createInstrumentedFetch({
150
+ provider: "reviews",
151
+ retry: { attempts: 2 },
152
+ circuitBreaker: { failures: 5, cooldownMs: 30_000 },
153
+ });
154
+ await reviewsFetch(url, { operation: "reviews.list" });
155
+ ```
156
+
157
+ Each request is measured once (`http.client.request.duration`, labelled by
158
+ `provider` and `operation`). Retries and the circuit breaker are off unless set. Only
159
+ idempotent methods retry, never a `POST`.
160
+ - Ask for only what the section shows. Trim large upstream payloads in the loader
161
+ before they reach a section. The `deco-storefront-performance` skill has the method.
162
+
163
+ ## Errors
164
+
165
+ - A loader that throws fails as `BLOCK_FAILED`, with `path` pointing at the field, for
166
+ example `["sections", 2, "product"]`, and the original error in `cause`.
167
+ - A failed nested block fails its parent. A page loader that resolves each section on
168
+ its own (the TanStack examples) shows one failed section's error state and renders
169
+ the others. One that resolves the whole page in one call (the Next.js examples)
170
+ fails the whole page.
171
+ - Decide what "no data" means. For an optional section, return `undefined` (render
172
+ nothing) or an empty list. Throw only when the page cannot make sense without it.
173
+ - On TanStack the page loader can mark the response with `DEGRADED_HEADER`
174
+ (`x-deco-degraded`, from `@decocms/tanstack/server`) when a loader failed, so the
175
+ site's page cache does not store it. Headers are sent before the body, so the page
176
+ loader has to await every block before it answers, and nothing streams. See the
177
+ `deco-storefront-caching` skill.
178
+
179
+ ## Moving a v7 or Fresh loader
180
+
181
+ | v7 / Fresh | v8 |
182
+ |---|---|
183
+ | `export const loader = (props, req, ctx) => ...` in the section | A loader block, plugged into a section prop in content; or the section resolves it through `currentClient()` |
184
+ | `loaders/x.ts` default export | A block map key pointing at the function |
185
+ | `ctx.invoke.<app>.loaders.x(...)` | Call the platform client from `@decocms/apps-*` in code, or `currentClient().resolve({ __resolveType: "x", ... })` for another block |
186
+ | `requestToParam` in content | Params from `matchRoute`, passed by the page loader |
187
+ | `req.headers`, cookies | Read by the binding and passed as arguments |
188
+ | Cached loaders, `cache: "stale-while-revalidate"` | No block-level cache. Cache in the upstream client's `fetch` |
189
+
190
+ A migrated site can keep v7's `(props, req)` section loaders through
191
+ `runSectionLoaders` in `@decocms/compat-v7/sections`. That path is for migrations
192
+ only. See the `deco-v7-to-v8-migration` skill. Write new loaders as block functions.
@@ -0,0 +1,158 @@
1
+ # Pages
2
+
3
+ A page is a saved block of the built-in type `page`. It lives at
4
+ `.deco/blocks/<name>.json` (the file name is `encodeURIComponent(name)`), and the site's
5
+ catch-all route finds it by path with `matchRoute`.
6
+
7
+ ```json
8
+ {
9
+ "__resolveType": "page",
10
+ "name": "Summer shirt",
11
+ "path": "/:slug/p",
12
+ "seo": { "__resolveType": "seo", "title": "Summer shirt", "description": "Light cotton shirt." },
13
+ "sections": [
14
+ { "__resolveType": "Header" },
15
+ { "__resolveType": "product-hero", "name": "Summer shirt", "price": 49, "currency": "USD", "image": "/images/summer-shirt.jpg" },
16
+ { "__resolveType": "Footer" }
17
+ ]
18
+ }
19
+ ```
20
+
21
+ The resolved type is `Page<Section>` from `@decocms/blocks`: `name` and `path` (from
22
+ `Route`), an optional `seo` and `sections`. The built-in `page` returns its inputs as
23
+ they are, so a resolved page is `{ name, path, seo, sections }` with every section
24
+ resolved. Without `seo`, the site's defaults apply (see [seo.md](./seo.md)).
25
+
26
+ Create or edit pages in Studio, or edit the JSON and send it with the `deco` CLI (see
27
+ the `deco-site-workflow` skill). There is no `website/pages/Page.tsx` type to write.
28
+ v7 content that still says so resolves through a legacy alias.
29
+
30
+ ## Paths
31
+
32
+ `path` is a template. `matchRoute` compiles all paths into a segment tree and tries, at
33
+ each segment, the literal child first, then a `:param` child, then a trailing `*`. So
34
+ `/sale` beats `/:slug`, and `/:slug` beats `/*`.
35
+
36
+ | Template | Matches | `params` |
37
+ |---|---|---|
38
+ | `/about` | `/about` | `{}` |
39
+ | `/:slug/p` | `/summer-shirt/p` | `{ slug: "summer-shirt" }` |
40
+ | `/blog/:slug` | `/blog/archive` | `{ slug: "archive" }` |
41
+ | `/c/*` | `/c/shoes/running` | `{ "*": "shoes/running" }` (one or more segments) |
42
+
43
+ - The URL is percent-decoded, its query and fragment are dropped, and a trailing slash
44
+ is removed before matching. A `:param` never holds a slash.
45
+ - A splat is only a trailing `*` segment. v7's `/:slug*` form is not v8 syntax.
46
+ - Two pages whose paths reach the same leaf (`/:a/p` and `/:b/p`) conflict. `deco check`
47
+ reports it, and at runtime the page whose saved name sorts first wins.
48
+
49
+ ## How a page is opened
50
+
51
+ The binding's page loader (`src/open-page.server.ts` in the examples and in what the
52
+ migration script writes) does this per request. You rarely change it, but you need it
53
+ in mind to know what reaches your blocks.
54
+
55
+ 1. `client.routes()`: `{ name, path }` of every page, from the content index. `name`
56
+ is the saved block's name.
57
+ 2. `matchRoute(href, { routes })`: `match` with `entry` and `params`, or `not-found`.
58
+ 3. `client.prefetch(entry.name)`: starts downloading the page and everything it
59
+ references, in parallel with the next step.
60
+ 4. `client.redirects()` and `matchRoute(href, { routes: [], redirects })`: a redirect
61
+ wins over a page at the same path.
62
+ 5. `client.resolve(entry.name, { run: false })`: the page as JSON, saved references
63
+ expanded, nothing run.
64
+ 6. In the TanStack examples: one `client.resolve(section)` per section, each its own
65
+ promise, plus `seo`. The route renders each promise in its own Suspense boundary.
66
+ See [lazy-blocks.md](./lazy-blocks.md). The Next.js examples skip step 5 and
67
+ resolve the whole page in one call (`client.resolve(entry.name)`), so there one
68
+ failing block fails the page.
69
+
70
+ The wiring of that file, the route and `head()` belong to the `deco-tanstack-site` and
71
+ `deco-nextjs-site` skills.
72
+
73
+ ## Route params reach blocks as arguments
74
+
75
+ A block function never sees the URL. `matchRoute` returns `params` to the page loader,
76
+ and the page loader passes them on. With a section read in step 5, add the param as an
77
+ argument when you resolve it:
78
+
79
+ ```ts
80
+ const { slug } = match.params;
81
+ const [hero, error] = await c.resolve({ ...section, slug });
82
+ ```
83
+
84
+ For an inline block, the extra field becomes one of its inputs. For a reference to a
85
+ saved block, it is merged over the saved block's own fields (shallow,
86
+ `{ ...saved, ...arguments }`). Only the top-level block gets it. A loader nested inside
87
+ the section does not. The section passes `slug` down itself (see
88
+ [loaders.md](./loaders.md)). Decide one name per param (`slug`) and use it in every
89
+ block that needs it, so the page loader can pass the same arguments to all of them.
90
+
91
+ A page loader that resolves the whole page in one call has no per-section step. Passing
92
+ `slug` to `resolve({ __resolveType: entry.name, slug })` only reaches the `page` block
93
+ itself, not its sections. Resolve the sections one by one to pass params.
94
+
95
+ This is the page loader's choice, not a framework rule. Read the site's
96
+ `open-page.server.ts` before you assume a block gets a param. The v7 way,
97
+ `website/functions/requestToParam.ts` in content, has no v8 block.
98
+
99
+ ## Shared header and footer
100
+
101
+ Save shared sections once as named blocks (`Header.json`, `Footer.json`) and reference
102
+ them by name in each page:
103
+
104
+ ```json
105
+ { "__resolveType": "Header" }
106
+ ```
107
+
108
+ A reference resolves to the saved block. Fields you add next to `__resolveType` replace
109
+ the saved block's fields of the same name, for that page only. Copy the references from
110
+ the home page when you create a page, so every page shows the same header and footer.
111
+
112
+ ## Variants of a page's sections
113
+
114
+ `sections` can be a list, or one `multivariate` block whose variants are whole lists.
115
+ The page loader handles both: a single block resolves to the chosen list. Use the whole
116
+ list form when an A/B test changes the layout, and per-section variants when it
117
+ changes one section. See the `deco-variants` skill.
118
+
119
+ ## Changing the page type
120
+
121
+ - **Extra fields on every page.** Add a `page` key to the block map. It replaces the
122
+ built-in, and its Props type becomes the page form:
123
+
124
+ ```ts
125
+ interface StorePage extends Page {
126
+ theme: "light" | "dark";
127
+ }
128
+ export default { page: (props: StorePage) => props /* , ... */ } satisfies Blocks;
129
+ ```
130
+
131
+ `deco check` warns that Studio's page list and editor rely on the built-in `page`.
132
+ Keep the same fields so they keep working. The `seo` field then follows your type:
133
+ Studio offers a block for it only if the block's return type fits that type.
134
+
135
+ - **A routable type of your own** (blog posts, store locator entries). Make its Props
136
+ extend `Route` (`name` and `path`). A block whose Props have a `path` field but do not
137
+ extend `Route` is an error, and `deco schema` writes no schema until you fix it. Then
138
+ route it next to pages:
139
+
140
+ ```ts
141
+ const [posts] = await c.entries("post");
142
+ const postRoutes = posts.flatMap(({ name, path }) => (path ? [{ name, path }] : []));
143
+ const match = matchRoute(pathname, { routes: [...routes, ...postRoutes] });
144
+ ```
145
+
146
+ `client.entries(type)` reads only the content index (`{ name, type, path?, refs,
147
+ noIndex? }`, no body fetched); resolve the post that matched with
148
+ `client.resolve(match.entry.name)`. `client.list()` was removed and throws.
149
+
150
+ ## Checklist for a new page
151
+
152
+ 1. The path does not shadow another page (`deco check` reports conflicts).
153
+ 2. Header and footer are references to the shared saved blocks.
154
+ 3. Each section's type is a key in the block map, and `deco schema` is current.
155
+ 4. The page has `seo`, or you know which defaults it falls back to.
156
+ 5. A dynamic page's blocks get the params they need from the page loader.
157
+ 6. Open the page through `deco push --draft=<name>` and its preview link before
158
+ publishing.
@@ -0,0 +1,95 @@
1
+ # Review before publish
2
+
3
+ Run this before `deco push`, before opening a PR, and again before `deco publish`. Read
4
+ the diff (`git diff` for code, `deco diff` for content) and go through each item. The
5
+ command details are in the `deco-site-workflow` skill.
6
+
7
+ ## 1. The schema matches the code
8
+
9
+ - Run `deco schema`. It must print no errors. With an error it writes nothing, and
10
+ Studio keeps the old forms.
11
+ - In CI, `deco schema --check` fails when `.deco/schema.gen.json` is out of date.
12
+ Commit the regenerated file with the code change.
13
+ - Read every warning: `props are typed any` (empty form) and `returns any` (offered for
14
+ no field) are bugs.
15
+
16
+ ## 2. Existing content still fits
17
+
18
+ This is the check for breaking changes: a renamed or removed prop, a changed loader
19
+ return type, a removed block map key.
20
+
21
+ - `deco check` with no flag checks **production** content (when the site has
22
+ `DECO_SITE`) against your **local** `.deco/schema.gen.json`. That is exactly the
23
+ question "does my code change break pages already live?". Run it after `deco schema`.
24
+ - `deco check --draft=<name>` checks a draft's content. `--revision=<id>` checks a
25
+ published release.
26
+ - With no `DECO_SITE` anywhere, `deco check` checks the files in `.deco/blocks`.
27
+ - Exit code 1 means at least one error: an unknown block type, a field no type
28
+ declares (`unknown field`), a block that does not fit its field, two pages or
29
+ redirects matching the same URLs. Warnings do not fail it, but read them: a replaced
30
+ built-in, a `redirect` block that is not routed.
31
+
32
+ If a prop must change shape, keep the old field working until content is migrated, or
33
+ migrate the content in the same change and push it as a draft.
34
+
35
+ ## 3. Content edits are what you meant
36
+
37
+ - `deco diff` shows what `.deco/blocks` changes against what you pulled.
38
+ `deco diff --draft=<name>` compares against a draft.
39
+ - `deco push --draft=<name>` saves the changed blocks into a draft as one change and
40
+ prints its preview link. Open every page you touched through that link, at mobile and
41
+ desktop widths.
42
+ - Publish only with an explicit go-ahead: `deco publish --draft=<name>` prints the
43
+ changes first, then makes the draft live.
44
+
45
+ ## 4. Hardcoded text and styles
46
+
47
+ - Text a merchant would change (titles, labels, banners, links) is a prop, not a string
48
+ in the component. Fixed interface text (aria labels, "Add to cart" when the site has
49
+ no i18n) can stay in code.
50
+ - Styles use the site's design tokens (Tailwind theme values, CSS variables), not raw
51
+ values that have a token.
52
+ - A prop that only switches layout or spacing earns its place only if editors need it.
53
+
54
+ ## 5. Sections
55
+
56
+ - Props are typed with a named interface, and the block map uses `satisfies Blocks`.
57
+ - The section renders nothing for `undefined` and has a failed state on routes that
58
+ stream sections.
59
+ - Interactive parts are small `"use client"` components. No hooks in an element-mode
60
+ section itself.
61
+ - In descriptor mode, the new section has its union member, its block map key and its
62
+ `case` in the route's view.
63
+ - The route's Suspense fallback for the section is a skeleton of the right size.
64
+
65
+ ## 6. Loaders
66
+
67
+ - Each loader asks the upstream for only what the sections show.
68
+ - No loader mutates a result it got from another block.
69
+ - Blocks that need the same data resolve the same loader with identical inputs, so the
70
+ request makes one call (see [loaders.md](./loaders.md)).
71
+ - A loader that can fail has a decision: return empty, render nothing, or throw.
72
+ - Upstream calls go through an `@decocms/apps-*` client or `createInstrumentedFetch`.
73
+ - Expensive data a section may not use is a `Lazy<T>` prop.
74
+
75
+ ## 7. Secrets
76
+
77
+ - No token, API key or password in code, in `.deco/blocks`, or in a prop default.
78
+ Content holds no secrets on v8. Secrets live in the deploy platform and reach code
79
+ when the client is created.
80
+ - `.env` and `.dev.vars` are not committed.
81
+
82
+ ## 8. Dead code
83
+
84
+ - Every new file is imported. Every new block map key is used by content or meant for
85
+ editors.
86
+ - A removed block map key has no content left that uses it (`deco check` reports the
87
+ unknown type).
88
+ - No leftover v7 or Fresh imports (`apps/`, `$fresh`, `islands/`,
89
+ `@decocms/blocks/cms`).
90
+
91
+ ## 9. Order of release
92
+
93
+ Code that adds or changes a block must be deployed, and its schema pushed, before
94
+ content that uses it is published. Otherwise production resolves a type it does not
95
+ have (`UNKNOWN_BLOCK`). The deploy order is in the `deco-site-workflow` skill.
@@ -0,0 +1,158 @@
1
+ # Sections
2
+
3
+ A section is a block function whose return type is a React element or a render
4
+ descriptor. `deco schema` reads the block map's default export and puts every key with
5
+ such a return type in Studio's section picker. Its first parameter's type becomes the
6
+ form.
7
+
8
+ ## Write the component, then register it
9
+
10
+ 1. Write the component in `src/` with a named `Props` interface. Keep it a plain React
11
+ component. It does not know it is a block.
12
+ 2. Add a key to the block map. The key is the type name content saves in
13
+ `__resolveType`, so pick it once and keep it (kebab-case, like `promo-banner`).
14
+ 3. Run `deco schema` (or keep `deco schema --watch` running), then place the section on
15
+ a page in Studio or in `.deco/blocks/<Page>.json`.
16
+
17
+ ```ts
18
+ // src/model.ts
19
+ export interface PromoBannerProps {
20
+ /** @title Text */
21
+ title: string;
22
+ /** @title Link */
23
+ href: string;
24
+ }
25
+ ```
26
+
27
+ ```tsx
28
+ // src/PromoBanner.tsx
29
+ import type { PromoBannerProps } from "./model";
30
+
31
+ export default function PromoBanner({ title, href }: PromoBannerProps) {
32
+ return <a href={href}>{title}</a>;
33
+ }
34
+ ```
35
+
36
+ ```json
37
+ { "__resolveType": "promo-banner", "title": "Free shipping over $50", "href": "/shipping" }
38
+ ```
39
+
40
+ The JSDoc tags, widgets (`ImageWidget`, `RichText`, `Color` from
41
+ `@decocms/compat-v7/types/widgets`), field order and shapes that break the form are in
42
+ the `deco-cms-schema` skill. Do not repeat them here.
43
+
44
+ ## Descriptors or elements: follow the binding
45
+
46
+ What the block function returns depends on how the site renders. Check the existing
47
+ block map before you add a key, and do what the other sections do.
48
+
49
+ | Site | Block function returns | Who renders the component |
50
+ |---|---|---|
51
+ | TanStack Start (no RSC), as in `examples/tanstack-worker-smoke` | A descriptor: `{ component: "promo-banner", props: input }` | The catch-all route maps `component` to a React component |
52
+ | Next.js App Router (`examples/nextjs-binding-smoke`) or TanStack Start with RSC (`examples/tanstack-rsc-smoke`) | An element: `<PromoBanner {...input} />` | The block function, on the server |
53
+
54
+ Descriptor mode:
55
+
56
+ ```ts
57
+ // .deco/index.ts
58
+ import type { Blocks, Seo } from "@decocms/blocks";
59
+ import type { BlockDescriptor, PromoBannerProps } from "../src/model";
60
+
61
+ export default {
62
+ seo: (input: Seo) => input,
63
+ "promo-banner": (input: PromoBannerProps): BlockDescriptor => ({
64
+ component: "promo-banner",
65
+ props: input,
66
+ }),
67
+ } satisfies Blocks;
68
+ ```
69
+
70
+ `BlockDescriptor` is a union the site owns, one member per section:
71
+
72
+ ```ts
73
+ export type BlockDescriptor =
74
+ | { component: "promo-banner"; props: PromoBannerProps }
75
+ | { component: "product-hero"; props: ProductHeroProps };
76
+ ```
77
+
78
+ Adding a section in descriptor mode takes three edits: the union member, the block map
79
+ key, and a `case` in the route's view switch. If you skip the `case`, the section
80
+ resolves but renders nothing. Why descriptors: on TanStack Start the page's block
81
+ promises go through a server function, so they carry data, not elements.
82
+
83
+ Element mode:
84
+
85
+ ```tsx
86
+ // .deco/index.tsx
87
+ export default {
88
+ "promo-banner": (input: PromoBannerProps) => <PromoBanner {...input} />,
89
+ } satisfies Blocks;
90
+ ```
91
+
92
+ Keep `satisfies Blocks`, not a type annotation. `satisfies` keeps each function's exact
93
+ type, and `deco schema` needs it to build the forms and to know which blocks fit which
94
+ fields.
95
+
96
+ ## Interactivity: client components, not islands or HTMX
97
+
98
+ v8 has no islands folder and no HTMX. A section is a normal React tree.
99
+
100
+ - Put state, effects and event handlers in a small component in its own file, marked
101
+ `"use client"` at the top (like `src/CartButton.tsx` in the examples), and render it
102
+ from the section.
103
+ - In element mode the section runs on the server as a Server Component, so hooks in the
104
+ section file itself fail. Only the `"use client"` file hydrates.
105
+ - In descriptor mode the whole route tree hydrates. The examples still keep
106
+ `"use client"` on interactive files, so the same component works in both modes.
107
+ - Keep the section's props serializable data. Do not pass functions or class instances
108
+ from content into a client component.
109
+ - An action that needs the server (add to cart, newsletter signup) is a server function
110
+ on TanStack Start or a server action on Next.js. There is no `/deco/invoke`. See the
111
+ `deco-tanstack-site` and `deco-nextjs-site` skills.
112
+
113
+ Porting a Fresh section: `class` becomes `className`, `islands/X.tsx` becomes a
114
+ `"use client"` component, and each `hx-*` request becomes a server function called from
115
+ a client component.
116
+
117
+ ## Sections inside sections
118
+
119
+ A field typed `ReactNode` or `ReactNode[]` (in element mode) or the site's descriptor
120
+ type (in descriptor mode) becomes a section picker in Studio. Use it for layout
121
+ sections that hold other sections, like a two-column block. The children resolve before
122
+ the parent runs, so the parent gets finished elements or descriptors.
123
+
124
+ ## Data a section needs
125
+
126
+ A section should not fetch. Give it a prop typed with the data it needs (`product:
127
+ Product`) and let the content plug a loader into that prop. A loader block whose
128
+ return type fits the prop shows up as a choice in the form. See
129
+ [loaders.md](./loaders.md).
130
+
131
+ If fetching the data is expensive and the section may not need it, type the prop
132
+ `Lazy<T>` and call it only when needed. See [lazy-blocks.md](./lazy-blocks.md).
133
+
134
+ ## Things the generator warns about
135
+
136
+ `deco schema` prints these. Fix them before you push. An error (the last two) means
137
+ the schema file is not written at all.
138
+
139
+ - `"<key>": its props are typed any, so its form is empty`: give the parameter a real
140
+ type.
141
+ - `"<key>": returns any, so it isn't offered for any field`: annotate the return type.
142
+ - `"<key>" isn't a function`: every block map value must be a function.
143
+ - `"<key>": has a "path" field but its type doesn't extend Route`: a `path` field makes
144
+ a block routable. Rename the field, or extend `Route` on purpose (see
145
+ [pages.md](./pages.md)).
146
+
147
+ ## Rendering rules
148
+
149
+ - **Render nothing for `undefined`.** A section an editor hid with a rule resolves to
150
+ `undefined` and is dropped from the list. The route must not crash on it.
151
+ - **Do not mutate what props hold.** The props object itself is a fresh copy, but a
152
+ loader result inside it is shared: the same block with the same inputs runs once per
153
+ request, and every place that uses it gets the same object. Copy before you change it.
154
+ - **Keep editable text in props.** A string a merchant would change belongs in the
155
+ Props type, not in the component.
156
+ - **Keep layout choices few.** A prop that only picks spacing or color is a design
157
+ token. Use one when editors truly need it, and keep content fields first. The
158
+ `deco-cms-schema` skill covers this.