@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,137 @@
1
+ # Router and navigation
2
+
3
+ ## `src/router.tsx`
4
+
5
+ ```tsx
6
+ import { createDecoRouter } from "@decocms/tanstack/router";
7
+ import { routeTree } from "./routeTree.gen";
8
+
9
+ export function getRouter() {
10
+ return createDecoRouter({ routeTree });
11
+ }
12
+
13
+ declare module "@tanstack/react-router" {
14
+ interface Register {
15
+ router: ReturnType<typeof getRouter>;
16
+ }
17
+ }
18
+ ```
19
+
20
+ `createDecoRouter` is `createRouter` with Deco's defaults: scroll restoration on, `defaultPreload:
21
+ "intent"`, and the Deco search parser and serializer. Its options:
22
+
23
+ | Option | For |
24
+ |---|---|
25
+ | `routeTree` | Required. |
26
+ | `context` | Router context for every route (`{ queryClient }`). |
27
+ | `Wrap` | A provider around the whole app, non-DOM only (`QueryClientProvider`, `ImageUrlProvider`). |
28
+ | `nonce` | The CSP nonce TanStack stamps on its own scripts, when the site enforces one. |
29
+ | `defaultPreload` | `"intent"` (default), `"viewport"`, `"render"` or `false`. |
30
+ | `trailingSlash` | TanStack's trailing-slash option. |
31
+
32
+ It takes nothing else. A router that needs another TanStack option (`hydrate`, say) calls
33
+ `createRouter` itself with `parseSearch: decoParseSearch` and `stringifySearch:
34
+ decoStringifySearch` from the same module, plus the defaults above.
35
+
36
+ **One `QueryClient` per router.** `getRouter()` runs per request on the server. Create the client
37
+ inside it and pass it through `context` and `Wrap`. A client at module scope is shared by every
38
+ request in the isolate and leaks one shopper's cart to the next.
39
+
40
+ ## `src/start.ts`
41
+
42
+ ```ts
43
+ import { decoServerFnFetch } from "@decocms/tanstack/start";
44
+ import { createStart } from "@tanstack/react-start";
45
+
46
+ export const startInstance = createStart(() => ({ serverFns: { fetch: decoServerFnFetch } }));
47
+ ```
48
+
49
+ `decoServerFnFetch` adds the page's CDN segment token (`__cseg`) to server-function calls, so a page
50
+ cache can let the CDN keep navigation data. With no token on the page it is a plain `fetch`. v7's
51
+ draft middleware in `start.ts` goes away: the worker decides drafts.
52
+
53
+ ## Search params
54
+
55
+ The Deco parser reads the query with `URLSearchParams`, not TanStack's JSON format, so commerce URLs
56
+ round-trip unchanged:
57
+
58
+ - A repeated key is an array: `?filter.size=M&filter.size=L` → `{ "filter.size": ["M", "L"] }`.
59
+ The serializer writes each value back.
60
+ - Every value is a string. `?page=2` is `"2"`, not `2`.
61
+ - An empty value is kept (`?q=`). `undefined` or `null` removes a param.
62
+
63
+ Pass search params as an object, not inside `to`:
64
+
65
+ ```tsx
66
+ <Link to="/s" search={{ q: term }}>Search for {term}</Link>
67
+ <Link to="." search={(prev) => ({ ...prev, page: "2" })}>Next page</Link>
68
+ ```
69
+
70
+ Keep the other params when you change one (`(prev) => ({ ...prev, sort })`). Don't rebuild the
71
+ object with `Object.fromEntries(new URLSearchParams(location.search))`: it keeps one value per key
72
+ and drops the other filters. How the loader turns these into the page's URL:
73
+ [`routes-and-pages.md`](./routes-and-pages.md).
74
+
75
+ A search form submits with `useNavigate`: `navigate({ to: "/s", search: { q } })`. Keep
76
+ `action="/s"` and `name="q"` on the `<form>` so it still works before hydration.
77
+
78
+ ## Links and preload
79
+
80
+ With `defaultPreload: "intent"`, hovering or focusing a `<Link>` loads the target route: its code
81
+ and its loader, which is the page server function. A click soon after uses that result.
82
+
83
+ - Turn it off where hover is not intent: long footer lists, variant pickers, filter options
84
+ (`<Link preload={false}>`). Each preload is a `/_serverFn/` call that resolves a whole page.
85
+ - `preload="render"` loads as soon as the link renders; keep it for the one next step most visitors
86
+ take.
87
+ - `router.preloadRoute({ to })` preloads from code (an autocomplete result under the cursor).
88
+ - Commerce APIs return absolute URLs. Turn them into paths before linking: `relative(url)` from
89
+ `@decocms/compat-v7/commerce/sdk/url` (its `stripSearchParams` option drops keys such as `skuId`).
90
+ - Keep a plain `<a href>` for other origins (a checkout on the platform's domain), downloads,
91
+ `mailto:`, `tel:` and in-page anchors.
92
+
93
+ ## A navigation that loads twice, or not at all
94
+
95
+ Count the `/_serverFn/` requests in the network panel (or a HAR) for one click. Each one resolves a
96
+ whole page.
97
+
98
+ | Symptom | Likely cause |
99
+ |---|---|
100
+ | Two calls per click, one on hover and one on click | Preload on intent, then a click whose search differs from the preloaded one. Turn preload off on that link, or make the link's target exactly the URL it navigates to. |
101
+ | Two calls for the same path, with and without a param | The param is in `loaderDeps` on one side and not the other. Keep client-only params out of `loaderDeps` and out of the href. |
102
+ | A filter or page change updates the URL but not the page | The param isn't in `loaderDeps`, so the href the loader builds from `deps` doesn't carry it. |
103
+ | Only one filter value reaches the server | A query built with `new URLSearchParams(search)`, or a search object rebuilt with `Object.fromEntries`. |
104
+
105
+ ## Variant switching on a product page
106
+
107
+ There are two kinds of variant.
108
+
109
+ **Another product** (a different color that is its own product): navigate. Skip preload on these
110
+ links, and show progress on the clicked option until the new page arrives.
111
+
112
+ ```tsx
113
+ const navigate = useNavigate();
114
+ const [loading, setLoading] = useState<number | null>(null);
115
+ // on click: e.preventDefault(); setLoading(index); navigate({ to: href });
116
+ ```
117
+
118
+ Reset `loading` when the product prop changes: the component may stay mounted across the
119
+ navigation. Don't `await navigate()` to reset it.
120
+
121
+ **Another SKU of the same product** (a size): the page already has every SKU when the product loader
122
+ returns them all. Keep the selected SKU in component state and render from it. No server call is
123
+ needed.
124
+
125
+ If the URL must also change (so a shared link opens that SKU), measure before you rely on it. v7
126
+ storefronts called `window.history.replaceState` on the claim that the router didn't see it. That
127
+ is no longer true: `@tanstack/history` 1.162 (what `@tanstack/react-router` 1.170 depends on) wraps
128
+ `pushState` and `replaceState` and notifies the router, which then starts a load. Whether that load calls the page server function depends on
129
+ `loaderDeps` and `staleTime`. Keep the SKU param out of `loaderDeps` and out of the href, then
130
+ check the network panel: a SKU click should make zero `/_serverFn/` calls.
131
+
132
+ ## Progress while a page loads
133
+
134
+ `DecoDocument` renders `NavigationProgress` (a bar at the top while `isLoading`) and
135
+ `StableOutlet` (keeps the content area's height so the footer doesn't jump). A site with its own
136
+ document can import both from `@decocms/tanstack/react`. `NavigationProgress` takes `color`
137
+ (default `--color-brand-primary-500`, else the text color).
@@ -0,0 +1,183 @@
1
+ # Routes and pages
2
+
3
+ A v8 site has no route factory. A page is three small files the site owns: the catch-all route,
4
+ the page server function, and `openPage`, which routes and resolves. v7's `cmsRouteConfig`,
5
+ `loadCmsPage` and `DecoPageRenderer` have no v8 equivalent.
6
+
7
+ ```
8
+ src/routes/$.tsx → loadPage (src/page.functions.ts) → openPage (src/open-page.server.ts)
9
+ route loader createServerFn, GET matchRoute, redirects, resolve
10
+ ```
11
+
12
+ During the server render `loadPage` is a plain call. On a client-side navigation the browser
13
+ fetches it from `/_serverFn/…`.
14
+
15
+ ## `openPage`: route, redirect, resolve
16
+
17
+ ```ts
18
+ // src/open-page.server.ts
19
+ import { notFound, redirect } from "@tanstack/react-router";
20
+ import { matchRoute, type Seo } from "@decocms/blocks";
21
+ import { client } from "./cms";
22
+ import type { StoredPage } from "./model";
23
+
24
+ export async function openPage<T>(href: string, request: Request) {
25
+ const c = client(request);
26
+ const [routes, routesError] = await c.routes();
27
+ if (routesError) throw routesError;
28
+ const match = matchRoute(href, { routes });
29
+ // The page's blocks download with the redirects block, in one wave.
30
+ if (match.kind === "match") c.prefetch(match.entry.name);
31
+ const [redirects, redirectsError] = await c.redirects();
32
+ if (redirectsError) throw redirectsError;
33
+ const moved = matchRoute(href, { routes: [], redirects });
34
+ if (moved.kind === "redirect") throw redirect({ href: moved.location, statusCode: moved.status });
35
+ if (match.kind !== "match") throw notFound();
36
+
37
+ const [page, pageError] = await c.resolve<StoredPage>(match.entry.name, { run: false });
38
+ if (pageError) throw pageError;
39
+ const sections = Array.isArray(page.sections) ? page.sections : [page.sections];
40
+ const blocks = sections.map((block, index) => ({
41
+ key: `${href}:${index}`,
42
+ value: c.resolve<T | T[] | undefined>(block).then(([value, blockError]) => {
43
+ if (blockError) console.error(blockError);
44
+ return { value: value ?? undefined, failed: blockError !== null };
45
+ }),
46
+ }));
47
+ const [seo, seoError] = await c.resolve<Seo | undefined>(page.seo);
48
+ if (seoError) throw seoError;
49
+ return { seo, blocks, pathTemplate: match.entry.path };
50
+ }
51
+ ```
52
+
53
+ What each part does:
54
+
55
+ - **`client.routes()`** lists `{ name, path }` of every page from the content index, without
56
+ reading page bodies. `matchRoute(url, { routes, redirects? })` returns `{ kind: "match", entry,
57
+ params }`, `{ kind: "redirect", location, status }` or `{ kind: "not-found" }`. Exact segments win
58
+ over `:params`, and params over a `*` splat, per segment.
59
+ - **Redirects** are the site's redirects block (`client.redirects()`). The worker already answers
60
+ them for page navigations before the app runs. `openPage` checks them again because a client-side
61
+ navigation reaches it as a server-function call, which the worker doesn't redirect.
62
+ - **`resolve(name, { run: false })`** reads the page without running its blocks. Each section is
63
+ then resolved on its own, so each is its own promise and streams on its own.
64
+ - **`resolve` returns `[value, error]`** (`Result<T>`): a failed block comes back as an error, so
65
+ check it. Report errors where you get them: v8 has no global error hook.
66
+ - **`pathTemplate`** is the page's `path` as `matchRoute` matched it. `DecoDocument` reads it from
67
+ the deepest route's loader data, so "." opens that page in Studio's editor. Add `pageId` the same
68
+ way if you have one. The example app leaves it out; add it.
69
+
70
+ **Always route the page's URL, never the request's.** `request.url` is the server-function URL on
71
+ a client-side navigation. Pass the request only to `client(request)`, which reads the headers the
72
+ worker set.
73
+
74
+ ## The server function
75
+
76
+ ```ts
77
+ // src/page.functions.ts
78
+ import { createServerFn } from "@tanstack/react-start";
79
+ import { getRequest } from "@tanstack/react-start/server";
80
+ import { openPage } from "./open-page.server";
81
+ import type { BlockDescriptor } from "./model";
82
+
83
+ function localPath(data: { href: string }) {
84
+ const href = data?.href;
85
+ if (typeof href !== "string" || !href.startsWith("/") || href.startsWith("//") || href.startsWith("/\\")) {
86
+ throw new Error("not a local path");
87
+ }
88
+ return { href };
89
+ }
90
+
91
+ export const loadPage = createServerFn({ method: "GET" })
92
+ .inputValidator(localPath)
93
+ .handler(({ data }) => openPage<BlockDescriptor>(data.href, getRequest()));
94
+ ```
95
+
96
+ Reject `//host` and `/\host`: both start with `/` and are protocol-relative URLs. A check of
97
+ `startsWith("/")` alone (the example app's zod schema) lets them through. Keep it a `GET`: a page
98
+ load is then a cacheable URL, and `serverFnPagePath(url)` from `@decocms/tanstack/worker` can read
99
+ the page path out of its `payload` for the site's page cache. Server functions in general:
100
+ [`server-functions.md`](./server-functions.md).
101
+
102
+ ## The catch-all route
103
+
104
+ ```tsx
105
+ // src/routes/$.tsx
106
+ import { Suspense } from "react";
107
+ import { Await, createFileRoute } from "@tanstack/react-router";
108
+ import { decoStringifySearch } from "@decocms/tanstack/router";
109
+ import { loadPage } from "../page.functions";
110
+
111
+ /** Search params that only select among data already loaded: they never reach the server. */
112
+ const CLIENT_ONLY = new Set(["skuId"]);
113
+
114
+ export const Route = createFileRoute("/$")({
115
+ loaderDeps: ({ search }) => ({
116
+ search: Object.fromEntries(Object.entries(search).filter(([k]) => !CLIENT_ONLY.has(k))),
117
+ }),
118
+ loader: ({ location, deps }) =>
119
+ loadPage({ data: { href: location.pathname + decoStringifySearch(deps.search) } }),
120
+ head: ({ loaderData }) => ({
121
+ meta: loaderData?.seo
122
+ ? [{ title: loaderData.seo.title }, { name: "description", content: loaderData.seo.description }]
123
+ : [],
124
+ }),
125
+ component: Page,
126
+ });
127
+
128
+ function Page() {
129
+ const page = Route.useLoaderData();
130
+ return page.blocks.map((block) => (
131
+ <Suspense key={block.key} fallback={null}>
132
+ <Await promise={block.value}>
133
+ {({ value, failed }) => (failed ? null : value ? <View block={value} /> : null)}
134
+ </Await>
135
+ </Suspense>
136
+ ));
137
+ }
138
+ ```
139
+
140
+ `View` maps each descriptor to its component (`switch (block.component)`); a value that is an
141
+ array is the chosen variant of a whole section list. `undefined` means an editor hid the block.
142
+
143
+ ### Search params
144
+
145
+ - **`loaderDeps` decides what the loader depends on.** TanStack builds the route match's id from
146
+ the route, its path params and `JSON.stringify(loaderDeps)`. Put every param the page's data
147
+ depends on in it (`q`, `sort`, `page`, `filter.*`); leave out params that only pick among data
148
+ already on the page (a SKU in a product's variant list). Never drop `q`: search then never works.
149
+ - **Build the href from `deps`, not from `location.search`**, so the page the server opens is the
150
+ page the match is keyed on.
151
+ - **Use `decoStringifySearch`.** `createDecoRouter` parses a repeated key into an array
152
+ (`?filter.size=M&filter.size=L` → `{ "filter.size": ["M", "L"] }`). `new URLSearchParams(search)`
153
+ joins that array into `filter.size=M%2CL`; `decoStringifySearch` writes both values back. The
154
+ migration script's generated route uses `URLSearchParams`; change it if the site has repeated
155
+ filter keys.
156
+ - **Empty values are kept** (`?q=`). TanStack compares the request URL with
157
+ `stringify(parse(url))` on the server and redirects (307) when they differ; the Deco pair is a
158
+ fixed point, so it never does.
159
+ - **Links and pagination**: carry every current param over and change one. `<Link search>` with
160
+ arrays works on the Deco router; `Object.fromEntries(new URLSearchParams(...))` drops all but one
161
+ value per key. More in [`router-and-navigation.md`](./router-and-navigation.md).
162
+ - **The commerce loader gets the URL from the page**, not from the request. A loader that needs the
163
+ query reads it from what `openPage` passes it. How loaders get the URL: `deco-site-authoring`.
164
+
165
+ ## Status codes
166
+
167
+ - A URL with no page: `throw notFound()` in `openPage`; the route's `notFoundComponent` (or the
168
+ root's) renders.
169
+ - A CMS page that should answer with another status (a "not found" page the editors manage): set
170
+ `x-page-status` (`PAGE_STATUS_HEADER` from `@decocms/tanstack/router`) from the route's
171
+ `headers`, for example
172
+ `headers: ({ loaderData }) => (loaderData?.status ? { [PAGE_STATUS_HEADER]: String(loaderData.status) } : {})`.
173
+ The worker turns it into the response status and removes the header. A status set while
174
+ rendering does not reach the response; a route's `headers` do.
175
+ - A page whose loader failed but still rendered: set `DEGRADED_HEADER` (`x-deco-degraded`, from
176
+ `@decocms/tanstack/server`) to `"true"` with `setResponseHeader` while the server function runs. The
177
+ example page cache never stores such a response. Caching: `deco-storefront-caching`.
178
+
179
+ ## Head and SEO
180
+
181
+ The route's `head()` returns meta from the loader data. `DecoDocument` renders `<HeadContent />`,
182
+ so the root route's `head()` (charset, viewport, a default title) and the page's merge there.
183
+ What to put in it (canonical, Open Graph, JSON-LD): `deco-site-authoring`.
@@ -0,0 +1,123 @@
1
+ # Server functions
2
+
3
+ v8 has no `/deco/invoke` and no `invoke` object: the worker answers `/deco/*` with 404. Anything
4
+ the browser asks the server for (add to cart, newsletter sign-up, a shipping quote) is a TanStack
5
+ Start server function the site writes. Raw HTTP endpoints that aren't called from React (a webhook,
6
+ a feed) go in the worker's `routes` ([`worker-entry.md`](./worker-entry.md)).
7
+
8
+ Migrating a v7 site? The migration script writes one server function per v7 invoke key:
9
+ `deco-v7-to-v8-migration` (`reference/server-functions.md`).
10
+
11
+ ## The shape
12
+
13
+ ```ts
14
+ // src/server/newsletter.functions.ts
15
+ import { createServerFn } from "@tanstack/react-start";
16
+ import { z } from "zod";
17
+ import { subscribe } from "./newsletter.server";
18
+
19
+ export const subscribeNewsletter = createServerFn({ method: "POST" })
20
+ .inputValidator(z.object({ email: z.string().email() }))
21
+ .handler(({ data }) => subscribe(data.email));
22
+ ```
23
+
24
+ ```tsx
25
+ // a client component
26
+ await subscribeNewsletter({ data: { email } });
27
+ ```
28
+
29
+ - **`GET` for reads, `POST` for writes.** A `GET` carries its input in the URL (`?payload=`), so a
30
+ cache can key on it. A `POST` never goes through the site's page cache (`isCacheable` accepts
31
+ only `GET`).
32
+ - **Validate the input.** `.inputValidator` takes a function or a schema (the example uses zod).
33
+ Anything the browser sends is untrusted; reject protocol-relative paths (`//host`) wherever an
34
+ input is a URL.
35
+ - **Put server-only code in `*.server.ts` files** and import them from handlers. TanStack Start's
36
+ import protection flags a `*.server.*` file or `@tanstack/react-start/server` imported into the
37
+ client build.
38
+
39
+ ## The handler must be a top-level `const`
40
+
41
+ TanStack Start's compiler replaces each `createServerFn(...).handler(...)` with an RPC stub
42
+ (`createClientRpc(...)`) in the client build and drops the handler's imports. In a file that only
43
+ has server functions, it looks only at top-level variable declarations
44
+ (`const x = createServerFn()...` or `export const x = ...`). In such a file, a server function
45
+ created inside a function body is not transformed, so the handler and everything it imports ship to the browser.
46
+ The call then runs in the browser: upstream APIs answer with CORS errors, and secrets may be in the
47
+ bundle.
48
+
49
+ ```ts
50
+ // Wrong: created by a factory, never transformed
51
+ export function makeAction(action: (input: unknown) => Promise<unknown>) {
52
+ return createServerFn({ method: "POST" }).handler(({ data }) => action(data));
53
+ }
54
+
55
+ // Right: one top-level const per function
56
+ export const addToCart = createServerFn({ method: "POST" })
57
+ .inputValidator(cartItemSchema)
58
+ .handler(({ data }) => addItem(data));
59
+ ```
60
+
61
+ The compiler also rejects a server function that isn't assigned to a variable
62
+ (`createServerFn must be assigned to a variable!`) or is destructured. A dispatcher that looks up
63
+ the action by name at runtime (`runInvoke(key, props)`) is v7's invoke endpoint again: write one
64
+ function per action.
65
+
66
+ **Check it.** In the browser's network panel, the call must go to `/_serverFn/...` on your own
67
+ origin, not to the upstream API. After `vite build`, search the client JavaScript (not the source
68
+ maps) for secret names and for the upstream API's host: neither should be there.
69
+
70
+ ## Per-visitor responses
71
+
72
+ A server function that answers for one visitor (cart, user, wishlist, addresses) calls
73
+ `markPrivate()` from `@decocms/tanstack/server`:
74
+
75
+ ```ts
76
+ import { markPrivate } from "@decocms/tanstack/server";
77
+
78
+ export const getCart = createServerFn({ method: "GET" }).handler(async () => {
79
+ markPrivate(); // Cache-Control: private, no-store
80
+ return readCart();
81
+ });
82
+ ```
83
+
84
+ It sets `Cache-Control: private, no-store` only when the browser called the function over HTTP
85
+ (`isServerFnCall()`). While the document renders, the call is a plain function call and the header
86
+ would land on the page, so it does nothing. A `GET` without it can be stored by the site's page
87
+ cache and served to the next visitor. Caching rules: `deco-storefront-caching`.
88
+
89
+ ## Cookies from an upstream API
90
+
91
+ An upstream call (a commerce cart, a session) often answers with several `Set-Cookie` headers.
92
+ They must reach the browser as separate headers.
93
+
94
+ ```ts
95
+ import { setResponseHeader } from "@tanstack/react-start/server";
96
+
97
+ const upstream = await fetch(url, init);
98
+ const cookies = upstream.headers.getSetCookie();
99
+ if (cookies.length) setResponseHeader("set-cookie", cookies);
100
+ ```
101
+
102
+ - **Read with `getSetCookie()`.** `headers.get("set-cookie")` returns every cookie joined by
103
+ `, ` into one string. Sent on as one header, the browser reads it as a single cookie
104
+ and the others are lost. The usual symptom: the
105
+ action succeeds, then the next page shows an empty cart.
106
+ - **`setResponseHeader` replaces.** With an array it deletes every `Set-Cookie` set earlier in this
107
+ response, then appends each value; with a string it overwrites. Collect all the cookies, then
108
+ set them once.
109
+ - **Duplicates are fine.** The worker keeps the last `Set-Cookie` for each cookie (name + Domain +
110
+ Path) on every response, so two layers setting the same cookie send one. Cookies that differ in
111
+ Domain or Path stay separate: a sign-out that clears a cookie under several scopes still clears
112
+ them all.
113
+ - In DevTools, the response should show several `Set-Cookie` rows. One row with commas inside is
114
+ the collapse.
115
+
116
+ Which cookies a commerce platform needs, and the VTEX cart flow: `deco-apps`.
117
+
118
+ ## Request state
119
+
120
+ v8 has no `RequestContext`. Inside a handler, read the request with `getRequest()` and the
121
+ worker's decisions with `requestVisitor()`, `requestAssignments()` and `requestVersion()` from
122
+ `@decocms/tanstack/server`. Pass what a helper needs as arguments; don't keep request data in
123
+ module scope, which every request in the isolate shares.
@@ -0,0 +1,153 @@
1
+ # Setting up a site
2
+
3
+ The shapes below are `examples/tanstack-worker-smoke` in this repo. Copy from there when in doubt:
4
+ it builds and runs in CI.
5
+
6
+ ## Packages
7
+
8
+ - `@decocms/blocks` and `@decocms/tanstack` at the same version. `@decocms/tanstack` takes
9
+ `@decocms/blocks` as a peer (`^8.6.0`), so a second copy of blocks never sneaks in.
10
+ - Peers: `@tanstack/react-start` and `@tanstack/react-router` (`>=1.166.0`), `react` 19, and `vite`
11
+ (only for `@decocms/tanstack/vite`).
12
+ - Dev: `@cloudflare/vite-plugin`, `@vitejs/plugin-react`, `wrangler`.
13
+ - The package's `engines` asks for Node `>=24`.
14
+
15
+ ## `vite.config.ts`
16
+
17
+ ```ts
18
+ import { cloudflare } from "@cloudflare/vite-plugin";
19
+ import { decoTanstack } from "@decocms/tanstack/vite";
20
+ import { tanstackStart } from "@tanstack/react-start/plugin/vite";
21
+ import react from "@vitejs/plugin-react";
22
+ import { defineConfig } from "vite";
23
+
24
+ export default defineConfig({
25
+ plugins: [
26
+ cloudflare({ viteEnvironment: { name: "ssr" } }),
27
+ tanstackStart(),
28
+ react(),
29
+ decoTanstack({ buildHash: process.env.WORKERS_CI_COMMIT_SHA }),
30
+ ],
31
+ });
32
+ ```
33
+
34
+ `decoTanstack()` adds four things:
35
+
36
+ - `decoContent()` from `@decocms/blocks/vite`: in `vite dev`, a block saved in the site editor
37
+ reloads open pages.
38
+ - `__BUILD_HASH__`: the build's id. `buildHash` when given (cut to 12 characters), else
39
+ `git rev-parse --short=12 HEAD`, else the time. `"dev"` in `vite dev`. Declare it once:
40
+ `declare const __BUILD_HASH__: string;`.
41
+ - A browser stub for `node:async_hooks`, so server state never breaks the client build.
42
+ - `resolve.dedupe` for React and the TanStack packages, so there is one copy of each.
43
+
44
+ The plugin reads no environment variable itself: pass the CI's commit SHA.
45
+
46
+ ## `wrangler.jsonc`
47
+
48
+ ```jsonc
49
+ {
50
+ "name": "my-store",
51
+ "main": "./src/worker-entry.ts",
52
+ "compatibility_date": "2026-02-14",
53
+ "compatibility_flags": ["nodejs_compat", "no_handle_cross_request_promise_resolution"]
54
+ }
55
+ ```
56
+
57
+ `main` is the worker entry, not TanStack's server entry ([`worker-entry.md`](./worker-entry.md)).
58
+ `nodejs_compat` is needed: the worker hands values to the render through `AsyncLocalStorage`.
59
+ The `deco` CLI finds the site in `DECO_SITE`: the environment, else `.env`, `.dev.vars`, then
60
+ `vars.DECO_SITE` in this file.
61
+
62
+ ## The block map: `.deco/index.ts`
63
+
64
+ One function per block type. The key is the type name saved in content; the function's input type
65
+ is what `deco schema` turns into Studio's form.
66
+
67
+ ```ts
68
+ import type { Blocks, Seo } from "@decocms/blocks";
69
+ import type { BlockDescriptor, ProductHeroProps, PromoBannerProps } from "../src/model";
70
+
71
+ export default {
72
+ seo: (input: Seo) => input,
73
+ "promo-banner": (input: PromoBannerProps): BlockDescriptor => ({ component: "promo-banner", props: input }),
74
+ "product-hero": (input: ProductHeroProps): BlockDescriptor => ({ component: "product-hero", props: input }),
75
+ } satisfies Blocks;
76
+ ```
77
+
78
+ The example's blocks return a descriptor (`{ component, props }`) and the route maps it to a
79
+ component ([`routes-and-pages.md`](./routes-and-pages.md)). Never rename a saved type name: content
80
+ stores it. How to write blocks and their props: `deco-site-authoring` and `deco-cms-schema`.
81
+
82
+ ## `src/cms.ts`
83
+
84
+ ```ts
85
+ import { createCMS } from "@decocms/blocks";
86
+ import { contentClient } from "@decocms/tanstack/server";
87
+ import blocks from "../.deco";
88
+ import content from "../.deco/blocks.gen";
89
+
90
+ export const cms = createCMS({ blocks, content });
91
+
92
+ // The client for this request: the version, visitor and tests the worker decided.
93
+ export const client = (request: Request) => contentClient(cms, request);
94
+ ```
95
+
96
+ `createCMS` options (`CMSConfig` in `@decocms/blocks`):
97
+
98
+ | Option | What it does |
99
+ |---|---|
100
+ | `blocks` | The block map. Required. |
101
+ | `content` | The content module (`.deco/blocks.gen.ts`) or a loader. Use it **or** `site`. |
102
+ | `site` | The site's ID in Studio. Content then comes from the delivery CDN at runtime. Passing `content` too throws. |
103
+ | `token` | The site token, a secret. Sends telemetry to the hosted collector. Needs `site`. |
104
+ | `preview.hosts` | Hosts where draft links preview, besides the ones Studio writes into the release. |
105
+ | `preview.draftHosts` | Hosts a draft pointer may point at; replaces the defaults. |
106
+ | `interval` | ms between content update checks; minimum 60 000. |
107
+ | `telemetry` | Where telemetry goes, or `false`. |
108
+
109
+ Create the CMS once, at module scope. The SDK reads no environment: the site passes `site` and
110
+ `token`. On Workers that is `import { env } from "cloudflare:workers"` (`env.DECO_SITE`, and the
111
+ token as a secret).
112
+
113
+ Create one client per request with `contentClient(cms, request)`. It builds
114
+ `cms.client({ version, visitor, experiments, campaigns })` from the headers the worker set, so the
115
+ page renders the draft and the tests the worker decided. Without the worker (another entry, a
116
+ test), the headers are missing: the release renders and the visitor decides the tests.
117
+
118
+ ## Scripts
119
+
120
+ ```json
121
+ {
122
+ "predev": "deco schema && deco content",
123
+ "dev": "vite dev",
124
+ "prebuild": "deco schema && deco content",
125
+ "build": "vite build"
126
+ }
127
+ ```
128
+
129
+ - `deco schema` turns the types in `.deco/index.ts` into `.deco/schema.gen.json`.
130
+ `deco schema --check` fails when the file is out of date (for CI).
131
+ - `deco content` turns `.deco/blocks` into `.deco/blocks.gen.ts`, the module `content` imports.
132
+ A site with `site` set reads its content from the CDN and needs no content module.
133
+ - `deco check` checks the content against the schema.
134
+
135
+ The CLI itself (login, drafts, publish, `schema push`): `deco-site-workflow`.
136
+
137
+ ## The other files
138
+
139
+ `src/router.tsx`, `src/start.ts`: [`router-and-navigation.md`](./router-and-navigation.md).
140
+ `src/routes/__root.tsx`: [`document-and-security.md`](./document-and-security.md).
141
+ `src/routes/$.tsx`, `src/page.functions.ts`, `src/open-page.server.ts`:
142
+ [`routes-and-pages.md`](./routes-and-pages.md). `src/worker-entry.ts`:
143
+ [`worker-entry.md`](./worker-entry.md).
144
+
145
+ ## Checks after setup
146
+
147
+ ```bash
148
+ bunx deco schema && bunx deco check
149
+ bun run build
150
+ ```
151
+
152
+ Then open a page, a URL with no page (404), a redirect from the redirects block, and
153
+ `/deco/_liveness` (`OK`).