@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,190 @@
1
+ # Setup
2
+
3
+ How a Next.js App Router app becomes a v8 Deco site. The reference app is
4
+ `examples/nextjs-binding-smoke`; copy from it rather than from memory.
5
+
6
+ ## Packages
7
+
8
+ | Package | Why |
9
+ |---|---|
10
+ | `@decocms/blocks` | The CMS (`createCMS`, `matchRoute`, types), the `deco` CLI (its `bin`), `@decocms/blocks/image` |
11
+ | `@decocms/nextjs` | The Next helpers. Same version as `@decocms/blocks` |
12
+ | `next` 16, `react` 19 | Peers of `@decocms/nextjs` (Node 24 or later). Install `react-dom` 19 with them, as any Next app does |
13
+ | `server-only` | Optional. The example marks its server modules with it |
14
+ | `@opentelemetry/api` | Optional peer, for the request metric only |
15
+
16
+ `@decocms/nextjs` has six entry points. Each is a separate subpath so the
17
+ proxy never loads React:
18
+
19
+ | Import | Used from |
20
+ |---|---|
21
+ | `@decocms/nextjs/proxy` | `src/proxy.ts` |
22
+ | `@decocms/nextjs/server` | Server Components (it reads `next/headers`) |
23
+ | `@decocms/nextjs` | Layouts and pages: `StudioBridge`, `StudioPage`, `DraftPreviewIndicator`, names and Studio origins |
24
+ | `@decocms/nextjs/config` | `next.config` (CommonJS, so `require()` works too) |
25
+ | `@decocms/nextjs/image-loader` | The next/image `loaderFile` |
26
+ | `@decocms/nextjs/instrumentation` | `src/instrumentation.ts` |
27
+
28
+ ## Files
29
+
30
+ | File | What it holds |
31
+ |---|---|
32
+ | `.deco/index.tsx` | The block map: the default export, `satisfies Blocks` |
33
+ | `.deco/blocks/*.json` | Saved content, one block per file |
34
+ | `.deco/schema.gen.json` | Written by `deco schema`. Commit it. Do not edit |
35
+ | `.deco/blocks.gen.ts` | Written by `deco content`, only for content without `site`. Do not edit |
36
+ | `src/cms.config.ts` | Every `createCMS` option except `blocks` |
37
+ | `src/cms.ts` | `cms = createCMS({ blocks, ...cmsConfig })` for pages |
38
+ | `src/cms.proxy.ts` | `proxyCms = createCMS({ blocks: {}, ...cmsConfig })` for the proxy |
39
+ | `src/proxy.ts` | See [proxy-and-drafts.md](./proxy-and-drafts.md) |
40
+ | `src/app/%5Fassignments/[assignments]/[[...path]]/page.tsx` | Every published CMS page. See [caching.md](./caching.md) |
41
+ | `src/app/%5Fdraft/[[...path]]/page.tsx` | Every preview. See [proxy-and-drafts.md](./proxy-and-drafts.md) |
42
+ | `src/app/layout.tsx` | The root layout, with `<StudioBridge site="…" />` |
43
+ | `src/image-loader.ts` | The next/image loader |
44
+ | `src/instrumentation.ts` | The request metric |
45
+
46
+ ## The block map
47
+
48
+ A saved block's `__resolveType` names a key of the block map. The function
49
+ gets the block's resolved props and returns what the page renders: a React
50
+ element for a section, plain data for anything else.
51
+
52
+ ```tsx
53
+ // .deco/index.tsx
54
+ import type { Blocks, Seo } from "@decocms/blocks";
55
+ import ProductHero from "../src/ProductHero";
56
+ import PromoBanner from "../src/PromoBanner";
57
+ import type { ProductHeroProps, PromoBannerProps } from "../src/model";
58
+
59
+ export default {
60
+ seo: (input: Seo) => input,
61
+ "promo-banner": (input: PromoBannerProps) => <PromoBanner {...input} />,
62
+ "product-hero": (input: ProductHeroProps) => <ProductHero {...input} />,
63
+ } satisfies Blocks;
64
+ ```
65
+
66
+ - The key is the block's identity in content. Renaming it breaks every saved
67
+ block that uses it.
68
+ - The CMS adds built-in blocks to every map: `lazy`, `multivariate`, `always`,
69
+ `never`, `experiment`, `campaign`, `page`, `redirect`, `redirects`,
70
+ `cms-settings`, `split-traffic`, `calendar`. Do not reuse those names.
71
+ - The Props type of each function is the Studio form. `deco schema` reads it
72
+ from `.deco/index.tsx` (or `.deco/index.ts`). Form details: load
73
+ `deco-cms-schema`.
74
+
75
+ **Editability check.** A section that renders literal text in JSX looks
76
+ right and cannot be edited in Studio. For every section, check that what an
77
+ editor should change comes from its props, and that the block map points at
78
+ the real component with its real Props type, not a static copy.
79
+
80
+ ## The two CMS handles
81
+
82
+ ```ts
83
+ // src/cms.config.ts
84
+ export const cmsConfig = { site: "my-store" };
85
+
86
+ // src/cms.ts
87
+ import { createCMS } from "@decocms/blocks";
88
+ import blocks from "../.deco";
89
+ import { cmsConfig } from "./cms.config";
90
+ export const cms = createCMS({ blocks, ...cmsConfig });
91
+
92
+ // src/cms.proxy.ts
93
+ import { createCMS } from "@decocms/blocks";
94
+ import { cmsConfig } from "./cms.config";
95
+ export const proxyCms = createCMS({ blocks: {}, ...cmsConfig });
96
+ ```
97
+
98
+ `createCMS` keeps one instance per process for each `site` (or, without
99
+ `site`, each content module), so both handles share content and release
100
+ checks. Each handle keeps its own block map. The proxy's handle has no block map, so no
101
+ section code lands in the proxy bundle.
102
+
103
+ Where content comes from:
104
+
105
+ - **With `site`** (Studio's site slug): the site's latest release on the
106
+ delivery CDN, loaded at runtime and checked again every `interval` (default
107
+ and minimum 60 000 ms). Passing `content` too throws.
108
+ - **Without `site`**: pass `content`, the module `deco content` writes from
109
+ `.deco/blocks` (`import content from "../.deco/blocks.gen"`). Used by tests
110
+ and the examples.
111
+
112
+ Other options: `preview: { hosts, draftHosts }` (see
113
+ [proxy-and-drafts.md](./proxy-and-drafts.md)), `telemetry` (`false`, or
114
+ `{ endpoint, headers }` for an OTLP/HTTP collector), and `token`, a
115
+ server-only secret that sends telemetry to the hosted collector and needs
116
+ `site`. Never import `token` into client code.
117
+
118
+ ## next.config
119
+
120
+ ```ts
121
+ // next.config.ts
122
+ import { withDeco } from "@decocms/nextjs/config";
123
+
124
+ export default withDeco({
125
+ images: { loader: "custom", loaderFile: "./src/image-loader.ts" },
126
+ });
127
+ ```
128
+
129
+ `withDeco(nextConfig, options?)` adds two things and nothing about hosting:
130
+
131
+ - `draftHeaders` (default on): two header rules placed before the site's own
132
+ `headers()`. A request with `?__draft=` or the `__deco_draft` cookie gets
133
+ `Cache-Control: max-age=0, no-cache, must-revalidate`, `Vary: Cookie` and
134
+ `X-Robots-Tag: noindex, nofollow`. Next sets `Cache-Control` and `Vary`
135
+ itself on dynamic pages, so only `X-Robots-Tag` is sure to arrive from these
136
+ rules; the proxy's `applyDraft` sets all three.
137
+ - `studioOrigins` (default on): Studio's hosts in `allowedDevOrigins`, so
138
+ `next dev` serves Studio its dev assets.
139
+
140
+ Turn either off with `withDeco(config, { draftHeaders: false, studioOrigins: false })`.
141
+
142
+ ## Scripts
143
+
144
+ Run the CLI before Next (the example does the same through a small script):
145
+
146
+ ```json
147
+ "predev": "deco schema && deco content",
148
+ "prebuild": "deco schema && deco content"
149
+ ```
150
+
151
+ Drop `deco content` when the site uses `site`. Use `deco schema --check` in
152
+ CI to fail on a stale schema, and `deco schema push` on production deploys so
153
+ Studio draws the forms. Order and secrets: load `deco-site-workflow`.
154
+
155
+ If the host installs only `dependencies` in production builds, keep
156
+ `@decocms/blocks` there: the `deco` bin comes from it and `prebuild` needs it.
157
+
158
+ ## Images
159
+
160
+ ```ts
161
+ // src/image-loader.ts
162
+ import { createImageUrl, decoCdn } from "@decocms/blocks/image";
163
+ import { createDecoImageLoader, nextImageOptimizer } from "@decocms/nextjs/image-loader";
164
+
165
+ const imageUrl = createImageUrl({ providers: [decoCdn({ fit: "contain" })] });
166
+ export default createDecoImageLoader(imageUrl, { fallback: nextImageOptimizer });
167
+ ```
168
+
169
+ The first provider that takes a source builds its URL. A commerce site lists
170
+ its platform's helpers (`@decocms/apps-vtex/image`,
171
+ `@decocms/apps-shopify/image`) before `decoCdn`. Any other source goes to
172
+ `fallback`: `nextImageOptimizer` sends it through `/_next/image`; without a
173
+ fallback the `src` comes back unchanged. next/image's `quality` may also be a
174
+ named tier (`low`, `medium`, `high`, `original`); `nextImageOptimizer` sends
175
+ them as 60, 70, 80 and 100.
176
+ Providers, quality and LCP: load `deco-images-media`.
177
+
178
+ ## Request metric
179
+
180
+ ```ts
181
+ // src/instrumentation.ts
182
+ export { register } from "@decocms/nextjs/instrumentation";
183
+ ```
184
+
185
+ `register` turns Next's own request span into `http.server.request.duration`
186
+ in the CMS's telemetry, labelled by `http.route`, `http.request.method`,
187
+ `status_class` and `cache` (`DRAFT` or `BYPASS`). It records nothing without
188
+ a telemetry destination, and does nothing on the Edge runtime. A site with its
189
+ own OpenTelemetry setup adds `serverRequestSpanProcessor()` to its span
190
+ processors instead, because only one tracer provider can be registered.
@@ -0,0 +1,130 @@
1
+ # The Studio bridge
2
+
3
+ Studio's site editor shows the site in an iframe. The bridge is what lets it
4
+ scroll to a section, reload the page after a save and load its own editor
5
+ code into the page. On Next it is one component in the root layout.
6
+
7
+ ## Wiring
8
+
9
+ ```tsx
10
+ // src/app/layout.tsx
11
+ import { StudioBridge } from "@decocms/nextjs";
12
+ import type { ReactNode } from "react";
13
+
14
+ export default function RootLayout({ children }: { children: ReactNode }) {
15
+ return (
16
+ <html lang="en">
17
+ <body>
18
+ {children}
19
+ <StudioBridge site="my-store" />
20
+ </body>
21
+ </html>
22
+ );
23
+ }
24
+ ```
25
+
26
+ `StudioBridge` renders two inline scripts and uses no hooks, so a Server
27
+ Component renders it as is. It reads no request, so it does not stop the root
28
+ layout from being cached.
29
+
30
+ | Prop | Default | What it does |
31
+ |---|---|---|
32
+ | `site` | required | The site's name in Studio |
33
+ | `editShortcut` | `true` | "." (or Ctrl+Shift+E) on a page outside Studio opens it in Studio's editor; Ctrl or Cmd+"." in a new tab |
34
+ | `studioOrigins` | `DECO_STUDIO_ORIGIN`, else Studio's production and staging origins | The exact origins the Studio channel trusts |
35
+ | `nonce` | none | The CSP nonce for the inline scripts |
36
+ | `page` | none | The page on screen; a `StudioPage` on the page wins |
37
+
38
+ ## What it does
39
+
40
+ - **The bridge script** answers Studio's scroll-to-section and rerender
41
+ messages, only from a parent window at one of Studio's origins. Outside a
42
+ frame it answers no message and only listens for the "." shortcut.
43
+ - **The Studio channel** runs on every page, production included (about
44
+ 0.7 kB gzipped). Framed by a trusted origin, it posts `{ type: "deco:ready" }`
45
+ and imports a module only when the answer `{ type: "deco:load", url }`
46
+ comes from exactly one trusted origin and names a URL on that origin. Not
47
+ framed, or framed by anyone else, it does nothing. It never evaluates a
48
+ script Studio sends. Message types are in `@decocms/blocks/protocol`.
49
+
50
+ ## Which page "." opens
51
+
52
+ The root layout does not re-render on navigation, so it cannot know which
53
+ page is on screen. Each CMS page renders a marker next to its sections:
54
+
55
+ ```tsx
56
+ import { StudioPage } from "@decocms/nextjs";
57
+
58
+ <StudioPage pathTemplate={page.path} />
59
+ ```
60
+
61
+ `pathTemplate` is the page block's `path` as `matchRoute` matched it
62
+ (`/:slug/p`, not `/summer-shirt/p`). An optional `id` names the page block.
63
+ Without the marker, Studio picks the page from the URL.
64
+
65
+ ## Content Security Policy
66
+
67
+ A site with a CSP must allow Studio's origins in `script-src` (the channel
68
+ imports Studio's modules) and in `frame-ancestors` (Studio frames the site).
69
+ `withStudioCsp(directives, options?)` from `@decocms/nextjs` adds them:
70
+
71
+ ```ts
72
+ // next.config.ts
73
+ import { withStudioCsp } from "@decocms/nextjs";
74
+ import { withDeco } from "@decocms/nextjs/config";
75
+
76
+ const csp = withStudioCsp("script-src 'self' 'unsafe-inline'; object-src 'none'").join("; ");
77
+
78
+ export default withDeco({
79
+ headers: async () => [
80
+ { source: "/:path*", headers: [{ key: "Content-Security-Policy", value: csp }] },
81
+ ],
82
+ });
83
+ ```
84
+
85
+ - It adds the origins to `script-src` and `script-src-elem`. A policy that
86
+ restricts scripts only through `default-src` gets a `script-src` with
87
+ `default-src`'s sources plus Studio's.
88
+ - It adds `frame-ancestors` with Studio's only when the policy has none. A
89
+ site's own `frame-ancestors` is kept as is: add Studio's yourself.
90
+ - Options: `studioOrigins`, `frameAncestors` (other editors allowed to frame
91
+ the site), `dev: true` (loopback may frame the site),
92
+ `addFrameAncestors: false`.
93
+ - Pass the same `nonce` to `StudioBridge` when the policy uses nonces.
94
+
95
+ A site that builds its headers in the proxy can set the same value there.
96
+
97
+ ## A local or staging Studio
98
+
99
+ Set `DECO_STUDIO_ORIGIN` to a comma-separated list of exact origins (for
100
+ example `http://localhost:3000`). It replaces the default list for the
101
+ channel and for `withStudioCsp`. Each entry must be an exact http(s) origin;
102
+ anything else (a path, a wildcard) is dropped. An empty `studioOrigins={[]}`
103
+ turns the channel off.
104
+
105
+ `withDeco` adds Studio's hosts to `allowedDevOrigins`, so `next dev` serves
106
+ its dev assets when Studio frames a local site.
107
+
108
+ ## Names for the site's own code
109
+
110
+ `@decocms/nextjs` exports what the proxy, the pages and `withDeco` use, for a
111
+ route that sets its own headers: `DRAFT_PARAM` (`__draft`), `DRAFT_COOKIE`
112
+ (`__deco_draft`), `VERSION_HEADER` (`x-deco-version`), `VISITOR_HEADER`
113
+ (`x-deco-visitor`), `ASSIGNMENTS_HEADER` (`x-deco-assignments`),
114
+ `draftResponseHeaders(...)`, `STUDIO_ORIGIN`, `STUDIO_ORIGINS`,
115
+ `STUDIO_FRAME_ANCESTORS`, `DEFAULT_STUDIO_ORIGINS`, `isStudioOrigin(origin)`,
116
+ `studioOrigins(option?)` and `withStudioCsp(...)`.
117
+
118
+ ## When Studio can't drive the page
119
+
120
+ 1. Is `StudioBridge` in the root layout's `<body>`, on every route?
121
+ 2. Does the CSP allow Studio in `script-src` and `frame-ancestors`? Look for
122
+ CSP errors in the framed page's console.
123
+ 3. Does an `X-Frame-Options` header block framing? Remove it in favor of
124
+ `frame-ancestors`.
125
+ 4. Is Studio on a non-default origin? Set `DECO_STUDIO_ORIGIN` on the server.
126
+ 5. Does "." open the wrong page? Render `StudioPage` with the matched
127
+ `path` template.
128
+
129
+ Connecting a local site to Studio and the `deco` CLI side: load
130
+ `deco-site-workflow`.
@@ -0,0 +1,75 @@
1
+ ---
2
+ name: deco-site-authoring
3
+ description: "Writing sections, pages and loaders for a site on @decocms/blocks 8 (with @decocms/tanstack or @decocms/nextjs). Covers block functions in .deco/index.ts and their Props, React sections as descriptors or elements, client components instead of islands or HTMX, page blocks with path templates and route params, loaders as block functions (one run per distinct input per client, no request object), SEO and JSON-LD fed by the same commerce loader as the page, the built-in lazy block, one promise per section with Suspense and loading skeletons, and the review before deco push. Load it when creating or changing a section, page or loader, when a section never loads, loads twice or shows the wrong data, or before pushing content and code."
4
+ ---
5
+
6
+ # Authoring sections, pages and loaders on v8
7
+
8
+ On @decocms/blocks 8 everything an editor can place is a **block function**: a plain
9
+ function in the block map, `.deco/index.ts` (or `.tsx`), that takes one argument, its
10
+ inputs, and returns a value. Content is JSON in `.deco/blocks/`, where each object names
11
+ a function in `__resolveType` and carries its inputs. `client.resolve` walks that JSON
12
+ inside out, so nested blocks run first, siblings run concurrently, and each function
13
+ gets its inputs already resolved.
14
+
15
+ Use this skill when you are writing or changing the code an editor uses. It is not for
16
+ wiring the binding or deploying.
17
+
18
+ ## The model in five lines
19
+
20
+ - **Section**: a block function that returns a React element, or a descriptor
21
+ `{ component, props }`. `deco schema` puts it in the section picker.
22
+ - **Loader**: a block function that returns data. A field of type `T` accepts a plain
23
+ value or any block whose awaited return type fits `T`.
24
+ - **Matcher**: a block function that returns a boolean.
25
+ - **Page**: the built-in `page` block, `{ name, path, seo?, sections }`, routed by
26
+ `matchRoute`.
27
+ - **No request scope**: a block function gets its inputs and nothing else. It calls
28
+ `currentClient()` to reach the client, and gets route params as arguments.
29
+
30
+ ## When to load what
31
+
32
+ | Reference | Load it when |
33
+ |---|---|
34
+ | [`references/sections.md`](./references/sections.md) | Writing a section, choosing descriptors or elements, adding interactivity (hooks, `"use client"`), porting a Fresh island or an HTMX section |
35
+ | [`references/pages.md`](./references/pages.md) | Creating a page block, path templates and params, shared header/footer, a page with variants, routing a custom type, a route conflict |
36
+ | [`references/loaders.md`](./references/loaders.md) | Fetching data for a section, passing a route param to a loader, a loader that runs twice, `BLOCK_FAILED`, secrets, upstream fetches |
37
+ | [`references/lazy-blocks.md`](./references/lazy-blocks.md) | `Lazy<T>` props, the `lazy` built-in, streaming sections with Suspense, loading skeletons, a failed or hidden section |
38
+ | [`references/seo.md`](./references/seo.md) | A page's `seo` field, title and description from product data, canonical and JSON-LD, the SEO checklist for a new site |
39
+ | [`references/review-before-publish.md`](./references/review-before-publish.md) | Before `deco push` or opening a PR: the checklist, `deco schema --check`, `deco check` against a draft |
40
+
41
+ ## Rules that hold everywhere
42
+
43
+ - **One argument, no context.** A block function gets exactly one argument, its
44
+ inputs, with `__resolveType` removed. There is no `req`, no `ctx`, no `invoke`.
45
+ - **Results are read-only.** A client runs each block function once per distinct
46
+ input and hands every occurrence the same object. Copy a result before you change
47
+ it.
48
+ - **A failing block fails its parent.** The error is `BLOCK_FAILED` with `path`
49
+ set to where it happened, such as `["sections", 2, "product"]`. `resolve` never
50
+ throws: it returns `[value, null]` or `[null, error]`.
51
+ - **A hidden block is `undefined`.** A `multivariate` with no true rule resolves to
52
+ `undefined`, and lists drop it. Render nothing for it.
53
+ - **Names.** Block map keys are the type names saved in content. Built-in names
54
+ (`lazy`, `multivariate`, `always`, `never`, `experiment`, `campaign`, `page`,
55
+ `redirect`, `redirects`, `cms-settings`, `split-traffic`, `calendar`) are names no
56
+ saved block can take. A block map key with a built-in's name replaces the
57
+ built-in, and `deco check` tells you what relies on it.
58
+ - **After changing a Props type, run `deco schema`.** The Studio form comes from
59
+ `.deco/schema.gen.json`, and `deco check` validates against it.
60
+
61
+ ## Related skills
62
+
63
+ - `deco-site-workflow`: the `deco` CLI end to end (`pull`, `diff`, `push --draft`,
64
+ `publish`, `schema push`, `check`).
65
+ - `deco-cms-schema`: how a Props type becomes the Studio form (JSDoc tags, widgets,
66
+ shapes that break the form).
67
+ - `deco-tanstack-site` and `deco-nextjs-site`: the catch-all route, `open-page`, the
68
+ worker or proxy, server functions, document head.
69
+ - `deco-variants`: `multivariate`, matchers, A/B tests and campaigns.
70
+ - `deco-apps`: the `@decocms/apps-*` clients a loader calls, commerce types.
71
+ - `deco-images-media`: images and video inside sections.
72
+ - `deco-storefront-performance` and `deco-storefront-caching`: slow loaders,
73
+ duplicate upstream calls, payload size, cache keys.
74
+ - `deco-v7-to-v8-migration`: a site moving from v7, where sections still use
75
+ `(props, req)` loaders through `@decocms/compat-v7/sections`.
@@ -0,0 +1,155 @@
1
+ # Lazy blocks, streaming and skeletons
2
+
3
+ Two different tools answer "don't make the page wait for this":
4
+
5
+ - The **`lazy` built-in** skips work on the server: a prop typed `Lazy<T>` is a function
6
+ the block calls only if it needs the value.
7
+ - **One promise per section** streams the page: the page loader resolves each section on
8
+ its own, and the route shows a fallback in a Suspense boundary until that section is
9
+ ready.
10
+
11
+ v8 has no async rendering of the v7 kind. There is no `Rendering/Lazy.tsx` wrapper in
12
+ content, no `LoadingFallback` export picked up by the framework, and no section that
13
+ waits for the viewport before it loads. The migration script unwraps v7's wrappers into
14
+ plain sections.
15
+
16
+ ## The `lazy` built-in
17
+
18
+ ```ts
19
+ import type { Lazy } from "@decocms/blocks";
20
+
21
+ export async function productCard({
22
+ title,
23
+ showProduct,
24
+ product,
25
+ }: {
26
+ title: string;
27
+ showProduct: boolean;
28
+ product: Lazy<Product>;
29
+ }) {
30
+ if (!showProduct) return <Title text={title} />; // the loader never runs
31
+ const item = await product(); // the loader runs here
32
+ return <Card title={title} product={item} />;
33
+ }
34
+ ```
35
+
36
+ In content, the field holds a `lazy` block around the loader:
37
+
38
+ ```json
39
+ {
40
+ "__resolveType": "product-card",
41
+ "title": "Summer collection",
42
+ "showProduct": true,
43
+ "product": {
44
+ "__resolveType": "lazy",
45
+ "value": { "__resolveType": "product-by-slug", "slug": "summer-shirt" }
46
+ }
47
+ }
48
+ ```
49
+
50
+ How it behaves:
51
+
52
+ - The resolver does not resolve `value` first. It hands the block a memoized
53
+ `() => Promise<T>` instead.
54
+ - The value resolves the first time the function is called, and only once. A second
55
+ call returns the same result.
56
+ - If the value fails, the call rejects, and the block decides what to do. If the block
57
+ lets the error escape, the block fails with the inner error's code and path.
58
+ - A lazy value that is never called never runs, and never rejects unhandled.
59
+ - `value` can be any JSON, not only a block. Saved block references inside it expand
60
+ when it is called.
61
+
62
+ Schema and checks:
63
+
64
+ - `deco schema` turns a `Lazy<T>` prop into a field that holds a `lazy` block whose
65
+ `value` has the form of `T`. `Lazy<T>[]` is a list of them.
66
+ - `deco check` reports `this field is Lazy<T>: wrap the value in a lazy block` for a
67
+ plain value in such a field, and `a lazy block only fits a Lazy<T> field` for a `lazy`
68
+ block anywhere else. A `lazy` block cannot sit directly in a page's `sections`.
69
+ - The built-in `multivariate` stores each variant's `value` as a `lazy` block, so only
70
+ the chosen variant runs. `deco check` reports `a variant's value must be a lazy block`
71
+ otherwise.
72
+ - A matcher can take an inner rule as `Lazy<boolean>` and skip it:
73
+ `async ({ a, b }: { a: boolean; b: Lazy<boolean> }) => a && (await b())`.
74
+
75
+ Use `Lazy<T>` when the block may not need the data: a toggle, a tab that is closed by
76
+ default, a fallback source, an expensive rule. It does not move work to the browser or
77
+ delay it until scroll. A block that always calls its lazy prop gains nothing from it.
78
+
79
+ ## One promise per section
80
+
81
+ The page loader in the examples (`src/open-page.server.ts`) reads the page with
82
+ `{ run: false }`, then starts one `client.resolve(section)` per section and returns the
83
+ promises without awaiting them:
84
+
85
+ ```ts
86
+ const blocks = sections.map((block, index) => ({
87
+ key: `${href}:${index}`,
88
+ value: c.resolve(block).then(([value, error]) => {
89
+ if (error) console.error(error);
90
+ return { value: value ?? undefined, failed: error !== null };
91
+ }),
92
+ }));
93
+ ```
94
+
95
+ Each entry settles to `{ value, failed }` and never rejects, so one slow or failing
96
+ section does not hold or break the others. The route renders each one in its own
97
+ boundary. On TanStack Start without RSC:
98
+
99
+ ```tsx
100
+ <Suspense key={block.key} fallback={<SectionSkeleton />}>
101
+ <Await promise={block.value}>
102
+ {({ value, failed }) => {
103
+ if (failed) return <p role="status">This content is temporarily unavailable.</p>;
104
+ return value ? <View block={value} /> : null; // undefined: an editor hid it
105
+ }}
106
+ </Await>
107
+ </Suspense>
108
+ ```
109
+
110
+ With TanStack RSC (`examples/tanstack-rsc-smoke`), an async server component awaits
111
+ the promise inside the same `Suspense`. The Next.js examples resolve the whole page in
112
+ one call instead, so nothing streams per section and one failing block fails the page.
113
+ A Next.js site that wants per-section streaming applies the same split in its page
114
+ loader. The wiring is in the `deco-tanstack-site` and `deco-nextjs-site` skills.
115
+
116
+ Three states to render, every time:
117
+
118
+ | State | Cause | Render |
119
+ |---|---|---|
120
+ | Pending | The section's loaders are still running | The Suspense fallback |
121
+ | `failed: true` | A block in the section threw | A small, quiet message, or nothing for decoration |
122
+ | `value === undefined` | A rule hid the section | Nothing |
123
+
124
+ Two caveats from migrated sites (details in the `deco-v7-to-v8-migration` skill,
125
+ `rendering.md`):
126
+
127
+ - After changing the page setup, check in the browser that every streamed section
128
+ hydrates (its handlers and effects run). One TanStack Start release left streamed
129
+ sections with server markup that never hydrated.
130
+ - A page whose blocks only read in-memory content can await them, so every section is
131
+ in the first HTML chunk. Stop awaiting a block once it fetches upstream.
132
+
133
+ ## Skeletons
134
+
135
+ The fallback is shown in the server's first HTML and then replaced in place. A
136
+ skeleton that is the wrong size moves the page when the section arrives (CLS).
137
+
138
+ - **Match the box.** Same container, padding, gaps and aspect ratios as the real
139
+ section, at each breakpoint. Height matters more than detail.
140
+ - **Pure markup.** CSS only (a pulse animation is fine). No hooks, no data, no props
141
+ from the loader. It renders before any data exists.
142
+ - **Represent the content.** A shelf skeleton shows a title bar and the number of cards
143
+ the real shelf shows per breakpoint (for example two on mobile, four on desktop,
144
+ hiding the rest with responsive classes).
145
+ - **Reuse a card skeleton.** Most shelves and grids repeat a product card. Build one
146
+ `CardSkeleton` that mirrors the real card (image, name in two lines, price block,
147
+ button) and use it everywhere.
148
+ - **Pick the skeleton per section type.** `{ run: false }` already gives the page
149
+ loader each section's `__resolveType` (saved references are expanded, so a reference
150
+ to a saved block shows the saved block's type). The page loader can return it next to
151
+ `key` and `value`, and the route can map it to a skeleton, with one generic fallback
152
+ for the rest.
153
+ - **Above the fold.** The first sections (header, hero, product summary) are what the
154
+ user sees first. Keep their loaders fast, or await them, rather than showing a
155
+ skeleton where the main content should be.