@decocms/blocks 8.10.0 → 8.12.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (210) hide show
  1. package/dist/index.d.ts +1 -1
  2. package/dist/index.d.ts.map +1 -1
  3. package/dist/index.js.map +1 -1
  4. package/dist/protocol/conformance/blockMetaVectors.json +80 -0
  5. package/dist/protocol/index.d.ts +5 -2
  6. package/dist/protocol/index.d.ts.map +1 -1
  7. package/dist/protocol/index.js +5 -2
  8. package/dist/protocol/index.js.map +1 -1
  9. package/dist/v8/blockMeta.d.ts +33 -4
  10. package/dist/v8/blockMeta.d.ts.map +1 -1
  11. package/dist/v8/blockMeta.js +70 -13
  12. package/dist/v8/blockMeta.js.map +1 -1
  13. package/dist/v8/cli/index.d.ts +1 -0
  14. package/dist/v8/cli/index.d.ts.map +1 -1
  15. package/dist/v8/cli/index.js +1 -0
  16. package/dist/v8/cli/index.js.map +1 -1
  17. package/dist/v8/cli/run.d.ts +2 -0
  18. package/dist/v8/cli/run.d.ts.map +1 -1
  19. package/dist/v8/cli/run.js +30 -1
  20. package/dist/v8/cli/run.js.map +1 -1
  21. package/dist/v8/cli/skills.d.ts +25 -0
  22. package/dist/v8/cli/skills.d.ts.map +1 -0
  23. package/dist/v8/cli/skills.js +70 -0
  24. package/dist/v8/cli/skills.js.map +1 -0
  25. package/dist/v8/client.d.ts +6 -4
  26. package/dist/v8/client.d.ts.map +1 -1
  27. package/dist/v8/client.js +26 -70
  28. package/dist/v8/client.js.map +1 -1
  29. package/dist/v8/cms.d.ts.map +1 -1
  30. package/dist/v8/cms.js +1 -2
  31. package/dist/v8/cms.js.map +1 -1
  32. package/dist/v8/contentIndex.d.ts +18 -7
  33. package/dist/v8/contentIndex.d.ts.map +1 -1
  34. package/dist/v8/contentIndex.js +46 -17
  35. package/dist/v8/contentIndex.js.map +1 -1
  36. package/dist/v8/draftChanges.d.ts.map +1 -1
  37. package/dist/v8/draftChanges.js +4 -1
  38. package/dist/v8/draftChanges.js.map +1 -1
  39. package/dist/v8/index.d.ts +1 -1
  40. package/dist/v8/index.d.ts.map +1 -1
  41. package/dist/v8/remoteLoader.d.ts +4 -2
  42. package/dist/v8/remoteLoader.d.ts.map +1 -1
  43. package/dist/v8/remoteLoader.js +13 -3
  44. package/dist/v8/remoteLoader.js.map +1 -1
  45. package/dist/v8/types.d.ts +47 -7
  46. package/dist/v8/types.d.ts.map +1 -1
  47. package/package.json +3 -2
  48. package/skills/deco-apps/SKILL.md +82 -0
  49. package/skills/deco-apps/references/algolia.md +51 -0
  50. package/skills/deco-apps/references/commerce-types.md +132 -0
  51. package/skills/deco-apps/references/instrumented-fetch.md +144 -0
  52. package/skills/deco-apps/references/magento.md +55 -0
  53. package/skills/deco-apps/references/messaging.md +76 -0
  54. package/skills/deco-apps/references/shopify.md +69 -0
  55. package/skills/deco-apps/references/vendored-loaders.md +135 -0
  56. package/skills/deco-apps/references/vtex-cookies-auth.md +146 -0
  57. package/skills/deco-apps/references/vtex.md +150 -0
  58. package/skills/deco-apps/references/wake.md +75 -0
  59. package/skills/deco-cms-schema/SKILL.md +80 -0
  60. package/skills/deco-cms-schema/references/annotations.md +147 -0
  61. package/skills/deco-cms-schema/references/content-hygiene.md +91 -0
  62. package/skills/deco-cms-schema/references/formats-and-widgets.md +112 -0
  63. package/skills/deco-cms-schema/references/shapes-that-break-the-form.md +165 -0
  64. package/skills/deco-cms-schema/references/types-to-fields.md +112 -0
  65. package/skills/deco-go-live/SKILL.md +127 -0
  66. package/skills/deco-go-live/references/content-releases.md +90 -0
  67. package/skills/deco-go-live/references/process.md +106 -0
  68. package/skills/deco-go-live/references/proxy-headers-checkout.md +139 -0
  69. package/skills/deco-go-live/references/qa-checklist-template.md +150 -0
  70. package/skills/deco-go-live/references/qa-inventory.md +120 -0
  71. package/skills/deco-go-live/references/react-spa.md +183 -0
  72. package/skills/deco-go-live/references/seo-analytics.md +114 -0
  73. package/skills/deco-go-live/references/traffic-ramp.md +87 -0
  74. package/skills/deco-go-live/references/worker-runtime.md +93 -0
  75. package/skills/deco-go-live/scripts/preflight.sh +221 -0
  76. package/skills/deco-images-media/SKILL.md +64 -0
  77. package/skills/deco-images-media/references/asset-upload.md +191 -0
  78. package/skills/deco-images-media/references/components-per-binding.md +167 -0
  79. package/skills/deco-images-media/references/providers-and-cdn.md +145 -0
  80. package/skills/deco-images-media/references/quality-and-lcp.md +93 -0
  81. package/skills/deco-images-media/references/troubleshooting.md +147 -0
  82. package/skills/deco-images-media/references/video.md +122 -0
  83. package/skills/deco-make-editable/SKILL.md +94 -0
  84. package/skills/deco-make-editable/references/a11y-and-e2e.md +104 -0
  85. package/skills/deco-make-editable/references/content-shapes.md +203 -0
  86. package/skills/deco-make-editable/references/from-figma.md +110 -0
  87. package/skills/deco-make-editable/references/i18n-fields.md +112 -0
  88. package/skills/deco-make-editable/references/inventory.md +79 -0
  89. package/skills/deco-make-editable/references/pixel-parity.md +175 -0
  90. package/skills/deco-make-editable/references/seeding-content.md +119 -0
  91. package/skills/deco-nextjs-site/SKILL.md +74 -0
  92. package/skills/deco-nextjs-site/references/caching.md +116 -0
  93. package/skills/deco-nextjs-site/references/metadata-seo.md +100 -0
  94. package/skills/deco-nextjs-site/references/proxy-and-drafts.md +177 -0
  95. package/skills/deco-nextjs-site/references/rendering.md +172 -0
  96. package/skills/deco-nextjs-site/references/setup.md +190 -0
  97. package/skills/deco-nextjs-site/references/studio-bridge.md +130 -0
  98. package/skills/deco-site-authoring/SKILL.md +75 -0
  99. package/skills/deco-site-authoring/references/lazy-blocks.md +155 -0
  100. package/skills/deco-site-authoring/references/loaders.md +192 -0
  101. package/skills/deco-site-authoring/references/pages.md +158 -0
  102. package/skills/deco-site-authoring/references/review-before-publish.md +95 -0
  103. package/skills/deco-site-authoring/references/sections.md +158 -0
  104. package/skills/deco-site-authoring/references/seo.md +116 -0
  105. package/skills/deco-site-workflow/SKILL.md +101 -0
  106. package/skills/deco-site-workflow/references/check.md +116 -0
  107. package/skills/deco-site-workflow/references/cli-reference.md +106 -0
  108. package/skills/deco-site-workflow/references/content-layout.md +93 -0
  109. package/skills/deco-site-workflow/references/content-sync.md +146 -0
  110. package/skills/deco-site-workflow/references/delivery.md +51 -0
  111. package/skills/deco-site-workflow/references/deploy.md +87 -0
  112. package/skills/deco-site-workflow/references/schema.md +173 -0
  113. package/skills/deco-site-workflow/references/serve-and-studio.md +138 -0
  114. package/skills/deco-storefront-caching/SKILL.md +67 -0
  115. package/skills/deco-storefront-caching/references/cache-keys.md +129 -0
  116. package/skills/deco-storefront-caching/references/case-study.md +82 -0
  117. package/skills/deco-storefront-caching/references/egress-traps.md +153 -0
  118. package/skills/deco-storefront-caching/references/nextjs.md +60 -0
  119. package/skills/deco-storefront-caching/references/perf-guardrails-e2e.md +123 -0
  120. package/skills/deco-storefront-caching/references/verification.md +136 -0
  121. package/skills/deco-storefront-caching/references/worker-page-cache.md +160 -0
  122. package/skills/deco-storefront-caching/scripts/html-anatomy.mjs +97 -0
  123. package/skills/deco-storefront-performance/SKILL.md +81 -0
  124. package/skills/deco-storefront-performance/references/cls-third-party.md +90 -0
  125. package/skills/deco-storefront-performance/references/hydration.md +116 -0
  126. package/skills/deco-storefront-performance/references/loaders-n-plus-1.md +107 -0
  127. package/skills/deco-storefront-performance/references/navigation-ux.md +130 -0
  128. package/skills/deco-storefront-performance/references/payload-trim.md +163 -0
  129. package/skills/deco-storefront-performance/references/render-location.md +152 -0
  130. package/skills/deco-storefront-performance/references/request-dedupe.md +147 -0
  131. package/skills/deco-storefront-performance/references/trace-reading.md +79 -0
  132. package/skills/deco-storefront-performance/references/worker-memory.md +176 -0
  133. package/skills/deco-tanstack-site/SKILL.md +68 -0
  134. package/skills/deco-tanstack-site/references/document-and-security.md +155 -0
  135. package/skills/deco-tanstack-site/references/router-and-navigation.md +137 -0
  136. package/skills/deco-tanstack-site/references/routes-and-pages.md +183 -0
  137. package/skills/deco-tanstack-site/references/server-functions.md +123 -0
  138. package/skills/deco-tanstack-site/references/setup.md +153 -0
  139. package/skills/deco-tanstack-site/references/worker-entry.md +152 -0
  140. package/skills/deco-v7-to-v8-migration/SKILL.md +123 -0
  141. package/skills/deco-v7-to-v8-migration/references/caching-and-privacy.md +10 -0
  142. package/skills/deco-v7-to-v8-migration/references/content.md +25 -0
  143. package/skills/deco-v7-to-v8-migration/references/editor-forms.md +27 -0
  144. package/skills/deco-v7-to-v8-migration/references/faststore.md +40 -0
  145. package/skills/deco-v7-to-v8-migration/references/framework-code.md +53 -0
  146. package/skills/deco-v7-to-v8-migration/references/hosted-releases.md +16 -0
  147. package/skills/deco-v7-to-v8-migration/references/import-map.md +81 -0
  148. package/skills/deco-v7-to-v8-migration/references/legacy-names.md +33 -0
  149. package/skills/deco-v7-to-v8-migration/references/manual-steps.md +10 -0
  150. package/skills/deco-v7-to-v8-migration/references/native-apps.md +43 -0
  151. package/skills/deco-v7-to-v8-migration/references/nextjs.md +19 -0
  152. package/skills/deco-v7-to-v8-migration/references/parity.md +66 -0
  153. package/skills/deco-v7-to-v8-migration/references/rendering.md +13 -0
  154. package/skills/deco-v7-to-v8-migration/references/running-the-script.md +29 -0
  155. package/skills/deco-v7-to-v8-migration/references/script-steps.md +13 -0
  156. package/skills/deco-v7-to-v8-migration/references/server-functions.md +15 -0
  157. package/skills/deco-v7-to-v8-migration/references/sibling-port.md +11 -0
  158. package/skills/deco-v7-to-v8-migration/references/site-code.md +15 -0
  159. package/skills/deco-v7-to-v8-migration/references/telemetry.md +10 -0
  160. package/skills/deco-v7-to-v8-migration/references/verify.md +23 -0
  161. package/skills/deco-v7-to-v8-migration/scripts/apps.ts +297 -0
  162. package/skills/deco-v7-to-v8-migration/scripts/asyncRendering.ts +73 -0
  163. package/skills/deco-v7-to-v8-migration/scripts/blockMap.ts +584 -0
  164. package/skills/deco-v7-to-v8-migration/scripts/checkContentReads.ts +32 -0
  165. package/skills/deco-v7-to-v8-migration/scripts/ciSchemaCheck.ts +145 -0
  166. package/skills/deco-v7-to-v8-migration/scripts/compat.ts +357 -0
  167. package/skills/deco-v7-to-v8-migration/scripts/content.ts +121 -0
  168. package/skills/deco-v7-to-v8-migration/scripts/contentReads.ts +157 -0
  169. package/skills/deco-v7-to-v8-migration/scripts/experiments.ts +81 -0
  170. package/skills/deco-v7-to-v8-migration/scripts/framework.ts +61 -0
  171. package/skills/deco-v7-to-v8-migration/scripts/imageCopy.ts +276 -0
  172. package/skills/deco-v7-to-v8-migration/scripts/imageModule.ts +285 -0
  173. package/skills/deco-v7-to-v8-migration/scripts/imports.ts +942 -0
  174. package/skills/deco-v7-to-v8-migration/scripts/invoke.ts +624 -0
  175. package/skills/deco-v7-to-v8-migration/scripts/legacyNames.ts +45 -0
  176. package/skills/deco-v7-to-v8-migration/scripts/main.ts +59 -0
  177. package/skills/deco-v7-to-v8-migration/scripts/matchers.ts +41 -0
  178. package/skills/deco-v7-to-v8-migration/scripts/migrate.ts +180 -0
  179. package/skills/deco-v7-to-v8-migration/scripts/redirects.ts +455 -0
  180. package/skills/deco-v7-to-v8-migration/scripts/report.ts +50 -0
  181. package/skills/deco-v7-to-v8-migration/scripts/scaffold.ts +1119 -0
  182. package/skills/deco-v7-to-v8-migration/scripts/secrets.ts +35 -0
  183. package/skills/deco-v7-to-v8-migration/scripts/sectionLoaders.ts +216 -0
  184. package/skills/deco-v7-to-v8-migration/scripts/siteSettings.ts +261 -0
  185. package/skills/deco-v7-to-v8-migration/scripts/stubs.ts +388 -0
  186. package/skills/deco-v7-to-v8-migration/scripts/tsconfig.json +7 -0
  187. package/skills/deco-v7-to-v8-migration/scripts/vendor.ts +249 -0
  188. package/skills/deco-v7-to-v8-migration/scripts/vtexInvoke.ts +240 -0
  189. package/skills/deco-v7-to-v8-migration/scripts/walk.ts +30 -0
  190. package/skills/deco-variants/SKILL.md +57 -0
  191. package/skills/deco-variants/references/caching-variants.md +63 -0
  192. package/skills/deco-variants/references/custom-matchers.md +83 -0
  193. package/skills/deco-variants/references/draft-preview.md +59 -0
  194. package/skills/deco-variants/references/experiments-and-campaigns.md +104 -0
  195. package/skills/deco-variants/references/multivariate.md +85 -0
  196. package/skills/deco-variants/references/v7-matchers.md +71 -0
  197. package/src/index.ts +1 -1
  198. package/src/protocol/conformance/blockMetaVectors.json +80 -0
  199. package/src/protocol/index.ts +8 -1
  200. package/src/v8/blockMeta.ts +75 -11
  201. package/src/v8/cli/index.ts +1 -0
  202. package/src/v8/cli/run.ts +35 -1
  203. package/src/v8/cli/skills.ts +91 -0
  204. package/src/v8/client.ts +32 -77
  205. package/src/v8/cms.ts +1 -2
  206. package/src/v8/contentIndex.ts +49 -19
  207. package/src/v8/draftChanges.ts +5 -1
  208. package/src/v8/index.ts +1 -1
  209. package/src/v8/remoteLoader.ts +13 -3
  210. package/src/v8/types.ts +48 -7
