@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,147 @@
|
|
|
1
|
+
# Troubleshooting images
|
|
2
|
+
|
|
3
|
+
Start from the symptom. Most checks need two things: the `src` stored in the
|
|
4
|
+
content (in `.deco/blocks` or the loader's output) and the URL the page actually
|
|
5
|
+
requested (DevTools, Network, filter "Img").
|
|
6
|
+
|
|
7
|
+
| Symptom | Likely cause | Section |
|
|
8
|
+
|---|---|---|
|
|
9
|
+
| Every image on the site is a bit soft | No tier, or `low`, in `decoCdn` | [Soft everywhere](#soft-everywhere) |
|
|
10
|
+
| One banner is pixelated, worse on phones and Retina screens | Source has fewer pixels than the slot needs | [Undersized source](#undersized-source) |
|
|
11
|
+
| A full-width hero is soft only on wide screens | `sizes` default says 50vw | [Wrong sizes](#wrong-sizes) |
|
|
12
|
+
| Images are huge (MBs) and slow | Source passes through unresized | [Not resized](#not-resized) |
|
|
13
|
+
| 404 or 508 on `/image?…` | Bad `src` inside the CDN URL | [Broken CDN URLs](#broken-cdn-urls) |
|
|
14
|
+
| Image blocked, console shows a CSP error | Host missing from `img-src` | [providers-and-cdn.md](./providers-and-cdn.md#hosts-for-csp-and-preconnect) |
|
|
15
|
+
| Mobile crop looks wrong, desktop fine | `Source` ratios differ per breakpoint | [Mobile crop](#mobile-crop) |
|
|
16
|
+
| Page jumps as images load | Missing `width`/`height` | [quality-and-lcp.md](./quality-and-lcp.md#preloading-the-lcp-image) |
|
|
17
|
+
|
|
18
|
+
## Soft everywhere
|
|
19
|
+
|
|
20
|
+
Look at the `quality` parameter on any requested `/image?…` URL.
|
|
21
|
+
|
|
22
|
+
- **No `quality` parameter**: the site's `decoCdn` has no `quality` option, so
|
|
23
|
+
the CDN default applies to every image. Set `decoCdn({ quality: "high" })`.
|
|
24
|
+
- **`quality=low`**: someone chose `low` site-wide. Raise it.
|
|
25
|
+
- **Not a Deco CDN URL at all**: the image came from a platform provider.
|
|
26
|
+
`vtexCatalogWebp` and `vtexFileManager` use VTEX's 1 to 10 scale (default
|
|
27
|
+
8); `vtexCatalog`, `vtexCatalogFrame` and `shopifyCdn` ignore quality.
|
|
28
|
+
|
|
29
|
+
A site-wide tier change touches every image URL, so the CDN cache refills
|
|
30
|
+
once. That is expected.
|
|
31
|
+
|
|
32
|
+
## Undersized source
|
|
33
|
+
|
|
34
|
+
The most common "distorted image" report is not stretching. It is a source with
|
|
35
|
+
fewer pixels than the slot needs on a high-density screen, upscaled by the
|
|
36
|
+
browser. Tell-tale sign: **sharp when the file is opened directly, pixelated on
|
|
37
|
+
the site.** Opening it shows its small native size; the site shows it larger.
|
|
38
|
+
|
|
39
|
+
**Mechanism.** `width` on `Image` or `Source` is the 1x CSS width. The srcset
|
|
40
|
+
also offers `2 × width`, and on a DPR 2 screen the browser takes that one. If
|
|
41
|
+
the uploaded file is smaller, the CDN or browser has to invent pixels. No
|
|
42
|
+
parameter fixes that: `quality: "original"` only adds bytes.
|
|
43
|
+
|
|
44
|
+
**Required source pixels = rendered CSS width × device pixel ratio.** Use 2x as
|
|
45
|
+
the target; most phones and laptops are DPR 2 or more.
|
|
46
|
+
|
|
47
|
+
### Diagnose
|
|
48
|
+
|
|
49
|
+
1. Measure the **original** file, not a resized URL. Take the `src` from the
|
|
50
|
+
content (before it went through `ImageUrl`) and download that:
|
|
51
|
+
|
|
52
|
+
```bash
|
|
53
|
+
curl -sL "<original src>" -o /tmp/orig
|
|
54
|
+
sips -g pixelWidth -g pixelHeight /tmp/orig # macOS; or: identify /tmp/orig
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
Measuring a `/image?width=1400…` URL reports 1400, the output size, which
|
|
58
|
+
hides the problem.
|
|
59
|
+
2. Read the `width` on the component. Each `Source` has its own:
|
|
60
|
+
|
|
61
|
+
```tsx
|
|
62
|
+
<Source media="(min-width: 1024px)" src={desktop} width={700} height={342} /> // needs 1400×684
|
|
63
|
+
<Source media="(max-width: 1023px)" src={mobile} width={375} height={184} /> // needs 750×368
|
|
64
|
+
```
|
|
65
|
+
3. Source width ≥ `width × 2`: sharp. Smaller: that is the bug. In one measured
|
|
66
|
+
case a 542px-wide file filled a slot that needed 1400px, a 2.6x upscale.
|
|
67
|
+
|
|
68
|
+
### Fix
|
|
69
|
+
|
|
70
|
+
Upload a larger source, at least 2x the slot, in the slot's aspect ratio. Larger
|
|
71
|
+
is fine: the CDN downscales, which never blurs.
|
|
72
|
+
|
|
73
|
+
These do **not** fix it:
|
|
74
|
+
|
|
75
|
+
- Changing `width`/`height` on the component. The slot on screen is the same,
|
|
76
|
+
so the browser upscales anyway.
|
|
77
|
+
- `quality: "original"`. No detail is added. Go back to `"high"`.
|
|
78
|
+
- Shrinking the component with CSS. It only helps below half the source width,
|
|
79
|
+
and it changes the design everywhere the component is used.
|
|
80
|
+
|
|
81
|
+
No larger original? An AI upscaler can help. Choose a scale that clears the
|
|
82
|
+
target (3x on 542px gives 1626px, above 1400; 2x gives 1084px, below). Check
|
|
83
|
+
fine detail (text, logos, small product features) before shipping. A real
|
|
84
|
+
high-resolution photo is always better.
|
|
85
|
+
|
|
86
|
+
Then stop it from happening again: put the 2x size in the field's
|
|
87
|
+
`@description` (see [components-per-binding.md](./components-per-binding.md#image-fields-in-section-props)).
|
|
88
|
+
|
|
89
|
+
### Explaining it to a non-technical stakeholder
|
|
90
|
+
|
|
91
|
+
> The image looks pixelated because the uploaded file is smaller than the space
|
|
92
|
+
> it fills. The banner needs 1400×684 px (750×368 px on mobile); the current file
|
|
93
|
+
> is 542×280 px, so the site has to stretch it. It looks sharp when you open the
|
|
94
|
+
> file because it is shown at its small original size there. Upload the image at
|
|
95
|
+
> the larger size, ideally the original high-resolution photo.
|
|
96
|
+
|
|
97
|
+
## Wrong sizes
|
|
98
|
+
|
|
99
|
+
`Image` defaults `sizes` to `"(max-width: 768px) 100vw, 50vw"`. On a 1440px
|
|
100
|
+
screen that tells the browser a full-width hero is 720 CSS px wide, so it may
|
|
101
|
+
pick the 1x candidate. Set `sizes` to the real layout (see
|
|
102
|
+
[quality-and-lcp.md](./quality-and-lcp.md#sizes-and-the-srcset)).
|
|
103
|
+
|
|
104
|
+
## Not resized
|
|
105
|
+
|
|
106
|
+
The requested URL equals the `src` in the content: no provider matched it.
|
|
107
|
+
|
|
108
|
+
- `imageUrl.isOptimizable(src)` returns false for it. Check in a test or a
|
|
109
|
+
console.
|
|
110
|
+
- `decoCdn()` without `sources` resizes only Deco-hosted URLs. For other hosts,
|
|
111
|
+
add the platform provider or use `decoCdn({ sources: "all" })`.
|
|
112
|
+
- A provider listed after `decoCdn({ sources: "all" })` never runs. Move it
|
|
113
|
+
earlier.
|
|
114
|
+
- `data:` URIs and empty strings are never resized, by design.
|
|
115
|
+
- On Next.js, a source no provider resizes goes to `fallback`, or is returned
|
|
116
|
+
unchanged. Pass `fallback: nextImageOptimizer` if you want Next to resize it.
|
|
117
|
+
- A relative path like `/assets/banner.jpg` is not a Deco-hosted URL, so the
|
|
118
|
+
default `decoCdn()` leaves it alone and the site serves the file as is. With
|
|
119
|
+
`sources: "all"` it becomes `src=/assets/banner.jpg` on the CDN. Check that the
|
|
120
|
+
CDN can serve such a URL before relying on it.
|
|
121
|
+
|
|
122
|
+
## Broken CDN URLs
|
|
123
|
+
|
|
124
|
+
- **`src=image` or `src=<cdn>/image`**: an already-resized URL was resized
|
|
125
|
+
again by older code. v8 `decoCdn` unwraps these. If you still see them, some
|
|
126
|
+
code builds CDN URLs by hand; switch it to `imageUrl`.
|
|
127
|
+
- **508 on `assets.decocms.com` or `decoims.com`**: the `src` points back at
|
|
128
|
+
`decoims.com`, and the CDN fetches itself. `decoCdn` strips `decoims.com`
|
|
129
|
+
from sources when it is in `legacyHosts` (the default on those domains). With
|
|
130
|
+
a custom `legacyHosts: []` on `assets.decocms.com` and `sources: "all"`, a
|
|
131
|
+
`decoims.com` source is sent whole as `src=` and the loop comes back.
|
|
132
|
+
- **404 with a valid-looking `src`**: characters like `%`, `&`, `#`, `+` in a
|
|
133
|
+
file name. `decoCdn` escapes them only when it unwraps a nested URL; rename
|
|
134
|
+
such files when you upload them. The v8 upload endpoint already does (see
|
|
135
|
+
[asset-upload.md](./asset-upload.md)).
|
|
136
|
+
- **The query string on the source disappeared**: `decoCdn` drops everything
|
|
137
|
+
after `?` in `src`. A source that needs its query (signed URLs) must not go
|
|
138
|
+
through `decoCdn`; give it its own provider or leave it unmatched.
|
|
139
|
+
|
|
140
|
+
## Mobile crop
|
|
141
|
+
|
|
142
|
+
A `Picture` has a `Source` per media query, each with its own `width` and
|
|
143
|
+
`height`, so the ratio can differ. With `fit: "cover"` (the default) the CDN
|
|
144
|
+
crops to that ratio. A common bug: desktop is 700×342 (about 2:1) and mobile
|
|
145
|
+
is 350×350, so the mobile photo is cropped to a square. Decide the intended
|
|
146
|
+
mobile shape by looking at the live mobile render (emulate the device and DPR,
|
|
147
|
+
take a screenshot), then make the `Source` and the uploaded file agree.
|
|
@@ -0,0 +1,122 @@
|
|
|
1
|
+
# Video
|
|
2
|
+
|
|
3
|
+
v8 ships **no `Video` component**. Neither `@decocms/tanstack` nor
|
|
4
|
+
`@decocms/nextjs` has one, and `@decocms/blocks/image` is for images only.
|
|
5
|
+
Render a plain `<video>`.
|
|
6
|
+
|
|
7
|
+
Two layers decide whether a video plays with sound, and they are independent:
|
|
8
|
+
|
|
9
|
+
1. **The file.** Does the served file contain an audio track? For videos on the
|
|
10
|
+
Deco media host, that depends on the URL (below).
|
|
11
|
+
2. **The player.** Is the `<video>` muted, and does it autoplay? That is HTML
|
|
12
|
+
attributes and browser policy.
|
|
13
|
+
|
|
14
|
+
## The media host strips audio by default
|
|
15
|
+
|
|
16
|
+
Videos uploaded to Deco and served from `decoims.com` come without the audio
|
|
17
|
+
track unless the URL asks for it. This is behavior of the media host, not of the
|
|
18
|
+
v8 packages, so verify it on your URL (below).
|
|
19
|
+
|
|
20
|
+
| URL | Audio track | Size in one measured case |
|
|
21
|
+
|---|---|---|
|
|
22
|
+
| `…/video.mp4` | removed | 3.08 MB |
|
|
23
|
+
| `…/video.mp4?muted=true` | removed | 3.08 MB |
|
|
24
|
+
| `…/video.mp4?muted=false` | present | 3.59 MB |
|
|
25
|
+
|
|
26
|
+
The silent version is a different, smaller file. No player setting brings sound
|
|
27
|
+
back to it. Each variant is cached under its own URL, so switching to
|
|
28
|
+
`?muted=false` fetches a separate file with no cache-busting needed.
|
|
29
|
+
|
|
30
|
+
Verify with two requests and compare sizes:
|
|
31
|
+
|
|
32
|
+
```bash
|
|
33
|
+
curl -sI "<video url>" | grep -i content-length
|
|
34
|
+
curl -sI "<video url>?muted=false" | grep -i content-length
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
The `?muted=false` response should be larger.
|
|
38
|
+
|
|
39
|
+
## Do not send video through `ImageUrl`
|
|
40
|
+
|
|
41
|
+
`decoCdn` builds `https://<domain>/image?…&src=<path>` and keeps only the part
|
|
42
|
+
of `src` before `?`. A video passed to `Image`, `useImageUrl()` or the next/image
|
|
43
|
+
loader becomes an image request and loses `?muted=false`. Use the stored URL
|
|
44
|
+
as is.
|
|
45
|
+
|
|
46
|
+
## Browser autoplay
|
|
47
|
+
|
|
48
|
+
Browsers block autoplay with sound in most cases; muted video autoplays. To
|
|
49
|
+
play with sound, plan for a user action (a click on `controls` or your own
|
|
50
|
+
button). This is browser policy; no URL or attribute changes it.
|
|
51
|
+
|
|
52
|
+
| Goal | File URL | `<video>` attributes |
|
|
53
|
+
|---|---|---|
|
|
54
|
+
| Silent background loop | default (no param) | `autoPlay muted loop playsInline` |
|
|
55
|
+
| Plays with sound when the user starts it | `?muted=false` | `controls`, no `autoPlay` |
|
|
56
|
+
| Autoplays silently, user can unmute | `?muted=false` | `autoPlay muted loop playsInline` plus a button that sets `video.muted = false` |
|
|
57
|
+
|
|
58
|
+
`playsInline` stops iOS from going fullscreen on play.
|
|
59
|
+
|
|
60
|
+
```tsx
|
|
61
|
+
import type { ImageWidget, VideoWidget } from "@decocms/compat-v7/types/widgets";
|
|
62
|
+
import { useImageUrl } from "@decocms/tanstack/react";
|
|
63
|
+
|
|
64
|
+
interface Props {
|
|
65
|
+
/** @description MP4 or WebM */
|
|
66
|
+
video: VideoWidget;
|
|
67
|
+
poster?: ImageWidget;
|
|
68
|
+
sound?: boolean;
|
|
69
|
+
}
|
|
70
|
+
|
|
71
|
+
function withSound(src: string) {
|
|
72
|
+
if (!/^https?:\/\//.test(src)) return src; // relative paths: leave alone
|
|
73
|
+
const url = new URL(src);
|
|
74
|
+
url.searchParams.set("muted", "false");
|
|
75
|
+
return url.href;
|
|
76
|
+
}
|
|
77
|
+
|
|
78
|
+
export default function HeroVideo({ video, poster, sound }: Props) {
|
|
79
|
+
const imageUrl = useImageUrl();
|
|
80
|
+
return (
|
|
81
|
+
<video
|
|
82
|
+
src={sound ? withSound(video) : video}
|
|
83
|
+
poster={poster ? imageUrl(poster, { width: 1280, height: 720 }) : undefined}
|
|
84
|
+
width={1280}
|
|
85
|
+
height={720}
|
|
86
|
+
autoPlay
|
|
87
|
+
muted
|
|
88
|
+
loop
|
|
89
|
+
playsInline
|
|
90
|
+
preload="metadata"
|
|
91
|
+
/>
|
|
92
|
+
);
|
|
93
|
+
}
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
Notes on the example:
|
|
97
|
+
|
|
98
|
+
- `withSound` only makes sense for media-host URLs. Other hosts may ignore or
|
|
99
|
+
reject the parameter.
|
|
100
|
+
- The poster is an image, so it does go through `ImageUrl`.
|
|
101
|
+
- `width` and `height` reserve the box, as with images.
|
|
102
|
+
- `preload="metadata"` avoids downloading the whole file before play. For a
|
|
103
|
+
hero video that is the LCP element, consider the poster as the LCP image and
|
|
104
|
+
preload that instead.
|
|
105
|
+
|
|
106
|
+
## Video fields
|
|
107
|
+
|
|
108
|
+
`VideoWidget` (from `@decocms/compat-v7/types/widgets`) or `@format video-uri`
|
|
109
|
+
on a string gives the field a video picker. `deco check` accepts any string
|
|
110
|
+
there, so it will not catch a broken video URL.
|
|
111
|
+
|
|
112
|
+
## "The video has no sound"
|
|
113
|
+
|
|
114
|
+
1. **Check the URL.** If it is a media-host URL without `?muted=false`, the
|
|
115
|
+
served file has no audio. Add the parameter.
|
|
116
|
+
2. **Check the player.** If the URL has `?muted=false` and it is still silent,
|
|
117
|
+
the element is `muted` (required for autoplay). Add `controls` or an unmute
|
|
118
|
+
button.
|
|
119
|
+
3. **Check the code path.** If the rendered `src` is an `/image?…` URL, the
|
|
120
|
+
video went through `ImageUrl`. Render the stored URL directly.
|
|
121
|
+
4. **Verify** by opening the `?muted=false` URL in a tab: it should play with
|
|
122
|
+
sound.
|
|
@@ -0,0 +1,94 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: deco-make-editable
|
|
3
|
+
description: "@decocms/blocks 8: turn a hardcoded site, or a Figma design, into blocks that people edit in deco Studio, without changing how the site looks. Covers the inventory of content vs interface, the three content shapes (global blocks read by name, composed pages of type page, collections read with client.entries), the foo/fooPt bilingual field convention, seeding .deco/blocks from the existing code and sending it with deco push --draft and deco check --draft, implementing sections from a Figma file with the Figma MCP tools, pixel-parity checks with Playwright, accessibility and functional checks, and working in small PRs. Load it when asked to make a site, page, menu, footer or landing editable in Studio, to move hardcoded text into the CMS, to handle two languages in CMS content, or to build a Figma design as editable sections on a v8 site."
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Make a site editable in Studio
|
|
7
|
+
|
|
8
|
+
The goal is not "move strings into JSON". It is two things at once:
|
|
9
|
+
|
|
10
|
+
1. Someone who is not a developer opens Studio, changes a text, a link or the
|
|
11
|
+
order of sections, publishes, and the site changes.
|
|
12
|
+
2. The site renders exactly as it did before the conversion.
|
|
13
|
+
|
|
14
|
+
Every step serves one of those two halves. The same method works when the
|
|
15
|
+
starting point is a Figma file instead of a hardcoded site: build the sections
|
|
16
|
+
from the design, then seed them with the design's content.
|
|
17
|
+
|
|
18
|
+
This skill is about method. For the v8 mechanics it relies on, load the skill
|
|
19
|
+
that owns them:
|
|
20
|
+
|
|
21
|
+
- `deco-site-authoring`: writing sections, pages and loaders.
|
|
22
|
+
- `deco-cms-schema`: how a `Props` type becomes the Studio form (JSDoc tags,
|
|
23
|
+
widgets, shapes that break the form).
|
|
24
|
+
- `deco-site-workflow`: the `deco` CLI, where content lives, drafts and
|
|
25
|
+
publishing, and what to check when Studio cannot see the site.
|
|
26
|
+
- `deco-tanstack-site` or `deco-nextjs-site`: the routes and the worker.
|
|
27
|
+
|
|
28
|
+
## When to load what
|
|
29
|
+
|
|
30
|
+
| Reference | Load it when |
|
|
31
|
+
|---|---|
|
|
32
|
+
| [`references/inventory.md`](./references/inventory.md) | Starting: deciding what goes to the CMS, what stays in code, and the order of PRs |
|
|
33
|
+
| [`references/content-shapes.md`](./references/content-shapes.md) | Choosing between a global block, a composed page and a collection, and wiring each one |
|
|
34
|
+
| [`references/i18n-fields.md`](./references/i18n-fields.md) | The site has two languages and the content must be edited in both |
|
|
35
|
+
| [`references/seeding-content.md`](./references/seeding-content.md) | Writing the first `.deco/blocks` files from the current code, sending them as a draft, and the order of publish and deploy |
|
|
36
|
+
| [`references/from-figma.md`](./references/from-figma.md) | The starting point is a Figma file: mapping frames to sections, tokens, assets |
|
|
37
|
+
| [`references/pixel-parity.md`](./references/pixel-parity.md) | Proving a PR changes nothing visible: HTML diff, screenshot diff, Figma comparison, live edit |
|
|
38
|
+
| [`references/a11y-and-e2e.md`](./references/a11y-and-e2e.md) | Before calling a section or a page done: accessibility and functional checks |
|
|
39
|
+
|
|
40
|
+
## The loop, per content area
|
|
41
|
+
|
|
42
|
+
Work in small PRs, one content area at a time (menu, then home, then
|
|
43
|
+
landings). Each PR goes through the same loop:
|
|
44
|
+
|
|
45
|
+
1. **Inventory** the area: which texts, links and lists are content.
|
|
46
|
+
2. **Shape** each piece: global block, composed page or collection.
|
|
47
|
+
3. **Type** the props and add the block to the block map (`.deco/index.ts`, or
|
|
48
|
+
`.deco/index.tsx` when it holds JSX). Run `deco schema`.
|
|
49
|
+
4. **Seed** `.deco/blocks` from the current code, never by retyping.
|
|
50
|
+
5. **Check** with `deco check` (content in git, no `DECO_SITE`) or
|
|
51
|
+
`deco push --draft=<name>` then `deco check --draft=<name>` (a hosted site).
|
|
52
|
+
6. **Prove parity**: the page on the branch and on `main` render the same
|
|
53
|
+
HTML and the same pixels, at desktop and mobile widths, in every language.
|
|
54
|
+
7. **Live edit**: change the content and see the change land on the right
|
|
55
|
+
page and language only.
|
|
56
|
+
|
|
57
|
+
A PR that is not pixel-identical to `main` does not merge. That rule is what
|
|
58
|
+
lets a conversion run for weeks without anyone noticing it on the live site.
|
|
59
|
+
|
|
60
|
+
## v8 facts this skill relies on
|
|
61
|
+
|
|
62
|
+
These are true of the packages in this repo and change how the v7 version of
|
|
63
|
+
this method worked.
|
|
64
|
+
|
|
65
|
+
- **Studio lists only what the block map lists.** A block type exists because
|
|
66
|
+
`.deco/index.ts` exports a function under that key. Components that are not
|
|
67
|
+
in the map never show up in Studio's section picker, so there is no folder
|
|
68
|
+
to keep clean.
|
|
69
|
+
- **The form comes from the function's input type.** `deco schema` reads the
|
|
70
|
+
first parameter's type of each function in the map and writes
|
|
71
|
+
`.deco/schema.gen.json`. A function that returns JSX or a
|
|
72
|
+
`{ component, props }` descriptor is a section; one that returns its own
|
|
73
|
+
input is content (grouped with pages when the type extends `Route`).
|
|
74
|
+
- **Block functions get only their saved input.** `currentClient()` inside one
|
|
75
|
+
knows the visitor and the version, not the URL. Anything that depends on the
|
|
76
|
+
path (such as the language) is added by the site's code that renders the
|
|
77
|
+
result, not by the block function.
|
|
78
|
+
- **Results are read-only.** A client runs each block function once per
|
|
79
|
+
distinct input and hands the same object to every place that uses it. Copy
|
|
80
|
+
before you change a result (the `localize` helper in
|
|
81
|
+
[i18n-fields.md](./references/i18n-fields.md) builds a new object).
|
|
82
|
+
- **There is no locale in the CMS.** Two languages are a site convention (see
|
|
83
|
+
[i18n-fields.md](./references/i18n-fields.md)).
|
|
84
|
+
- **The CLI has no asset upload command.** How images get to the site is
|
|
85
|
+
covered in `deco-images-media`.
|
|
86
|
+
|
|
87
|
+
## Rules for this skill
|
|
88
|
+
|
|
89
|
+
- Never retype content. Extract it from the code with a script.
|
|
90
|
+
- No fallback copy of the content in code. A constant fallback becomes a
|
|
91
|
+
second source of truth that drifts from what editors see.
|
|
92
|
+
- Do not publish a draft (`deco publish`) without the site owner's explicit
|
|
93
|
+
OK for that publish.
|
|
94
|
+
- Anything specific to one store goes in that store's own notes, not here.
|
|
@@ -0,0 +1,104 @@
|
|
|
1
|
+
# Accessibility and functional checks
|
|
2
|
+
|
|
3
|
+
Pixel parity proves a section looks right with today's content. These checks
|
|
4
|
+
prove it works, for every visitor, and keeps working when editors change the
|
|
5
|
+
content.
|
|
6
|
+
|
|
7
|
+
Deeper checklists live in other skills; this file lists what a conversion or a
|
|
8
|
+
Figma build must not skip:
|
|
9
|
+
|
|
10
|
+
- `deco-go-live`: a QA checklist built from the site's blocks and routes.
|
|
11
|
+
- `deco-images-media` and `deco-storefront-performance`: images, LCP, CLS,
|
|
12
|
+
heavy HTML.
|
|
13
|
+
|
|
14
|
+
## Content robustness
|
|
15
|
+
|
|
16
|
+
Editors will do things the design never showed. For each section, try:
|
|
17
|
+
|
|
18
|
+
- every optional field empty: no empty heading tag, no dangling separator, no
|
|
19
|
+
broken layout;
|
|
20
|
+
- a text three times longer than the design's, and a one-word one;
|
|
21
|
+
- a list with zero items, one item, and more items than the design shows;
|
|
22
|
+
- a section removed, and the same section added twice to one page;
|
|
23
|
+
- an image with a different aspect ratio than the design's.
|
|
24
|
+
|
|
25
|
+
A section that renders nothing when its main content is empty is better than
|
|
26
|
+
one that renders an empty box. A section added twice must not reuse an `id`
|
|
27
|
+
(two `id="faq"` break anchors and `aria-controls`).
|
|
28
|
+
|
|
29
|
+
## Accessibility
|
|
30
|
+
|
|
31
|
+
- **Headings:** one `h1` per page, then `h2` and `h3` in order. A section's
|
|
32
|
+
heading level must not depend on where an editor puts it: when a section can
|
|
33
|
+
be first on a page (and become the `h1`), give it a prop for the level or
|
|
34
|
+
keep the `h1` in a section that only goes first.
|
|
35
|
+
- **Images:** every content image has `alt` text, and the `alt` is a field
|
|
36
|
+
next to the image in the form. Decorative images have `alt=""`.
|
|
37
|
+
- **Links and buttons:** every icon-only control has an accessible name
|
|
38
|
+
(`aria-label`, kept in code). Links that open a new tab say so to screen
|
|
39
|
+
readers.
|
|
40
|
+
- **Contrast:** WCAG AA, 4.5:1 for normal text, 3:1 for large text and UI
|
|
41
|
+
parts. When editors choose colors or put text over an image they choose,
|
|
42
|
+
contrast is their choice: add an overlay or a text color option to the
|
|
43
|
+
section instead of trusting each image.
|
|
44
|
+
- **Keyboard:** every interactive element is reachable with Tab, shows a
|
|
45
|
+
visible focus ring, and works with Enter or Space. Menus and drawers close
|
|
46
|
+
with Escape and return focus to the button that opened them.
|
|
47
|
+
- **Language:** `<html lang>` matches the page's language on a two-language
|
|
48
|
+
site (`DecoDocument` takes a `lang` prop on TanStack Start).
|
|
49
|
+
- A skip link to the main content, when the header has many links.
|
|
50
|
+
|
|
51
|
+
Run an automated pass (axe or Lighthouse) on each converted page as a floor,
|
|
52
|
+
not as proof.
|
|
53
|
+
|
|
54
|
+
## Functional checks
|
|
55
|
+
|
|
56
|
+
Walk each converted page on desktop (1440px) and mobile (375px or 390px).
|
|
57
|
+
|
|
58
|
+
**Header and navigation**
|
|
59
|
+
|
|
60
|
+
- The logo links home. Every menu link goes where its `href` says, with the
|
|
61
|
+
locale prefix on secondary-language pages.
|
|
62
|
+
- Dropdowns or mega menus open on hover and on keyboard focus.
|
|
63
|
+
- Mobile: the menu button opens the drawer, nested items expand and collapse,
|
|
64
|
+
the drawer closes on navigation and on a backdrop tap.
|
|
65
|
+
- A sticky header does not cover anchored headings (`scroll-margin-top`).
|
|
66
|
+
|
|
67
|
+
**Content sections**
|
|
68
|
+
|
|
69
|
+
- Calls to action link to the right page. External links open in a new tab.
|
|
70
|
+
- Carousels: arrows and dots work, swipe works on mobile, autoplay stops on
|
|
71
|
+
hover and focus.
|
|
72
|
+
- Accordions and tabs work with the keyboard.
|
|
73
|
+
- Forms (newsletter, contact) submit, show success and error states, and
|
|
74
|
+
keep their messages in code, not in a block.
|
|
75
|
+
|
|
76
|
+
**Footer**
|
|
77
|
+
|
|
78
|
+
- Every link column renders and links work. Social and payment icons render.
|
|
79
|
+
- Mobile: columns stack or collapse as designed.
|
|
80
|
+
|
|
81
|
+
**Mobile**
|
|
82
|
+
|
|
83
|
+
- Touch targets are at least 44×44px.
|
|
84
|
+
- No horizontal scroll at 375px.
|
|
85
|
+
- Body text is at least 16px.
|
|
86
|
+
- Fixed or sticky bars do not hide content.
|
|
87
|
+
|
|
88
|
+
## Performance, briefly
|
|
89
|
+
|
|
90
|
+
- The page's LCP image uses `preload`; every other image loads lazily.
|
|
91
|
+
- Every image has `width` and `height`, so nothing shifts while it loads.
|
|
92
|
+
- Deferring sections far below the fold (the built-in `lazy` block, loading
|
|
93
|
+
skeletons) is covered in `deco-site-authoring`.
|
|
94
|
+
- Compare the HTML size of a converted page with `main`. Content from a block
|
|
95
|
+
should not make a page heavier than the hardcoded version.
|
|
96
|
+
|
|
97
|
+
## Automate what you repeat
|
|
98
|
+
|
|
99
|
+
When a check runs on every PR (menu links, the mobile drawer, the CTA
|
|
100
|
+
targets), write it as a Playwright test against the dev server. Keep the tests
|
|
101
|
+
on behavior and roles (`getByRole("navigation")`, `getByRole("button", { name:
|
|
102
|
+
"Open menu" })` for interface text kept in code), not on CSS classes or
|
|
103
|
+
positions, so an editor reordering sections or rewording a heading does not
|
|
104
|
+
break them.
|
|
@@ -0,0 +1,203 @@
|
|
|
1
|
+
# The three content shapes
|
|
2
|
+
|
|
3
|
+
Every piece of content from the [inventory](./inventory.md) takes one of three
|
|
4
|
+
shapes. Pick the shape first; the code follows from it.
|
|
5
|
+
|
|
6
|
+
| Shape | Use for | Saved as | Read with |
|
|
7
|
+
|---|---|---|---|
|
|
8
|
+
| **Global block** | Things on every page: header menu, footer, a top banner | One saved block with a fixed name, e.g. `.deco/blocks/Header%20menu.json` | `client.resolve("Header menu")` in a loader shared by every page |
|
|
9
|
+
| **Composed page** | Pages editors rearrange: home, landings | A saved block of type `page` with `name`, `path`, `seo` and `sections` | `client.routes()` + `matchRoute`, then `client.resolve(name)` |
|
|
10
|
+
| **Collection** | Many documents of one kind: articles, FAQ entries, store addresses | One saved block per document, all of one type | `client.entries(type)` for names and paths (index only), then `client.resolve(name)` per document shown |
|
|
11
|
+
|
|
12
|
+
A saved block's file name is `encodeURIComponent(name) + ".json"`, so the
|
|
13
|
+
block named `Header menu` lives in `Header%20menu.json`. Subfolders of
|
|
14
|
+
`.deco/blocks` are not read. A saved block cannot take the name of a block
|
|
15
|
+
type or a built-in (`page`, `lazy`, `multivariate`, …): `deco check` reports
|
|
16
|
+
it.
|
|
17
|
+
|
|
18
|
+
The site wiring around these (the client, the catch-all route, the worker) is
|
|
19
|
+
in `deco-tanstack-site` or `deco-nextjs-site`. The examples below assume a
|
|
20
|
+
TanStack Start site with `src/cms.ts` exporting `cms` from `createCMS`, as in
|
|
21
|
+
`examples/tanstack-worker-smoke`.
|
|
22
|
+
|
|
23
|
+
## Sections: JSX or descriptors
|
|
24
|
+
|
|
25
|
+
A block function that returns JSX, or a `{ component, props }` object, is a
|
|
26
|
+
section: Studio offers it wherever a section fits. `tanstack-smoke` and
|
|
27
|
+
`tanstack-worker-smoke` in `examples/` return descriptors, because a server
|
|
28
|
+
function's result must be serialized; the site maps each descriptor to its
|
|
29
|
+
component when it renders. The Next.js examples and `tanstack-rsc-smoke`
|
|
30
|
+
(server components) return JSX from the block map (`.deco/index.tsx`).
|
|
31
|
+
|
|
32
|
+
```ts
|
|
33
|
+
// .deco/index.ts
|
|
34
|
+
import type { Blocks, Seo } from "@decocms/blocks";
|
|
35
|
+
import type { HeaderMenuProps } from "../src/sections/HeaderMenu";
|
|
36
|
+
import type { HeroProps } from "../src/sections/Hero";
|
|
37
|
+
|
|
38
|
+
export type Section =
|
|
39
|
+
| { component: "header-menu"; props: HeaderMenuProps }
|
|
40
|
+
| { component: "hero"; props: HeroProps };
|
|
41
|
+
|
|
42
|
+
export default {
|
|
43
|
+
seo: (input: Seo) => input,
|
|
44
|
+
"header-menu": (input: HeaderMenuProps): Section => ({ component: "header-menu", props: input }),
|
|
45
|
+
hero: (input: HeroProps): Section => ({ component: "hero", props: input }),
|
|
46
|
+
} satisfies Blocks;
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
Run `deco schema` after every change to a `Props` type, and commit the
|
|
50
|
+
regenerated `.deco/schema.gen.json`. In CI, `deco schema --check` fails when
|
|
51
|
+
the file is out of date.
|
|
52
|
+
|
|
53
|
+
## Global blocks
|
|
54
|
+
|
|
55
|
+
One saved block per piece, named for what editors call it:
|
|
56
|
+
|
|
57
|
+
```json
|
|
58
|
+
// .deco/blocks/Header%20menu.json
|
|
59
|
+
{
|
|
60
|
+
"__resolveType": "header-menu",
|
|
61
|
+
"links": [
|
|
62
|
+
{ "label": "Pricing", "href": "/pricing" },
|
|
63
|
+
{ "label": "Docs", "href": "/docs" }
|
|
64
|
+
]
|
|
65
|
+
}
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
Read it once per request, in a loader every page shares (the root route on
|
|
69
|
+
TanStack Start), and hand the result to the layout:
|
|
70
|
+
|
|
71
|
+
```ts
|
|
72
|
+
// src/global-blocks.functions.ts
|
|
73
|
+
import { createServerFn } from "@tanstack/react-start";
|
|
74
|
+
import { contentClient } from "@decocms/tanstack/server";
|
|
75
|
+
import type { Section } from "../.deco";
|
|
76
|
+
import { cms } from "./cms";
|
|
77
|
+
|
|
78
|
+
const GLOBAL_BLOCKS = ["Header menu", "Footer"] as const;
|
|
79
|
+
|
|
80
|
+
export const loadGlobalBlocks = createServerFn({ method: "GET" }).handler(async () => {
|
|
81
|
+
const client = contentClient(cms);
|
|
82
|
+
const results = await Promise.all(GLOBAL_BLOCKS.map((name) => client.resolve<Section>(name)));
|
|
83
|
+
return Object.fromEntries(
|
|
84
|
+
GLOBAL_BLOCKS.map((name, i) => {
|
|
85
|
+
const [value, error] = results[i]!;
|
|
86
|
+
if (error) console.error(name, error);
|
|
87
|
+
return [name, value ?? null];
|
|
88
|
+
}),
|
|
89
|
+
) as Record<(typeof GLOBAL_BLOCKS)[number], Section | null>;
|
|
90
|
+
});
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
What held up in practice:
|
|
94
|
+
|
|
95
|
+
- **List the global block names in one place.** A missing block then shows up
|
|
96
|
+
as one `null` you can test for, not as a header that silently renders empty.
|
|
97
|
+
- **No fallback copy in code.** When a block cannot be read, render nothing (or
|
|
98
|
+
the section's empty state) and log the error. A constant with the old menu
|
|
99
|
+
becomes a second source of truth that drifts from what editors see.
|
|
100
|
+
- **Derive what editors should not manage.** The active menu item comes from
|
|
101
|
+
comparing `href` with the current path, not from an extra field.
|
|
102
|
+
- **External links** in CMS lists still need `target="_blank"` and
|
|
103
|
+
`rel="noopener noreferrer"`. Set them in the component from the URL, not
|
|
104
|
+
from a field editors can forget.
|
|
105
|
+
|
|
106
|
+
## Composed pages
|
|
107
|
+
|
|
108
|
+
A page is a saved block of the built-in type `page`. Its `sections` are the
|
|
109
|
+
blocks editors add, remove and reorder:
|
|
110
|
+
|
|
111
|
+
```json
|
|
112
|
+
// .deco/blocks/Home.json
|
|
113
|
+
{
|
|
114
|
+
"__resolveType": "page",
|
|
115
|
+
"name": "Home",
|
|
116
|
+
"path": "/",
|
|
117
|
+
"seo": { "__resolveType": "seo", "title": "…", "description": "…" },
|
|
118
|
+
"sections": [
|
|
119
|
+
{ "__resolveType": "hero", "title": "…", "cta": { "label": "…", "href": "/start" } },
|
|
120
|
+
{ "__resolveType": "guides", "items": [] }
|
|
121
|
+
]
|
|
122
|
+
}
|
|
123
|
+
```
|
|
124
|
+
|
|
125
|
+
The page loader in `examples/tanstack-worker-smoke/src/open-page.server.ts`
|
|
126
|
+
does the rest: `client.routes()` lists every page's `{ name, path }` from the
|
|
127
|
+
index, `matchRoute(href, { routes })` picks one, and `client.resolve(name, {
|
|
128
|
+
run: false })` reads it, then each section resolves on its own so a slow one
|
|
129
|
+
does not hold the others. `deco-tanstack-site` covers the catch-all route that
|
|
130
|
+
calls it.
|
|
131
|
+
|
|
132
|
+
**Keep your routes.** You do not have to hand the whole site to a catch-all
|
|
133
|
+
route to get CMS pages. A site with content files, locale prefixes or
|
|
134
|
+
redirects of its own can keep its file routes and call the same page loader
|
|
135
|
+
only in the routes that are now CMS pages (`loadPage({ data: { href: "/" } })`
|
|
136
|
+
in `src/routes/index.tsx`). On TanStack Router a file route such as `/` ranks
|
|
137
|
+
above the `$` catch-all, so converting one route never changes the others.
|
|
138
|
+
|
|
139
|
+
**Keep the frame in code.** The header and footer around a page stay in the
|
|
140
|
+
layout, fed by global blocks. A page's `sections` hold only what changes from
|
|
141
|
+
page to page.
|
|
142
|
+
|
|
143
|
+
**Render no wrapper you did not have.** The site writes the loop that renders
|
|
144
|
+
each section. If the old page had no element around each section, do not add
|
|
145
|
+
one: an extra `<div>` breaks CSS such as `.page > section` and fails the
|
|
146
|
+
[HTML parity](./pixel-parity.md) check.
|
|
147
|
+
|
|
148
|
+
**The tab title can come from the page.** The `page` block's `seo` field takes
|
|
149
|
+
any block that returns a `Seo` (`{ title, description }`), such as the `seo`
|
|
150
|
+
block in the map above. A page without one falls back to the root route's
|
|
151
|
+
defaults.
|
|
152
|
+
|
|
153
|
+
## Collections
|
|
154
|
+
|
|
155
|
+
A collection is a block type whose function returns its own input, with one
|
|
156
|
+
saved block per document:
|
|
157
|
+
|
|
158
|
+
```ts
|
|
159
|
+
// src/post.ts
|
|
160
|
+
import type { Route } from "@decocms/blocks";
|
|
161
|
+
|
|
162
|
+
export interface Post extends Route {
|
|
163
|
+
/**
|
|
164
|
+
* @title Published on
|
|
165
|
+
* @format date
|
|
166
|
+
*/
|
|
167
|
+
date: string;
|
|
168
|
+
/** @format rich-text */
|
|
169
|
+
body: string;
|
|
170
|
+
}
|
|
171
|
+
|
|
172
|
+
// .deco/index.ts
|
|
173
|
+
post: (input: Post) => input,
|
|
174
|
+
```
|
|
175
|
+
|
|
176
|
+
Because `Post` extends `Route` (`name` and `path`), `deco schema` puts the
|
|
177
|
+
type in the `pages` group and `deco check` reports two posts with conflicting
|
|
178
|
+
paths. A type without `path` is plain content that only the site's code reads.
|
|
179
|
+
|
|
180
|
+
`client.routes()` lists only blocks of type `page`, not posts. To give each
|
|
181
|
+
post its own URL, list the posts and match them together with the pages, as
|
|
182
|
+
`examples/nextjs-binding-smoke/src/open-page.server.ts` does:
|
|
183
|
+
`matchRoute(href, { routes: [...routes, ...posts] })`.
|
|
184
|
+
|
|
185
|
+
List them with `client.entries`, which reads only the content index (names,
|
|
186
|
+
types, paths, references, `noIndex`), and resolve the documents you show:
|
|
187
|
+
|
|
188
|
+
```ts
|
|
189
|
+
const [entries, error] = await client.entries("post");
|
|
190
|
+
if (error) throw error;
|
|
191
|
+
const posts = await Promise.all(
|
|
192
|
+
entries.slice(0, 20).map(async ({ name }) => (await client.resolve<Post>(name))[0]),
|
|
193
|
+
);
|
|
194
|
+
```
|
|
195
|
+
|
|
196
|
+
`entries` is sorted by block name and costs no block fetch however many
|
|
197
|
+
documents there are; each `resolve(name)` reads one body. Sort by a field of
|
|
198
|
+
the body (a date) only over the documents you resolved, or put the sort key in
|
|
199
|
+
the name. For pages, route with `client.routes()` and `client.redirects()`.
|
|
200
|
+
There is no working `client.list()`: it was removed (it fetched every block of
|
|
201
|
+
the type) and throws, naming these replacements.
|
|
202
|
+
|
|
203
|
+
See `examples/nextjs-binding-smoke/src/app/blog/page.tsx` for a list page.
|