@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.
- package/dist/index.d.ts +1 -1
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js.map +1 -1
- package/dist/protocol/conformance/blockMetaVectors.json +80 -0
- package/dist/protocol/index.d.ts +5 -2
- package/dist/protocol/index.d.ts.map +1 -1
- package/dist/protocol/index.js +5 -2
- package/dist/protocol/index.js.map +1 -1
- package/dist/v8/blockMeta.d.ts +33 -4
- package/dist/v8/blockMeta.d.ts.map +1 -1
- package/dist/v8/blockMeta.js +70 -13
- package/dist/v8/blockMeta.js.map +1 -1
- package/dist/v8/cli/index.d.ts +1 -0
- package/dist/v8/cli/index.d.ts.map +1 -1
- package/dist/v8/cli/index.js +1 -0
- package/dist/v8/cli/index.js.map +1 -1
- package/dist/v8/cli/run.d.ts +2 -0
- package/dist/v8/cli/run.d.ts.map +1 -1
- package/dist/v8/cli/run.js +30 -1
- package/dist/v8/cli/run.js.map +1 -1
- package/dist/v8/cli/skills.d.ts +25 -0
- package/dist/v8/cli/skills.d.ts.map +1 -0
- package/dist/v8/cli/skills.js +70 -0
- package/dist/v8/cli/skills.js.map +1 -0
- package/dist/v8/client.d.ts +6 -4
- package/dist/v8/client.d.ts.map +1 -1
- package/dist/v8/client.js +26 -70
- package/dist/v8/client.js.map +1 -1
- package/dist/v8/cms.d.ts.map +1 -1
- package/dist/v8/cms.js +1 -2
- package/dist/v8/cms.js.map +1 -1
- package/dist/v8/contentIndex.d.ts +18 -7
- package/dist/v8/contentIndex.d.ts.map +1 -1
- package/dist/v8/contentIndex.js +46 -17
- package/dist/v8/contentIndex.js.map +1 -1
- package/dist/v8/draftChanges.d.ts.map +1 -1
- package/dist/v8/draftChanges.js +4 -1
- package/dist/v8/draftChanges.js.map +1 -1
- package/dist/v8/index.d.ts +1 -1
- package/dist/v8/index.d.ts.map +1 -1
- package/dist/v8/remoteLoader.d.ts +4 -2
- package/dist/v8/remoteLoader.d.ts.map +1 -1
- package/dist/v8/remoteLoader.js +13 -3
- package/dist/v8/remoteLoader.js.map +1 -1
- package/dist/v8/types.d.ts +47 -7
- package/dist/v8/types.d.ts.map +1 -1
- package/package.json +3 -2
- package/skills/deco-apps/SKILL.md +82 -0
- package/skills/deco-apps/references/algolia.md +51 -0
- package/skills/deco-apps/references/commerce-types.md +132 -0
- package/skills/deco-apps/references/instrumented-fetch.md +144 -0
- package/skills/deco-apps/references/magento.md +55 -0
- package/skills/deco-apps/references/messaging.md +76 -0
- package/skills/deco-apps/references/shopify.md +69 -0
- package/skills/deco-apps/references/vendored-loaders.md +135 -0
- package/skills/deco-apps/references/vtex-cookies-auth.md +146 -0
- package/skills/deco-apps/references/vtex.md +150 -0
- package/skills/deco-apps/references/wake.md +75 -0
- package/skills/deco-cms-schema/SKILL.md +80 -0
- package/skills/deco-cms-schema/references/annotations.md +147 -0
- package/skills/deco-cms-schema/references/content-hygiene.md +91 -0
- package/skills/deco-cms-schema/references/formats-and-widgets.md +112 -0
- package/skills/deco-cms-schema/references/shapes-that-break-the-form.md +165 -0
- package/skills/deco-cms-schema/references/types-to-fields.md +112 -0
- package/skills/deco-go-live/SKILL.md +127 -0
- package/skills/deco-go-live/references/content-releases.md +90 -0
- package/skills/deco-go-live/references/process.md +106 -0
- package/skills/deco-go-live/references/proxy-headers-checkout.md +139 -0
- package/skills/deco-go-live/references/qa-checklist-template.md +150 -0
- package/skills/deco-go-live/references/qa-inventory.md +120 -0
- package/skills/deco-go-live/references/react-spa.md +183 -0
- package/skills/deco-go-live/references/seo-analytics.md +114 -0
- package/skills/deco-go-live/references/traffic-ramp.md +87 -0
- package/skills/deco-go-live/references/worker-runtime.md +93 -0
- package/skills/deco-go-live/scripts/preflight.sh +221 -0
- package/skills/deco-images-media/SKILL.md +64 -0
- package/skills/deco-images-media/references/asset-upload.md +191 -0
- package/skills/deco-images-media/references/components-per-binding.md +167 -0
- package/skills/deco-images-media/references/providers-and-cdn.md +145 -0
- package/skills/deco-images-media/references/quality-and-lcp.md +93 -0
- package/skills/deco-images-media/references/troubleshooting.md +147 -0
- package/skills/deco-images-media/references/video.md +122 -0
- package/skills/deco-make-editable/SKILL.md +94 -0
- package/skills/deco-make-editable/references/a11y-and-e2e.md +104 -0
- package/skills/deco-make-editable/references/content-shapes.md +203 -0
- package/skills/deco-make-editable/references/from-figma.md +110 -0
- package/skills/deco-make-editable/references/i18n-fields.md +112 -0
- package/skills/deco-make-editable/references/inventory.md +79 -0
- package/skills/deco-make-editable/references/pixel-parity.md +175 -0
- package/skills/deco-make-editable/references/seeding-content.md +119 -0
- package/skills/deco-nextjs-site/SKILL.md +74 -0
- package/skills/deco-nextjs-site/references/caching.md +116 -0
- package/skills/deco-nextjs-site/references/metadata-seo.md +100 -0
- package/skills/deco-nextjs-site/references/proxy-and-drafts.md +177 -0
- package/skills/deco-nextjs-site/references/rendering.md +172 -0
- package/skills/deco-nextjs-site/references/setup.md +190 -0
- package/skills/deco-nextjs-site/references/studio-bridge.md +130 -0
- package/skills/deco-site-authoring/SKILL.md +75 -0
- package/skills/deco-site-authoring/references/lazy-blocks.md +155 -0
- package/skills/deco-site-authoring/references/loaders.md +192 -0
- package/skills/deco-site-authoring/references/pages.md +158 -0
- package/skills/deco-site-authoring/references/review-before-publish.md +95 -0
- package/skills/deco-site-authoring/references/sections.md +158 -0
- package/skills/deco-site-authoring/references/seo.md +116 -0
- package/skills/deco-site-workflow/SKILL.md +101 -0
- package/skills/deco-site-workflow/references/check.md +116 -0
- package/skills/deco-site-workflow/references/cli-reference.md +106 -0
- package/skills/deco-site-workflow/references/content-layout.md +93 -0
- package/skills/deco-site-workflow/references/content-sync.md +146 -0
- package/skills/deco-site-workflow/references/delivery.md +51 -0
- package/skills/deco-site-workflow/references/deploy.md +87 -0
- package/skills/deco-site-workflow/references/schema.md +173 -0
- package/skills/deco-site-workflow/references/serve-and-studio.md +138 -0
- package/skills/deco-storefront-caching/SKILL.md +67 -0
- package/skills/deco-storefront-caching/references/cache-keys.md +129 -0
- package/skills/deco-storefront-caching/references/case-study.md +82 -0
- package/skills/deco-storefront-caching/references/egress-traps.md +153 -0
- package/skills/deco-storefront-caching/references/nextjs.md +60 -0
- package/skills/deco-storefront-caching/references/perf-guardrails-e2e.md +123 -0
- package/skills/deco-storefront-caching/references/verification.md +136 -0
- package/skills/deco-storefront-caching/references/worker-page-cache.md +160 -0
- package/skills/deco-storefront-caching/scripts/html-anatomy.mjs +97 -0
- package/skills/deco-storefront-performance/SKILL.md +81 -0
- package/skills/deco-storefront-performance/references/cls-third-party.md +90 -0
- package/skills/deco-storefront-performance/references/hydration.md +116 -0
- package/skills/deco-storefront-performance/references/loaders-n-plus-1.md +107 -0
- package/skills/deco-storefront-performance/references/navigation-ux.md +130 -0
- package/skills/deco-storefront-performance/references/payload-trim.md +163 -0
- package/skills/deco-storefront-performance/references/render-location.md +152 -0
- package/skills/deco-storefront-performance/references/request-dedupe.md +147 -0
- package/skills/deco-storefront-performance/references/trace-reading.md +79 -0
- package/skills/deco-storefront-performance/references/worker-memory.md +176 -0
- package/skills/deco-tanstack-site/SKILL.md +68 -0
- package/skills/deco-tanstack-site/references/document-and-security.md +155 -0
- package/skills/deco-tanstack-site/references/router-and-navigation.md +137 -0
- package/skills/deco-tanstack-site/references/routes-and-pages.md +183 -0
- package/skills/deco-tanstack-site/references/server-functions.md +123 -0
- package/skills/deco-tanstack-site/references/setup.md +153 -0
- package/skills/deco-tanstack-site/references/worker-entry.md +152 -0
- package/skills/deco-v7-to-v8-migration/SKILL.md +123 -0
- package/skills/deco-v7-to-v8-migration/references/caching-and-privacy.md +10 -0
- package/skills/deco-v7-to-v8-migration/references/content.md +25 -0
- package/skills/deco-v7-to-v8-migration/references/editor-forms.md +27 -0
- package/skills/deco-v7-to-v8-migration/references/faststore.md +40 -0
- package/skills/deco-v7-to-v8-migration/references/framework-code.md +53 -0
- package/skills/deco-v7-to-v8-migration/references/hosted-releases.md +16 -0
- package/skills/deco-v7-to-v8-migration/references/import-map.md +81 -0
- package/skills/deco-v7-to-v8-migration/references/legacy-names.md +33 -0
- package/skills/deco-v7-to-v8-migration/references/manual-steps.md +10 -0
- package/skills/deco-v7-to-v8-migration/references/native-apps.md +43 -0
- package/skills/deco-v7-to-v8-migration/references/nextjs.md +19 -0
- package/skills/deco-v7-to-v8-migration/references/parity.md +66 -0
- package/skills/deco-v7-to-v8-migration/references/rendering.md +13 -0
- package/skills/deco-v7-to-v8-migration/references/running-the-script.md +29 -0
- package/skills/deco-v7-to-v8-migration/references/script-steps.md +13 -0
- package/skills/deco-v7-to-v8-migration/references/server-functions.md +15 -0
- package/skills/deco-v7-to-v8-migration/references/sibling-port.md +11 -0
- package/skills/deco-v7-to-v8-migration/references/site-code.md +15 -0
- package/skills/deco-v7-to-v8-migration/references/telemetry.md +10 -0
- package/skills/deco-v7-to-v8-migration/references/verify.md +23 -0
- package/skills/deco-v7-to-v8-migration/scripts/apps.ts +297 -0
- package/skills/deco-v7-to-v8-migration/scripts/asyncRendering.ts +73 -0
- package/skills/deco-v7-to-v8-migration/scripts/blockMap.ts +584 -0
- package/skills/deco-v7-to-v8-migration/scripts/checkContentReads.ts +32 -0
- package/skills/deco-v7-to-v8-migration/scripts/ciSchemaCheck.ts +145 -0
- package/skills/deco-v7-to-v8-migration/scripts/compat.ts +357 -0
- package/skills/deco-v7-to-v8-migration/scripts/content.ts +121 -0
- package/skills/deco-v7-to-v8-migration/scripts/contentReads.ts +157 -0
- package/skills/deco-v7-to-v8-migration/scripts/experiments.ts +81 -0
- package/skills/deco-v7-to-v8-migration/scripts/framework.ts +61 -0
- package/skills/deco-v7-to-v8-migration/scripts/imageCopy.ts +276 -0
- package/skills/deco-v7-to-v8-migration/scripts/imageModule.ts +285 -0
- package/skills/deco-v7-to-v8-migration/scripts/imports.ts +942 -0
- package/skills/deco-v7-to-v8-migration/scripts/invoke.ts +624 -0
- package/skills/deco-v7-to-v8-migration/scripts/legacyNames.ts +45 -0
- package/skills/deco-v7-to-v8-migration/scripts/main.ts +59 -0
- package/skills/deco-v7-to-v8-migration/scripts/matchers.ts +41 -0
- package/skills/deco-v7-to-v8-migration/scripts/migrate.ts +180 -0
- package/skills/deco-v7-to-v8-migration/scripts/redirects.ts +455 -0
- package/skills/deco-v7-to-v8-migration/scripts/report.ts +50 -0
- package/skills/deco-v7-to-v8-migration/scripts/scaffold.ts +1119 -0
- package/skills/deco-v7-to-v8-migration/scripts/secrets.ts +35 -0
- package/skills/deco-v7-to-v8-migration/scripts/sectionLoaders.ts +216 -0
- package/skills/deco-v7-to-v8-migration/scripts/siteSettings.ts +261 -0
- package/skills/deco-v7-to-v8-migration/scripts/stubs.ts +388 -0
- package/skills/deco-v7-to-v8-migration/scripts/tsconfig.json +7 -0
- package/skills/deco-v7-to-v8-migration/scripts/vendor.ts +249 -0
- package/skills/deco-v7-to-v8-migration/scripts/vtexInvoke.ts +240 -0
- package/skills/deco-v7-to-v8-migration/scripts/walk.ts +30 -0
- package/skills/deco-variants/SKILL.md +57 -0
- package/skills/deco-variants/references/caching-variants.md +63 -0
- package/skills/deco-variants/references/custom-matchers.md +83 -0
- package/skills/deco-variants/references/draft-preview.md +59 -0
- package/skills/deco-variants/references/experiments-and-campaigns.md +104 -0
- package/skills/deco-variants/references/multivariate.md +85 -0
- package/skills/deco-variants/references/v7-matchers.md +71 -0
- package/src/index.ts +1 -1
- package/src/protocol/conformance/blockMetaVectors.json +80 -0
- package/src/protocol/index.ts +8 -1
- package/src/v8/blockMeta.ts +75 -11
- package/src/v8/cli/index.ts +1 -0
- package/src/v8/cli/run.ts +35 -1
- package/src/v8/cli/skills.ts +91 -0
- package/src/v8/client.ts +32 -77
- package/src/v8/cms.ts +1 -2
- package/src/v8/contentIndex.ts +49 -19
- package/src/v8/draftChanges.ts +5 -1
- package/src/v8/index.ts +1 -1
- package/src/v8/remoteLoader.ts +13 -3
- 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`).
|