@@ -0,0 +1,116 @@
1
+ # Caching and ISR on Next
2
+
3
+ The binding caches nothing itself. It shapes requests so Next's own cache
4
+ (ISR, keyed by path) can keep published pages, while previews and
5
+ per-visitor decisions stay out of it.
6
+
7
+ ## The assignments route
8
+
9
+ Next caches a page by its path. Tests and campaigns change what a page shows,
10
+ so the proxy puts its decision into the path:
11
+
12
+ ```
13
+ /shoes → /_assignments/<segment>/shoes
14
+ ```
15
+
16
+ - The segment lists every test of the saved `experiments` block on or off for
17
+ this visitor, and every campaign of the saved `campaigns` block running or
18
+ not now. `-` means none; otherwise it is base64url, one spelling per set.
19
+ - The visitor id is never in it. Visitors on the same side of every test
20
+ share one path and one cache entry.
21
+ - A campaign starting or ending moves every visitor to a new path.
22
+ - The rewritten request carries no visitor and no draft header. The page
23
+ builds its client from the path alone (`assignedClient`), so it reads no
24
+ request.
25
+
26
+ ```tsx
27
+ // src/app/%5Fassignments/[assignments]/[[...path]]/page.tsx
28
+ export const revalidate = 600; // 10 minutes; never force-static
29
+ export async function generateStaticParams() {
30
+ return []; // nothing at build time: each path renders on first request, then is cached
31
+ }
32
+ ```
33
+
34
+ ## What the numbers mean
35
+
36
+ `revalidate = 600`: Next serves a stored page for 10 minutes. The first
37
+ request after that still gets the stored copy while Next renders the page
38
+ again in the background. So:
39
+
40
+ - A published change shows within about 10 minutes on a page people visit.
41
+ - A page nobody opened for longer shows its old copy once more.
42
+ - A banner can switch on a few minutes late. That delay is accepted.
43
+
44
+ On a site with `site`, the CMS also checks for a new release every `interval`
45
+ (default and minimum 60 000 ms). A re-render picks up whatever release the
46
+ process holds at that moment.
47
+
48
+ Never use `force-static` on a CMS page. A page that never expires keeps what
49
+ it rendered first, forever.
50
+
51
+ ## What makes a page render on every request
52
+
53
+ Any of these anywhere in the route, its layouts included:
54
+
55
+ - `headers()`, `cookies()` or `searchParams`;
56
+ - `bindDraft` (it reads `headers()`), so the `contentClient(cms)` pattern
57
+ that needs it (use `assignedClient` here);
58
+ - `export const dynamic = "force-dynamic"`.
59
+
60
+ A client component calling `useSearchParams()` does not stop the cache, but
61
+ renders on the client up to its nearest `<Suspense>`.
62
+
63
+ Check with `curl -sI https://<host>/<path>` twice: the second response should
64
+ show `x-nextjs-cache: HIT` (or `STALE` after 10 minutes). The example app's
65
+ smoke test checks exactly this.
66
+
67
+ ## Rules the route depends on
68
+
69
+ - **Direct hits are a 404.** The proxy answers `/_assignments/…` and
70
+ `/_draft/…` with 404 (`isAssignmentsRoutePath`, `isDraftRoutePath`), so only
71
+ its own rewrite reaches the route. Otherwise anyone could switch a test on
72
+ by typing a path.
73
+ - **Unknown names stay off, not 404.** `assignedClient` keeps off a test at 0%
74
+ and drops a test or campaign the content doesn't have. It returns `null`
75
+ (answer `notFound()`) only for a segment the proxy never writes. Next would
76
+ cache a 404 under the path, and a path written just before a publish must
77
+ still render.
78
+ - **Previews never land here.** `rewriteToAssignmentsRoute` returns `null` for
79
+ any preview; those render on the dynamic `/_draft` route.
80
+ - **Only CMS pages.** The proxy calls it only for paths its `isCmsPage` (the
81
+ site's own function) accepts.
82
+
83
+ ## A CDN in front of Next
84
+
85
+ The URL the visitor asked for (`/shoes`) answers by their cookie and the
86
+ current time, even though Next's entry is shared. So when the content saves
87
+ tests or campaigns, the rewrite marks the response
88
+ `Cache-Control: private, no-cache`. Do not override that with a shared
89
+ `s-maxage` at the CDN.
90
+
91
+ A site that caches pages in front of Next keys on the assignments, never on
92
+ the visitor:
93
+
94
+ ```ts
95
+ import { assignmentsKey, decideAssignments } from "@decocms/nextjs/proxy";
96
+
97
+ const key = assignmentsKey(await decideAssignments(proxyCms, draft, visitor));
98
+ // the version, the tests on and the campaigns running; "" when there are none
99
+ ```
100
+
101
+ Never store a response that carries `?__draft=` or the `__deco_draft` cookie.
102
+ Those responses carry `Cache-Control: max-age=0, no-cache, must-revalidate`
103
+ and `Vary: Cookie`.
104
+
105
+ ## Stale content after publishing
106
+
107
+ 1. Wait out `revalidate` and request the page twice: the second request
108
+ gets the new render.
109
+ 2. Check the release the process holds: a site with `site` reloads it every
110
+ `interval`.
111
+ 3. Check that no CDN or `headers()` rule adds a long shared `max-age` on top.
112
+ 4. A page on the draft route is never stale: if the draft shows the change
113
+ and the published page doesn't, it is the cache, not the content.
114
+
115
+ Cache keys, hit rate and egress in general: load `deco-storefront-caching`.
116
+ Tests and campaigns content: load `deco-variants`.
@@ -0,0 +1,100 @@
1
+ # Metadata from blocks
2
+
3
+ On Next, a page's `<title>`, description and other head tags come from
4
+ `generateMetadata`. On a Deco page, the source is the page block's `seo`
5
+ field. This file covers the wiring; what to put in SEO content and JSON-LD is
6
+ in `deco-site-authoring`.
7
+
8
+ ## The seo block
9
+
10
+ `@decocms/blocks` types it as `Seo { title: string; description: string }`,
11
+ and the built-in `page` block carries an optional `seo` next to `sections`.
12
+ There is no built-in `seo` block function: the site registers one in its block
13
+ map, so Studio can draw the form and saved pages can reference it.
14
+
15
+ ```tsx
16
+ // .deco/index.tsx
17
+ import type { Blocks, Seo } from "@decocms/blocks";
18
+
19
+ export default {
20
+ seo: (input: Seo) => input,
21
+ // … sections …
22
+ } satisfies Blocks;
23
+ ```
24
+
25
+ ```json
26
+ {
27
+ "__resolveType": "page",
28
+ "name": "Summer shirt",
29
+ "path": "/:slug/p",
30
+ "seo": {
31
+ "__resolveType": "seo",
32
+ "title": "Summer shirt | My store",
33
+ "description": "Light cotton shirt for hot days."
34
+ },
35
+ "sections": []
36
+ }
37
+ ```
38
+
39
+ When `resolve` runs the page, `seo` is resolved too: `page.seo` holds what the
40
+ `seo` function returned.
41
+
42
+ Need more fields (canonical, Open Graph image, noindex)? Give the site's `seo`
43
+ function its own Props type that extends `Seo`, and type the resolved page
44
+ with your own interface instead of `Page`. The CMS passes the props through;
45
+ nothing in the binding reads them.
46
+
47
+ ## generateMetadata
48
+
49
+ ```tsx
50
+ // src/app/%5Fassignments/[assignments]/[[...path]]/page.tsx
51
+ import type { Metadata } from "next";
52
+ import { openPage, pathnameFor } from "../../../../open-page.server";
53
+
54
+ type Props = { params: Promise<{ assignments: string; path?: string[] }> };
55
+
56
+ export async function generateMetadata({ params }: Props): Promise<Metadata> {
57
+ const { assignments, path } = await params;
58
+ const page = await openPage(pathnameFor(path), assignments);
59
+ return { title: page.seo?.title, description: page.seo?.description };
60
+ }
61
+ ```
62
+
63
+ - `openPage` is wrapped in React's `cache()` ([rendering.md](./rendering.md)),
64
+ so the metadata and the page share one resolve per request.
65
+ - On the assignments route, read only `params`. Reading `headers()`,
66
+ `cookies()` or `searchParams` in `generateMetadata` makes the page render
67
+ on every request, the same as in the page.
68
+ - On the draft route, call `bindDraft` before `openPage` in
69
+ `generateMetadata` too: Next may run it before the page body.
70
+ - Leave a field `undefined` when the page has no `seo`. Next then uses the
71
+ root layout's `metadata` (site defaults, a `title.template`).
72
+
73
+ ## Drafts are noindex
74
+
75
+ A preview must never be indexed. Two layers already do it:
76
+
77
+ - The proxy's `applyDraft` sets `X-Robots-Tag: noindex, nofollow`,
78
+ `Cache-Control: max-age=0, no-cache, must-revalidate` and `Vary: Cookie` on
79
+ every preview response.
80
+ - `withDeco`'s header rules add `X-Robots-Tag: noindex, nofollow` to any
81
+ request with `?__draft=` or the `__deco_draft` cookie.
82
+
83
+ Do not remove either to "fix" a header conflict. If a site-wide rule in
84
+ `headers()` sets `Cache-Control`, `withDeco` already places the draft rules
85
+ first.
86
+
87
+ ## Head tags the binding adds
88
+
89
+ `StudioPage` renders `<meta name="deco:page" content="<path template>">`.
90
+ React hoists it into `<head>`; it does not change the page's markup or SEO.
91
+
92
+ ## Checks
93
+
94
+ - `curl -s https://<host>/<path> | grep -i '<title>'` shows the page's
95
+ `seo.title`, not the layout default.
96
+ - A page with a `:slug` path has one `seo` for every slug. Per-item titles
97
+ (a product name) come from a loader that the `seo` block reads; load
98
+ `deco-site-authoring`.
99
+ - `curl -sI 'https://<host>/<path>?__draft=<name>'` shows
100
+ `X-Robots-Tag: noindex, nofollow`.
@@ -0,0 +1,177 @@
1
+ # The proxy and draft previews
2
+
3
+ The proxy (`src/proxy.ts`, Next 16's name for middleware) decides once per
4
+ request what the request reads. The pages only render that decision. This
5
+ split is what lets published pages stay cached while Studio previews render
6
+ fresh.
7
+
8
+ ## What the proxy decides
9
+
10
+ | Step | Function (`@decocms/nextjs/proxy`) | Result |
11
+ |---|---|---|
12
+ | Version | `decideDraft(proxyCms, request)` | A Studio link's draft or old release on an allowed host, its preview moment (`__at`) and switched tests and campaigns (`__test`, `__campaign`), the cookie to set |
13
+ | Visitor | `decideVisitor(request, draft)` | The `deco_segment` cookie, or a new visitor. Its cookie is sent on a first visit only, never when the request renders a draft or an old release |
14
+ | Tests and campaigns | `decideAssignments(proxyCms, draft, visitor)` | Each test of the saved `experiments` block on or off, each campaign of the saved `campaigns` block running or not. Missing blocks give none, never an error |
15
+
16
+ It forwards them to the page on request headers, always removing copies sent
17
+ from outside:
18
+
19
+ | Header | Set by |
20
+ |---|---|
21
+ | `x-deco-version` | `draftRequestHeaders(request, draft)` |
22
+ | `x-deco-visitor` | `visitorRequestHeaders(headers, visitor)` |
23
+ | `x-deco-assignments` | `assignmentsRequestHeaders(headers, assignments)` |
24
+
25
+ On the response, `applyDraft(response, draft)` sets the draft cookie and, on
26
+ any preview, `Cache-Control: max-age=0, no-cache, must-revalidate`,
27
+ `Vary: Cookie` and `X-Robots-Tag: noindex, nofollow`. `applyVisitor` sets the
28
+ visitor cookie.
29
+
30
+ ## The proxy
31
+
32
+ ```ts
33
+ // src/proxy.ts
34
+ import {
35
+ applyDraft, applyVisitor, assignmentsRequestHeaders, decideAssignments, decideDraft,
36
+ decideVisitor, draftRequestHeaders, isAssignmentsRoutePath, isDraftRoutePath,
37
+ rewriteToAssignmentsRoute, rewriteToDraftRoute, visitorRequestHeaders,
38
+ } from "@decocms/nextjs/proxy";
39
+ import { type NextRequest, NextResponse } from "next/server";
40
+ import { proxyCms } from "./cms.proxy";
41
+
42
+ export async function proxy(request: NextRequest) {
43
+ const { pathname } = request.nextUrl;
44
+ // Only the rewrites below may reach these routes.
45
+ if (isDraftRoutePath(pathname) || isAssignmentsRoutePath(pathname)) {
46
+ return new NextResponse("Not found", { status: 404 });
47
+ }
48
+ const draft = await decideDraft(proxyCms, request);
49
+ const visitor = decideVisitor(request, draft);
50
+ const assigned = isCmsPage(pathname)
51
+ ? await rewriteToAssignmentsRoute(proxyCms, request, draft, visitor)
52
+ : null;
53
+ if (assigned) return applyVisitor(applyDraft(assigned, draft), visitor);
54
+ const assignments = await decideAssignments(proxyCms, draft, visitor);
55
+ const headers = assignmentsRequestHeaders(
56
+ visitorRequestHeaders(draftRequestHeaders(request, draft), visitor),
57
+ assignments,
58
+ );
59
+ const response =
60
+ rewriteToDraftRoute(request, draft, visitor, assignments) ??
61
+ NextResponse.next({ request: { headers } });
62
+ return applyVisitor(applyDraft(response, draft), visitor);
63
+ }
64
+
65
+ // The app's own routes, outside the CMS.
66
+ function isCmsPage(pathname: string): boolean {
67
+ return pathname !== "/blog";
68
+ }
69
+
70
+ // Next's own files must not go through the proxy: rewritten, every script and style is a 404.
71
+ export const config = { matcher: ["/((?!_next/|favicon.ico).*)"] };
72
+ ```
73
+
74
+ - `rewriteToAssignmentsRoute` returns `null` for a preview, so a preview
75
+ falls through to `rewriteToDraftRoute`.
76
+ - `rewriteToDraftRoute` returns `null` when the request carries no draft
77
+ signal; the request then goes on with the forwarded headers.
78
+ - `isCmsPage` is the site's own. Routes the app owns (a blog index, an API
79
+ route) render as before and still get the forwarded headers.
80
+
81
+ **A site with no proxy logic of its own** exports
82
+ `draftProxy(proxyCms, options)` instead:
83
+
84
+ ```ts
85
+ export const proxy = draftProxy(proxyCms, {
86
+ assignments: (request) => isCmsPage(request.nextUrl.pathname),
87
+ });
88
+ ```
89
+
90
+ `assignments` picks the paths rewritten to the assignments route (default:
91
+ none) and makes direct hits on that route a 404. `rewrite` picks which
92
+ previews go to the draft route (default: all); return `false` for a route
93
+ that is already dynamic and binds the draft itself.
94
+
95
+ ## The draft route
96
+
97
+ ```tsx
98
+ // src/app/%5Fdraft/[[...path]]/page.tsx
99
+ import { DraftPreviewIndicator } from "@decocms/nextjs";
100
+ import { bindDraft, type SearchParams } from "@decocms/nextjs/server";
101
+ import { cms } from "../../../cms";
102
+ import { openPage, pathnameFor } from "../../../open-page.server";
103
+ import { PageView } from "../../PageView";
104
+
105
+ export const dynamic = "force-dynamic";
106
+
107
+ type Props = { params: Promise<{ path?: string[] }>; searchParams: Promise<SearchParams> };
108
+
109
+ export default async function DraftPage({ params, searchParams }: Props) {
110
+ await bindDraft(cms, { searchParams: await searchParams });
111
+ const opened = await openPage(pathnameFor((await params).path));
112
+ return (
113
+ <>
114
+ <PageView {...opened} />
115
+ <DraftPreviewIndicator />
116
+ </>
117
+ );
118
+ }
119
+ ```
120
+
121
+ - The folder is `%5Fdraft`. A literal `_draft` folder is private in Next and
122
+ never routes.
123
+ - `bindDraft(cms, { searchParams })` binds, for this request: the page's own
124
+ `?__draft=` (`off` ends the preview), else `x-deco-version`, else the draft
125
+ cookie, each checked against the preview hosts. It also binds the visitor
126
+ and the assignments the proxy forwarded (on the current release, only when
127
+ it saves an `experiments` or `campaigns` block, and a test at 0% stays
128
+ off). It returns whether a version was bound.
129
+ - `contentClient(cms)` then builds `cms.client({ version, experiments, campaigns })`
130
+ from what was bound. Create one per request. `openPage` in
131
+ [rendering.md](./rendering.md) calls it.
132
+ - `DraftPreviewIndicator` renders the "Preview mode" badge only when a draft
133
+ is bound. Render it inside the page, after `bindDraft`, never in a layout:
134
+ a layout may render before the page binds. `exitHref` overrides where
135
+ "Exit preview" goes (default: the current URL with `?__draft=off`).
136
+ - A layout under the draft route that reads content
137
+ (`app/%5Fdraft/layout.tsx`) calls `bindDraft(cms)` and `contentClient(cms)`
138
+ without `searchParams`; it reads the forwarded headers.
139
+ - `activeDraftPointer()` from `@decocms/nextjs/server` returns the bound
140
+ version, or `null` on the current release.
141
+
142
+ ## Preview hosts
143
+
144
+ A draft link previews only on hosts the CMS allows: the `previewHosts`
145
+ Studio writes into the current release's metadata, plus
146
+ `createCMS({ preview: { hosts } })`. The host is the one the visitor asked
147
+ for (`x-forwarded-host`, else `host`).
148
+
149
+ | Situation | Who may preview |
150
+ |---|---|
151
+ | A site whose release lists `previewHosts` | Those hosts and `preview.hosts` |
152
+ | No release on the CDN yet, or one published before Studio wrote the list | Every host |
153
+ | No `site` and no `preview.hosts` | Every host |
154
+ | The release metadata can't be read (network, 5xx, bad file) | Only `preview.hosts`, until a read succeeds |
155
+
156
+ On a host that may not preview, the page renders the release. `?__draft=off`
157
+ ends a preview on any host.
158
+
159
+ `preview.draftHosts` replaces the hosts a draft pointer may point at
160
+ (default: `.decocms.com` and loopback).
161
+
162
+ ## Debugging a draft that shows the published page
163
+
164
+ 1. Is the request reaching the proxy? Check the `matcher`.
165
+ 2. Is the host allowed? Compare `x-forwarded-host` or `host` with the release's
166
+ `previewHosts` and `preview.hosts`. Add a local host such as `localhost`
167
+ to `preview.hosts` to preview in development.
168
+ 3. Does the page call `bindDraft` before reading content, on the draft route?
169
+ 4. Does the page show a notice (`data-deco-preview-unavailable`) instead of
170
+ the "Preview mode" badge? The link's draft can no longer be read (deleted,
171
+ or the drafts host failing). The page renders the release, with that
172
+ notice instead of an error page.
173
+ 5. Is a CDN or a `headers()` rule caching responses that carry `?__draft=` or
174
+ the `__deco_draft` cookie? Draft responses must not be stored.
175
+
176
+ Studio links, draft names and `deco push --draft`: load `deco-site-workflow`.
177
+ Variant previews with `__test` and `__campaign`: load `deco-variants`.
@@ -0,0 +1,172 @@
1
+ # Reading and rendering a page
2
+
3
+ Pages are Server Components. They get one content client, match the path,
4
+ follow redirects, resolve the page block and render its sections. The same
5
+ function serves the draft route, the assignments route and
6
+ `generateMetadata`.
7
+
8
+ ## The client
9
+
10
+ | Where | Client | Why |
11
+ |---|---|---|
12
+ | Assignments route (published CMS pages) | `await assignedClient(cms, segment)` | Built from the path segment, reads no request, so Next can cache the page. `null` for a segment the proxy never writes: answer `notFound()` |
13
+ | Draft route, and the app's own dynamic routes | `contentClient(cms)`, after `await bindDraft(...)` | Built from what `bindDraft` bound from the request and the proxy's headers |
14
+
15
+ Both come from `@decocms/nextjs/server`. Create a client per request. A client
16
+ runs each block function once per distinct input and memoizes the result, so
17
+ results are shared and read-only: copy before changing one.
18
+
19
+ ## The page function
20
+
21
+ ```ts
22
+ // src/open-page.server.ts
23
+ import "server-only";
24
+ import { cache, type ReactNode } from "react";
25
+ import { notFound, permanentRedirect, redirect } from "next/navigation";
26
+ import { matchRoute, type Page } from "@decocms/blocks";
27
+ import { assignedClient, contentClient } from "@decocms/nextjs/server";
28
+ import { cms } from "./cms";
29
+
30
+ export const openPage = cache(async (pathname: string, assignments?: string) => {
31
+ const c = assignments === undefined ? contentClient(cms) : await assignedClient(cms, assignments);
32
+ if (!c) notFound();
33
+
34
+ const [routes, routesError] = await c.routes();
35
+ if (routesError) throw routesError;
36
+ const match = matchRoute(pathname, { routes });
37
+ // Start downloading the page's blocks while the redirects block loads.
38
+ if (match.kind === "match") c.prefetch(match.entry.name);
39
+
40
+ const [redirects, redirectsError] = await c.redirects();
41
+ if (redirectsError) throw redirectsError;
42
+ const moved = matchRoute(pathname, { routes: [], redirects });
43
+ if (moved.kind === "redirect") {
44
+ if (moved.status === 301 || moved.status === 308) permanentRedirect(moved.location);
45
+ redirect(moved.location);
46
+ }
47
+ if (match.kind !== "match") notFound();
48
+
49
+ const [page, error] = await c.resolve<Page<ReactNode>>(match.entry.name);
50
+ if (error) throw error;
51
+ return page;
52
+ });
53
+
54
+ export const pathnameFor = (segments: string[] = []) =>
55
+ "/" + segments.map(encodeURIComponent).join("/");
56
+ ```
57
+
58
+ Why each step is there:
59
+
60
+ - **`cache()`** from React: `generateMetadata` and the page call `openPage`
61
+ with the same arguments in one request; they share one result.
62
+ - **`routes()`** reads `{ name, path }` of every page from the content index,
63
+ without page bodies. `client.list()` was removed and throws: route with
64
+ `routes()` and `redirects()`, and read other types with `entries(type)`.
65
+ - **`matchRoute(pathname, { routes, redirects })`** returns
66
+ `{ kind: "match", entry, params }`, `{ kind: "redirect", location, status }`
67
+ or `{ kind: "not-found" }`. Exact segments win over `:params`, params over a
68
+ trailing `*`. `match.params` holds the matched params.
69
+ - **`prefetch(name)`** starts fetching the page and everything it references
70
+ in one parallel wave, with the redirects block. It never throws.
71
+ - **Redirects** run before the not-found. Statuses are 301, 302, 307 or 308.
72
+ Next's `permanentRedirect` answers 308 and `redirect` 307.
73
+ - **`resolve(name)`** runs the page: `seo` and every block in `sections` are
74
+ resolved, so `sections` holds what each block function returned.
75
+
76
+ The example app also routes a custom block type (blog posts that carry a
77
+ `path`): it adds the `{ name, path }` of `(await c.entries("post"))` to the
78
+ routes it matches (from the index, no post body read) and reads the one post
79
+ that matched.
80
+
81
+ ## Results and errors
82
+
83
+ `resolve`, `entries`, `routes` and `redirects` return a tuple instead of
84
+ throwing: `[value, null]` or `[null, CMSError]`. (`revision()` is the
85
+ exception: it rejects when content can't load.) `CMSError` has `code`, `message`, `path` (where in the
86
+ tree, such as `["sections", 2, "product"]`) and, for function failures,
87
+ `cause`.
88
+
89
+ | Code | Meaning |
90
+ |---|---|
91
+ | `NOT_FOUND` | No saved block by that name |
92
+ | `UNKNOWN_BLOCK` | A `__resolveType` not in the block map |
93
+ | `CYCLE` | Blocks reference each other in a loop |
94
+ | `BLOCK_FAILED` | A block function threw |
95
+ | `LOADER_FAILED` | The content didn't load. On a site with `site`, its `cause` is a `ContentUnavailableError` until the first load succeeds |
96
+
97
+ Throwing the error renders Next's error boundary. Decide per page whether a
98
+ failed block should fail the page or be skipped.
99
+
100
+ ## Rendering sections
101
+
102
+ ```tsx
103
+ // src/app/PageView.tsx
104
+ import { StudioPage } from "@decocms/nextjs";
105
+ import { Fragment, type ReactNode } from "react";
106
+ import type { Page } from "@decocms/blocks";
107
+
108
+ export function PageView({ page }: { page: Page<ReactNode> }) {
109
+ return (
110
+ <main>
111
+ {page.sections.map((section, index) => (
112
+ <Fragment key={index}>{section}</Fragment>
113
+ ))}
114
+ <StudioPage pathTemplate={page.path} />
115
+ </main>
116
+ );
117
+ }
118
+ ```
119
+
120
+ - A section function returns a React element, so the page renders the list
121
+ as is. A site may return descriptors instead (`{ component, props }`) and
122
+ map them itself; `Page<Section>` takes either.
123
+ - `StudioPage` renders a `<meta>` that tells the Studio bridge which page
124
+ template is on screen. See [studio-bridge.md](./studio-bridge.md).
125
+ - Sections are Server Components by default. Put interactive parts in a
126
+ `"use client"` component the section renders (the example's `ProductHero`
127
+ renders a client `CartButton`). Props passed to a client component must be
128
+ serializable.
129
+ - A client component that calls `useSearchParams()` renders on the client up
130
+ to its nearest `<Suspense>` on a cached page. Wrap it.
131
+ - A block prop that is a `lazy` block arrives as a function
132
+ `() => Promise<T>` that resolves only when called. Lazy blocks and loading
133
+ states: load `deco-site-authoring`.
134
+
135
+ ## The two routes
136
+
137
+ ```tsx
138
+ // src/app/%5Fassignments/[assignments]/[[...path]]/page.tsx
139
+ import { openPage, pathnameFor } from "../../../../open-page.server";
140
+ import { PageView } from "../../../PageView";
141
+
142
+ export const revalidate = 600;
143
+ export async function generateStaticParams() {
144
+ return [];
145
+ }
146
+
147
+ type Props = { params: Promise<{ assignments: string; path?: string[] }> };
148
+
149
+ export default async function Page({ params }: Props) {
150
+ const { assignments, path } = await params;
151
+ return <PageView page={await openPage(pathnameFor(path), assignments)} />;
152
+ }
153
+ ```
154
+
155
+ The draft route is the same page with `bindDraft` first and
156
+ `DraftPreviewIndicator` after; see [proxy-and-drafts.md](./proxy-and-drafts.md).
157
+ Why the assignments route looks like this: [caching.md](./caching.md).
158
+
159
+ ## Routes the app owns
160
+
161
+ A route outside the CMS (a blog index, an account page) calls
162
+ `await bindDraft(cms)` (with `{ searchParams }` on a page) and then reads with
163
+ `contentClient(cms)`, which uses the version, visitor and assignments the
164
+ proxy forwarded. Leave it out of the proxy's `isCmsPage` so it is not
165
+ rewritten. `bindDraft` reads request headers, so Next renders the route per
166
+ request.
167
+
168
+ `contentClient` only reads what `bindDraft` bound. Called without it, it
169
+ reads the current release with no visitor: every test is off, and campaigns
170
+ are checked against the current time.
171
+
172
+ Writing sections, loaders and page blocks: load `deco-site-authoring`.