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