@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,190 @@
|
|
|
1
|
+
# Setup
|
|
2
|
+
|
|
3
|
+
How a Next.js App Router app becomes a v8 Deco site. The reference app is
|
|
4
|
+
`examples/nextjs-binding-smoke`; copy from it rather than from memory.
|
|
5
|
+
|
|
6
|
+
## Packages
|
|
7
|
+
|
|
8
|
+
| Package | Why |
|
|
9
|
+
|---|---|
|
|
10
|
+
| `@decocms/blocks` | The CMS (`createCMS`, `matchRoute`, types), the `deco` CLI (its `bin`), `@decocms/blocks/image` |
|
|
11
|
+
| `@decocms/nextjs` | The Next helpers. Same version as `@decocms/blocks` |
|
|
12
|
+
| `next` 16, `react` 19 | Peers of `@decocms/nextjs` (Node 24 or later). Install `react-dom` 19 with them, as any Next app does |
|
|
13
|
+
| `server-only` | Optional. The example marks its server modules with it |
|
|
14
|
+
| `@opentelemetry/api` | Optional peer, for the request metric only |
|
|
15
|
+
|
|
16
|
+
`@decocms/nextjs` has six entry points. Each is a separate subpath so the
|
|
17
|
+
proxy never loads React:
|
|
18
|
+
|
|
19
|
+
| Import | Used from |
|
|
20
|
+
|---|---|
|
|
21
|
+
| `@decocms/nextjs/proxy` | `src/proxy.ts` |
|
|
22
|
+
| `@decocms/nextjs/server` | Server Components (it reads `next/headers`) |
|
|
23
|
+
| `@decocms/nextjs` | Layouts and pages: `StudioBridge`, `StudioPage`, `DraftPreviewIndicator`, names and Studio origins |
|
|
24
|
+
| `@decocms/nextjs/config` | `next.config` (CommonJS, so `require()` works too) |
|
|
25
|
+
| `@decocms/nextjs/image-loader` | The next/image `loaderFile` |
|
|
26
|
+
| `@decocms/nextjs/instrumentation` | `src/instrumentation.ts` |
|
|
27
|
+
|
|
28
|
+
## Files
|
|
29
|
+
|
|
30
|
+
| File | What it holds |
|
|
31
|
+
|---|---|
|
|
32
|
+
| `.deco/index.tsx` | The block map: the default export, `satisfies Blocks` |
|
|
33
|
+
| `.deco/blocks/*.json` | Saved content, one block per file |
|
|
34
|
+
| `.deco/schema.gen.json` | Written by `deco schema`. Commit it. Do not edit |
|
|
35
|
+
| `.deco/blocks.gen.ts` | Written by `deco content`, only for content without `site`. Do not edit |
|
|
36
|
+
| `src/cms.config.ts` | Every `createCMS` option except `blocks` |
|
|
37
|
+
| `src/cms.ts` | `cms = createCMS({ blocks, ...cmsConfig })` for pages |
|
|
38
|
+
| `src/cms.proxy.ts` | `proxyCms = createCMS({ blocks: {}, ...cmsConfig })` for the proxy |
|
|
39
|
+
| `src/proxy.ts` | See [proxy-and-drafts.md](./proxy-and-drafts.md) |
|
|
40
|
+
| `src/app/%5Fassignments/[assignments]/[[...path]]/page.tsx` | Every published CMS page. See [caching.md](./caching.md) |
|
|
41
|
+
| `src/app/%5Fdraft/[[...path]]/page.tsx` | Every preview. See [proxy-and-drafts.md](./proxy-and-drafts.md) |
|
|
42
|
+
| `src/app/layout.tsx` | The root layout, with `<StudioBridge site="…" />` |
|
|
43
|
+
| `src/image-loader.ts` | The next/image loader |
|
|
44
|
+
| `src/instrumentation.ts` | The request metric |
|
|
45
|
+
|
|
46
|
+
## The block map
|
|
47
|
+
|
|
48
|
+
A saved block's `__resolveType` names a key of the block map. The function
|
|
49
|
+
gets the block's resolved props and returns what the page renders: a React
|
|
50
|
+
element for a section, plain data for anything else.
|
|
51
|
+
|
|
52
|
+
```tsx
|
|
53
|
+
// .deco/index.tsx
|
|
54
|
+
import type { Blocks, Seo } from "@decocms/blocks";
|
|
55
|
+
import ProductHero from "../src/ProductHero";
|
|
56
|
+
import PromoBanner from "../src/PromoBanner";
|
|
57
|
+
import type { ProductHeroProps, PromoBannerProps } from "../src/model";
|
|
58
|
+
|
|
59
|
+
export default {
|
|
60
|
+
seo: (input: Seo) => input,
|
|
61
|
+
"promo-banner": (input: PromoBannerProps) => <PromoBanner {...input} />,
|
|
62
|
+
"product-hero": (input: ProductHeroProps) => <ProductHero {...input} />,
|
|
63
|
+
} satisfies Blocks;
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
- The key is the block's identity in content. Renaming it breaks every saved
|
|
67
|
+
block that uses it.
|
|
68
|
+
- The CMS adds built-in blocks to every map: `lazy`, `multivariate`, `always`,
|
|
69
|
+
`never`, `experiment`, `campaign`, `page`, `redirect`, `redirects`,
|
|
70
|
+
`cms-settings`, `split-traffic`, `calendar`. Do not reuse those names.
|
|
71
|
+
- The Props type of each function is the Studio form. `deco schema` reads it
|
|
72
|
+
from `.deco/index.tsx` (or `.deco/index.ts`). Form details: load
|
|
73
|
+
`deco-cms-schema`.
|
|
74
|
+
|
|
75
|
+
**Editability check.** A section that renders literal text in JSX looks
|
|
76
|
+
right and cannot be edited in Studio. For every section, check that what an
|
|
77
|
+
editor should change comes from its props, and that the block map points at
|
|
78
|
+
the real component with its real Props type, not a static copy.
|
|
79
|
+
|
|
80
|
+
## The two CMS handles
|
|
81
|
+
|
|
82
|
+
```ts
|
|
83
|
+
// src/cms.config.ts
|
|
84
|
+
export const cmsConfig = { site: "my-store" };
|
|
85
|
+
|
|
86
|
+
// src/cms.ts
|
|
87
|
+
import { createCMS } from "@decocms/blocks";
|
|
88
|
+
import blocks from "../.deco";
|
|
89
|
+
import { cmsConfig } from "./cms.config";
|
|
90
|
+
export const cms = createCMS({ blocks, ...cmsConfig });
|
|
91
|
+
|
|
92
|
+
// src/cms.proxy.ts
|
|
93
|
+
import { createCMS } from "@decocms/blocks";
|
|
94
|
+
import { cmsConfig } from "./cms.config";
|
|
95
|
+
export const proxyCms = createCMS({ blocks: {}, ...cmsConfig });
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
`createCMS` keeps one instance per process for each `site` (or, without
|
|
99
|
+
`site`, each content module), so both handles share content and release
|
|
100
|
+
checks. Each handle keeps its own block map. The proxy's handle has no block map, so no
|
|
101
|
+
section code lands in the proxy bundle.
|
|
102
|
+
|
|
103
|
+
Where content comes from:
|
|
104
|
+
|
|
105
|
+
- **With `site`** (Studio's site slug): the site's latest release on the
|
|
106
|
+
delivery CDN, loaded at runtime and checked again every `interval` (default
|
|
107
|
+
and minimum 60 000 ms). Passing `content` too throws.
|
|
108
|
+
- **Without `site`**: pass `content`, the module `deco content` writes from
|
|
109
|
+
`.deco/blocks` (`import content from "../.deco/blocks.gen"`). Used by tests
|
|
110
|
+
and the examples.
|
|
111
|
+
|
|
112
|
+
Other options: `preview: { hosts, draftHosts }` (see
|
|
113
|
+
[proxy-and-drafts.md](./proxy-and-drafts.md)), `telemetry` (`false`, or
|
|
114
|
+
`{ endpoint, headers }` for an OTLP/HTTP collector), and `token`, a
|
|
115
|
+
server-only secret that sends telemetry to the hosted collector and needs
|
|
116
|
+
`site`. Never import `token` into client code.
|
|
117
|
+
|
|
118
|
+
## next.config
|
|
119
|
+
|
|
120
|
+
```ts
|
|
121
|
+
// next.config.ts
|
|
122
|
+
import { withDeco } from "@decocms/nextjs/config";
|
|
123
|
+
|
|
124
|
+
export default withDeco({
|
|
125
|
+
images: { loader: "custom", loaderFile: "./src/image-loader.ts" },
|
|
126
|
+
});
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
`withDeco(nextConfig, options?)` adds two things and nothing about hosting:
|
|
130
|
+
|
|
131
|
+
- `draftHeaders` (default on): two header rules placed before the site's own
|
|
132
|
+
`headers()`. A request with `?__draft=` or the `__deco_draft` cookie gets
|
|
133
|
+
`Cache-Control: max-age=0, no-cache, must-revalidate`, `Vary: Cookie` and
|
|
134
|
+
`X-Robots-Tag: noindex, nofollow`. Next sets `Cache-Control` and `Vary`
|
|
135
|
+
itself on dynamic pages, so only `X-Robots-Tag` is sure to arrive from these
|
|
136
|
+
rules; the proxy's `applyDraft` sets all three.
|
|
137
|
+
- `studioOrigins` (default on): Studio's hosts in `allowedDevOrigins`, so
|
|
138
|
+
`next dev` serves Studio its dev assets.
|
|
139
|
+
|
|
140
|
+
Turn either off with `withDeco(config, { draftHeaders: false, studioOrigins: false })`.
|
|
141
|
+
|
|
142
|
+
## Scripts
|
|
143
|
+
|
|
144
|
+
Run the CLI before Next (the example does the same through a small script):
|
|
145
|
+
|
|
146
|
+
```json
|
|
147
|
+
"predev": "deco schema && deco content",
|
|
148
|
+
"prebuild": "deco schema && deco content"
|
|
149
|
+
```
|
|
150
|
+
|
|
151
|
+
Drop `deco content` when the site uses `site`. Use `deco schema --check` in
|
|
152
|
+
CI to fail on a stale schema, and `deco schema push` on production deploys so
|
|
153
|
+
Studio draws the forms. Order and secrets: load `deco-site-workflow`.
|
|
154
|
+
|
|
155
|
+
If the host installs only `dependencies` in production builds, keep
|
|
156
|
+
`@decocms/blocks` there: the `deco` bin comes from it and `prebuild` needs it.
|
|
157
|
+
|
|
158
|
+
## Images
|
|
159
|
+
|
|
160
|
+
```ts
|
|
161
|
+
// src/image-loader.ts
|
|
162
|
+
import { createImageUrl, decoCdn } from "@decocms/blocks/image";
|
|
163
|
+
import { createDecoImageLoader, nextImageOptimizer } from "@decocms/nextjs/image-loader";
|
|
164
|
+
|
|
165
|
+
const imageUrl = createImageUrl({ providers: [decoCdn({ fit: "contain" })] });
|
|
166
|
+
export default createDecoImageLoader(imageUrl, { fallback: nextImageOptimizer });
|
|
167
|
+
```
|
|
168
|
+
|
|
169
|
+
The first provider that takes a source builds its URL. A commerce site lists
|
|
170
|
+
its platform's helpers (`@decocms/apps-vtex/image`,
|
|
171
|
+
`@decocms/apps-shopify/image`) before `decoCdn`. Any other source goes to
|
|
172
|
+
`fallback`: `nextImageOptimizer` sends it through `/_next/image`; without a
|
|
173
|
+
fallback the `src` comes back unchanged. next/image's `quality` may also be a
|
|
174
|
+
named tier (`low`, `medium`, `high`, `original`); `nextImageOptimizer` sends
|
|
175
|
+
them as 60, 70, 80 and 100.
|
|
176
|
+
Providers, quality and LCP: load `deco-images-media`.
|
|
177
|
+
|
|
178
|
+
## Request metric
|
|
179
|
+
|
|
180
|
+
```ts
|
|
181
|
+
// src/instrumentation.ts
|
|
182
|
+
export { register } from "@decocms/nextjs/instrumentation";
|
|
183
|
+
```
|
|
184
|
+
|
|
185
|
+
`register` turns Next's own request span into `http.server.request.duration`
|
|
186
|
+
in the CMS's telemetry, labelled by `http.route`, `http.request.method`,
|
|
187
|
+
`status_class` and `cache` (`DRAFT` or `BYPASS`). It records nothing without
|
|
188
|
+
a telemetry destination, and does nothing on the Edge runtime. A site with its
|
|
189
|
+
own OpenTelemetry setup adds `serverRequestSpanProcessor()` to its span
|
|
190
|
+
processors instead, because only one tracer provider can be registered.
|
|
@@ -0,0 +1,130 @@
|
|
|
1
|
+
# The Studio bridge
|
|
2
|
+
|
|
3
|
+
Studio's site editor shows the site in an iframe. The bridge is what lets it
|
|
4
|
+
scroll to a section, reload the page after a save and load its own editor
|
|
5
|
+
code into the page. On Next it is one component in the root layout.
|
|
6
|
+
|
|
7
|
+
## Wiring
|
|
8
|
+
|
|
9
|
+
```tsx
|
|
10
|
+
// src/app/layout.tsx
|
|
11
|
+
import { StudioBridge } from "@decocms/nextjs";
|
|
12
|
+
import type { ReactNode } from "react";
|
|
13
|
+
|
|
14
|
+
export default function RootLayout({ children }: { children: ReactNode }) {
|
|
15
|
+
return (
|
|
16
|
+
<html lang="en">
|
|
17
|
+
<body>
|
|
18
|
+
{children}
|
|
19
|
+
<StudioBridge site="my-store" />
|
|
20
|
+
</body>
|
|
21
|
+
</html>
|
|
22
|
+
);
|
|
23
|
+
}
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
`StudioBridge` renders two inline scripts and uses no hooks, so a Server
|
|
27
|
+
Component renders it as is. It reads no request, so it does not stop the root
|
|
28
|
+
layout from being cached.
|
|
29
|
+
|
|
30
|
+
| Prop | Default | What it does |
|
|
31
|
+
|---|---|---|
|
|
32
|
+
| `site` | required | The site's name in Studio |
|
|
33
|
+
| `editShortcut` | `true` | "." (or Ctrl+Shift+E) on a page outside Studio opens it in Studio's editor; Ctrl or Cmd+"." in a new tab |
|
|
34
|
+
| `studioOrigins` | `DECO_STUDIO_ORIGIN`, else Studio's production and staging origins | The exact origins the Studio channel trusts |
|
|
35
|
+
| `nonce` | none | The CSP nonce for the inline scripts |
|
|
36
|
+
| `page` | none | The page on screen; a `StudioPage` on the page wins |
|
|
37
|
+
|
|
38
|
+
## What it does
|
|
39
|
+
|
|
40
|
+
- **The bridge script** answers Studio's scroll-to-section and rerender
|
|
41
|
+
messages, only from a parent window at one of Studio's origins. Outside a
|
|
42
|
+
frame it answers no message and only listens for the "." shortcut.
|
|
43
|
+
- **The Studio channel** runs on every page, production included (about
|
|
44
|
+
0.7 kB gzipped). Framed by a trusted origin, it posts `{ type: "deco:ready" }`
|
|
45
|
+
and imports a module only when the answer `{ type: "deco:load", url }`
|
|
46
|
+
comes from exactly one trusted origin and names a URL on that origin. Not
|
|
47
|
+
framed, or framed by anyone else, it does nothing. It never evaluates a
|
|
48
|
+
script Studio sends. Message types are in `@decocms/blocks/protocol`.
|
|
49
|
+
|
|
50
|
+
## Which page "." opens
|
|
51
|
+
|
|
52
|
+
The root layout does not re-render on navigation, so it cannot know which
|
|
53
|
+
page is on screen. Each CMS page renders a marker next to its sections:
|
|
54
|
+
|
|
55
|
+
```tsx
|
|
56
|
+
import { StudioPage } from "@decocms/nextjs";
|
|
57
|
+
|
|
58
|
+
<StudioPage pathTemplate={page.path} />
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
`pathTemplate` is the page block's `path` as `matchRoute` matched it
|
|
62
|
+
(`/:slug/p`, not `/summer-shirt/p`). An optional `id` names the page block.
|
|
63
|
+
Without the marker, Studio picks the page from the URL.
|
|
64
|
+
|
|
65
|
+
## Content Security Policy
|
|
66
|
+
|
|
67
|
+
A site with a CSP must allow Studio's origins in `script-src` (the channel
|
|
68
|
+
imports Studio's modules) and in `frame-ancestors` (Studio frames the site).
|
|
69
|
+
`withStudioCsp(directives, options?)` from `@decocms/nextjs` adds them:
|
|
70
|
+
|
|
71
|
+
```ts
|
|
72
|
+
// next.config.ts
|
|
73
|
+
import { withStudioCsp } from "@decocms/nextjs";
|
|
74
|
+
import { withDeco } from "@decocms/nextjs/config";
|
|
75
|
+
|
|
76
|
+
const csp = withStudioCsp("script-src 'self' 'unsafe-inline'; object-src 'none'").join("; ");
|
|
77
|
+
|
|
78
|
+
export default withDeco({
|
|
79
|
+
headers: async () => [
|
|
80
|
+
{ source: "/:path*", headers: [{ key: "Content-Security-Policy", value: csp }] },
|
|
81
|
+
],
|
|
82
|
+
});
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
- It adds the origins to `script-src` and `script-src-elem`. A policy that
|
|
86
|
+
restricts scripts only through `default-src` gets a `script-src` with
|
|
87
|
+
`default-src`'s sources plus Studio's.
|
|
88
|
+
- It adds `frame-ancestors` with Studio's only when the policy has none. A
|
|
89
|
+
site's own `frame-ancestors` is kept as is: add Studio's yourself.
|
|
90
|
+
- Options: `studioOrigins`, `frameAncestors` (other editors allowed to frame
|
|
91
|
+
the site), `dev: true` (loopback may frame the site),
|
|
92
|
+
`addFrameAncestors: false`.
|
|
93
|
+
- Pass the same `nonce` to `StudioBridge` when the policy uses nonces.
|
|
94
|
+
|
|
95
|
+
A site that builds its headers in the proxy can set the same value there.
|
|
96
|
+
|
|
97
|
+
## A local or staging Studio
|
|
98
|
+
|
|
99
|
+
Set `DECO_STUDIO_ORIGIN` to a comma-separated list of exact origins (for
|
|
100
|
+
example `http://localhost:3000`). It replaces the default list for the
|
|
101
|
+
channel and for `withStudioCsp`. Each entry must be an exact http(s) origin;
|
|
102
|
+
anything else (a path, a wildcard) is dropped. An empty `studioOrigins={[]}`
|
|
103
|
+
turns the channel off.
|
|
104
|
+
|
|
105
|
+
`withDeco` adds Studio's hosts to `allowedDevOrigins`, so `next dev` serves
|
|
106
|
+
its dev assets when Studio frames a local site.
|
|
107
|
+
|
|
108
|
+
## Names for the site's own code
|
|
109
|
+
|
|
110
|
+
`@decocms/nextjs` exports what the proxy, the pages and `withDeco` use, for a
|
|
111
|
+
route that sets its own headers: `DRAFT_PARAM` (`__draft`), `DRAFT_COOKIE`
|
|
112
|
+
(`__deco_draft`), `VERSION_HEADER` (`x-deco-version`), `VISITOR_HEADER`
|
|
113
|
+
(`x-deco-visitor`), `ASSIGNMENTS_HEADER` (`x-deco-assignments`),
|
|
114
|
+
`draftResponseHeaders(...)`, `STUDIO_ORIGIN`, `STUDIO_ORIGINS`,
|
|
115
|
+
`STUDIO_FRAME_ANCESTORS`, `DEFAULT_STUDIO_ORIGINS`, `isStudioOrigin(origin)`,
|
|
116
|
+
`studioOrigins(option?)` and `withStudioCsp(...)`.
|
|
117
|
+
|
|
118
|
+
## When Studio can't drive the page
|
|
119
|
+
|
|
120
|
+
1. Is `StudioBridge` in the root layout's `<body>`, on every route?
|
|
121
|
+
2. Does the CSP allow Studio in `script-src` and `frame-ancestors`? Look for
|
|
122
|
+
CSP errors in the framed page's console.
|
|
123
|
+
3. Does an `X-Frame-Options` header block framing? Remove it in favor of
|
|
124
|
+
`frame-ancestors`.
|
|
125
|
+
4. Is Studio on a non-default origin? Set `DECO_STUDIO_ORIGIN` on the server.
|
|
126
|
+
5. Does "." open the wrong page? Render `StudioPage` with the matched
|
|
127
|
+
`path` template.
|
|
128
|
+
|
|
129
|
+
Connecting a local site to Studio and the `deco` CLI side: load
|
|
130
|
+
`deco-site-workflow`.
|
|
@@ -0,0 +1,75 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: deco-site-authoring
|
|
3
|
+
description: "Writing sections, pages and loaders for a site on @decocms/blocks 8 (with @decocms/tanstack or @decocms/nextjs). Covers block functions in .deco/index.ts and their Props, React sections as descriptors or elements, client components instead of islands or HTMX, page blocks with path templates and route params, loaders as block functions (one run per distinct input per client, no request object), SEO and JSON-LD fed by the same commerce loader as the page, the built-in lazy block, one promise per section with Suspense and loading skeletons, and the review before deco push. Load it when creating or changing a section, page or loader, when a section never loads, loads twice or shows the wrong data, or before pushing content and code."
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Authoring sections, pages and loaders on v8
|
|
7
|
+
|
|
8
|
+
On @decocms/blocks 8 everything an editor can place is a **block function**: a plain
|
|
9
|
+
function in the block map, `.deco/index.ts` (or `.tsx`), that takes one argument, its
|
|
10
|
+
inputs, and returns a value. Content is JSON in `.deco/blocks/`, where each object names
|
|
11
|
+
a function in `__resolveType` and carries its inputs. `client.resolve` walks that JSON
|
|
12
|
+
inside out, so nested blocks run first, siblings run concurrently, and each function
|
|
13
|
+
gets its inputs already resolved.
|
|
14
|
+
|
|
15
|
+
Use this skill when you are writing or changing the code an editor uses. It is not for
|
|
16
|
+
wiring the binding or deploying.
|
|
17
|
+
|
|
18
|
+
## The model in five lines
|
|
19
|
+
|
|
20
|
+
- **Section**: a block function that returns a React element, or a descriptor
|
|
21
|
+
`{ component, props }`. `deco schema` puts it in the section picker.
|
|
22
|
+
- **Loader**: a block function that returns data. A field of type `T` accepts a plain
|
|
23
|
+
value or any block whose awaited return type fits `T`.
|
|
24
|
+
- **Matcher**: a block function that returns a boolean.
|
|
25
|
+
- **Page**: the built-in `page` block, `{ name, path, seo?, sections }`, routed by
|
|
26
|
+
`matchRoute`.
|
|
27
|
+
- **No request scope**: a block function gets its inputs and nothing else. It calls
|
|
28
|
+
`currentClient()` to reach the client, and gets route params as arguments.
|
|
29
|
+
|
|
30
|
+
## When to load what
|
|
31
|
+
|
|
32
|
+
| Reference | Load it when |
|
|
33
|
+
|---|---|
|
|
34
|
+
| [`references/sections.md`](./references/sections.md) | Writing a section, choosing descriptors or elements, adding interactivity (hooks, `"use client"`), porting a Fresh island or an HTMX section |
|
|
35
|
+
| [`references/pages.md`](./references/pages.md) | Creating a page block, path templates and params, shared header/footer, a page with variants, routing a custom type, a route conflict |
|
|
36
|
+
| [`references/loaders.md`](./references/loaders.md) | Fetching data for a section, passing a route param to a loader, a loader that runs twice, `BLOCK_FAILED`, secrets, upstream fetches |
|
|
37
|
+
| [`references/lazy-blocks.md`](./references/lazy-blocks.md) | `Lazy<T>` props, the `lazy` built-in, streaming sections with Suspense, loading skeletons, a failed or hidden section |
|
|
38
|
+
| [`references/seo.md`](./references/seo.md) | A page's `seo` field, title and description from product data, canonical and JSON-LD, the SEO checklist for a new site |
|
|
39
|
+
| [`references/review-before-publish.md`](./references/review-before-publish.md) | Before `deco push` or opening a PR: the checklist, `deco schema --check`, `deco check` against a draft |
|
|
40
|
+
|
|
41
|
+
## Rules that hold everywhere
|
|
42
|
+
|
|
43
|
+
- **One argument, no context.** A block function gets exactly one argument, its
|
|
44
|
+
inputs, with `__resolveType` removed. There is no `req`, no `ctx`, no `invoke`.
|
|
45
|
+
- **Results are read-only.** A client runs each block function once per distinct
|
|
46
|
+
input and hands every occurrence the same object. Copy a result before you change
|
|
47
|
+
it.
|
|
48
|
+
- **A failing block fails its parent.** The error is `BLOCK_FAILED` with `path`
|
|
49
|
+
set to where it happened, such as `["sections", 2, "product"]`. `resolve` never
|
|
50
|
+
throws: it returns `[value, null]` or `[null, error]`.
|
|
51
|
+
- **A hidden block is `undefined`.** A `multivariate` with no true rule resolves to
|
|
52
|
+
`undefined`, and lists drop it. Render nothing for it.
|
|
53
|
+
- **Names.** Block map keys are the type names saved in content. Built-in names
|
|
54
|
+
(`lazy`, `multivariate`, `always`, `never`, `experiment`, `campaign`, `page`,
|
|
55
|
+
`redirect`, `redirects`, `cms-settings`, `split-traffic`, `calendar`) are names no
|
|
56
|
+
saved block can take. A block map key with a built-in's name replaces the
|
|
57
|
+
built-in, and `deco check` tells you what relies on it.
|
|
58
|
+
- **After changing a Props type, run `deco schema`.** The Studio form comes from
|
|
59
|
+
`.deco/schema.gen.json`, and `deco check` validates against it.
|
|
60
|
+
|
|
61
|
+
## Related skills
|
|
62
|
+
|
|
63
|
+
- `deco-site-workflow`: the `deco` CLI end to end (`pull`, `diff`, `push --draft`,
|
|
64
|
+
`publish`, `schema push`, `check`).
|
|
65
|
+
- `deco-cms-schema`: how a Props type becomes the Studio form (JSDoc tags, widgets,
|
|
66
|
+
shapes that break the form).
|
|
67
|
+
- `deco-tanstack-site` and `deco-nextjs-site`: the catch-all route, `open-page`, the
|
|
68
|
+
worker or proxy, server functions, document head.
|
|
69
|
+
- `deco-variants`: `multivariate`, matchers, A/B tests and campaigns.
|
|
70
|
+
- `deco-apps`: the `@decocms/apps-*` clients a loader calls, commerce types.
|
|
71
|
+
- `deco-images-media`: images and video inside sections.
|
|
72
|
+
- `deco-storefront-performance` and `deco-storefront-caching`: slow loaders,
|
|
73
|
+
duplicate upstream calls, payload size, cache keys.
|
|
74
|
+
- `deco-v7-to-v8-migration`: a site moving from v7, where sections still use
|
|
75
|
+
`(props, req)` loaders through `@decocms/compat-v7/sections`.
|
|
@@ -0,0 +1,155 @@
|
|
|
1
|
+
# Lazy blocks, streaming and skeletons
|
|
2
|
+
|
|
3
|
+
Two different tools answer "don't make the page wait for this":
|
|
4
|
+
|
|
5
|
+
- The **`lazy` built-in** skips work on the server: a prop typed `Lazy<T>` is a function
|
|
6
|
+
the block calls only if it needs the value.
|
|
7
|
+
- **One promise per section** streams the page: the page loader resolves each section on
|
|
8
|
+
its own, and the route shows a fallback in a Suspense boundary until that section is
|
|
9
|
+
ready.
|
|
10
|
+
|
|
11
|
+
v8 has no async rendering of the v7 kind. There is no `Rendering/Lazy.tsx` wrapper in
|
|
12
|
+
content, no `LoadingFallback` export picked up by the framework, and no section that
|
|
13
|
+
waits for the viewport before it loads. The migration script unwraps v7's wrappers into
|
|
14
|
+
plain sections.
|
|
15
|
+
|
|
16
|
+
## The `lazy` built-in
|
|
17
|
+
|
|
18
|
+
```ts
|
|
19
|
+
import type { Lazy } from "@decocms/blocks";
|
|
20
|
+
|
|
21
|
+
export async function productCard({
|
|
22
|
+
title,
|
|
23
|
+
showProduct,
|
|
24
|
+
product,
|
|
25
|
+
}: {
|
|
26
|
+
title: string;
|
|
27
|
+
showProduct: boolean;
|
|
28
|
+
product: Lazy<Product>;
|
|
29
|
+
}) {
|
|
30
|
+
if (!showProduct) return <Title text={title} />; // the loader never runs
|
|
31
|
+
const item = await product(); // the loader runs here
|
|
32
|
+
return <Card title={title} product={item} />;
|
|
33
|
+
}
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
In content, the field holds a `lazy` block around the loader:
|
|
37
|
+
|
|
38
|
+
```json
|
|
39
|
+
{
|
|
40
|
+
"__resolveType": "product-card",
|
|
41
|
+
"title": "Summer collection",
|
|
42
|
+
"showProduct": true,
|
|
43
|
+
"product": {
|
|
44
|
+
"__resolveType": "lazy",
|
|
45
|
+
"value": { "__resolveType": "product-by-slug", "slug": "summer-shirt" }
|
|
46
|
+
}
|
|
47
|
+
}
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
How it behaves:
|
|
51
|
+
|
|
52
|
+
- The resolver does not resolve `value` first. It hands the block a memoized
|
|
53
|
+
`() => Promise<T>` instead.
|
|
54
|
+
- The value resolves the first time the function is called, and only once. A second
|
|
55
|
+
call returns the same result.
|
|
56
|
+
- If the value fails, the call rejects, and the block decides what to do. If the block
|
|
57
|
+
lets the error escape, the block fails with the inner error's code and path.
|
|
58
|
+
- A lazy value that is never called never runs, and never rejects unhandled.
|
|
59
|
+
- `value` can be any JSON, not only a block. Saved block references inside it expand
|
|
60
|
+
when it is called.
|
|
61
|
+
|
|
62
|
+
Schema and checks:
|
|
63
|
+
|
|
64
|
+
- `deco schema` turns a `Lazy<T>` prop into a field that holds a `lazy` block whose
|
|
65
|
+
`value` has the form of `T`. `Lazy<T>[]` is a list of them.
|
|
66
|
+
- `deco check` reports `this field is Lazy<T>: wrap the value in a lazy block` for a
|
|
67
|
+
plain value in such a field, and `a lazy block only fits a Lazy<T> field` for a `lazy`
|
|
68
|
+
block anywhere else. A `lazy` block cannot sit directly in a page's `sections`.
|
|
69
|
+
- The built-in `multivariate` stores each variant's `value` as a `lazy` block, so only
|
|
70
|
+
the chosen variant runs. `deco check` reports `a variant's value must be a lazy block`
|
|
71
|
+
otherwise.
|
|
72
|
+
- A matcher can take an inner rule as `Lazy<boolean>` and skip it:
|
|
73
|
+
`async ({ a, b }: { a: boolean; b: Lazy<boolean> }) => a && (await b())`.
|
|
74
|
+
|
|
75
|
+
Use `Lazy<T>` when the block may not need the data: a toggle, a tab that is closed by
|
|
76
|
+
default, a fallback source, an expensive rule. It does not move work to the browser or
|
|
77
|
+
delay it until scroll. A block that always calls its lazy prop gains nothing from it.
|
|
78
|
+
|
|
79
|
+
## One promise per section
|
|
80
|
+
|
|
81
|
+
The page loader in the examples (`src/open-page.server.ts`) reads the page with
|
|
82
|
+
`{ run: false }`, then starts one `client.resolve(section)` per section and returns the
|
|
83
|
+
promises without awaiting them:
|
|
84
|
+
|
|
85
|
+
```ts
|
|
86
|
+
const blocks = sections.map((block, index) => ({
|
|
87
|
+
key: `${href}:${index}`,
|
|
88
|
+
value: c.resolve(block).then(([value, error]) => {
|
|
89
|
+
if (error) console.error(error);
|
|
90
|
+
return { value: value ?? undefined, failed: error !== null };
|
|
91
|
+
}),
|
|
92
|
+
}));
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
Each entry settles to `{ value, failed }` and never rejects, so one slow or failing
|
|
96
|
+
section does not hold or break the others. The route renders each one in its own
|
|
97
|
+
boundary. On TanStack Start without RSC:
|
|
98
|
+
|
|
99
|
+
```tsx
|
|
100
|
+
<Suspense key={block.key} fallback={<SectionSkeleton />}>
|
|
101
|
+
<Await promise={block.value}>
|
|
102
|
+
{({ value, failed }) => {
|
|
103
|
+
if (failed) return <p role="status">This content is temporarily unavailable.</p>;
|
|
104
|
+
return value ? <View block={value} /> : null; // undefined: an editor hid it
|
|
105
|
+
}}
|
|
106
|
+
</Await>
|
|
107
|
+
</Suspense>
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
With TanStack RSC (`examples/tanstack-rsc-smoke`), an async server component awaits
|
|
111
|
+
the promise inside the same `Suspense`. The Next.js examples resolve the whole page in
|
|
112
|
+
one call instead, so nothing streams per section and one failing block fails the page.
|
|
113
|
+
A Next.js site that wants per-section streaming applies the same split in its page
|
|
114
|
+
loader. The wiring is in the `deco-tanstack-site` and `deco-nextjs-site` skills.
|
|
115
|
+
|
|
116
|
+
Three states to render, every time:
|
|
117
|
+
|
|
118
|
+
| State | Cause | Render |
|
|
119
|
+
|---|---|---|
|
|
120
|
+
| Pending | The section's loaders are still running | The Suspense fallback |
|
|
121
|
+
| `failed: true` | A block in the section threw | A small, quiet message, or nothing for decoration |
|
|
122
|
+
| `value === undefined` | A rule hid the section | Nothing |
|
|
123
|
+
|
|
124
|
+
Two caveats from migrated sites (details in the `deco-v7-to-v8-migration` skill,
|
|
125
|
+
`rendering.md`):
|
|
126
|
+
|
|
127
|
+
- After changing the page setup, check in the browser that every streamed section
|
|
128
|
+
hydrates (its handlers and effects run). One TanStack Start release left streamed
|
|
129
|
+
sections with server markup that never hydrated.
|
|
130
|
+
- A page whose blocks only read in-memory content can await them, so every section is
|
|
131
|
+
in the first HTML chunk. Stop awaiting a block once it fetches upstream.
|
|
132
|
+
|
|
133
|
+
## Skeletons
|
|
134
|
+
|
|
135
|
+
The fallback is shown in the server's first HTML and then replaced in place. A
|
|
136
|
+
skeleton that is the wrong size moves the page when the section arrives (CLS).
|
|
137
|
+
|
|
138
|
+
- **Match the box.** Same container, padding, gaps and aspect ratios as the real
|
|
139
|
+
section, at each breakpoint. Height matters more than detail.
|
|
140
|
+
- **Pure markup.** CSS only (a pulse animation is fine). No hooks, no data, no props
|
|
141
|
+
from the loader. It renders before any data exists.
|
|
142
|
+
- **Represent the content.** A shelf skeleton shows a title bar and the number of cards
|
|
143
|
+
the real shelf shows per breakpoint (for example two on mobile, four on desktop,
|
|
144
|
+
hiding the rest with responsive classes).
|
|
145
|
+
- **Reuse a card skeleton.** Most shelves and grids repeat a product card. Build one
|
|
146
|
+
`CardSkeleton` that mirrors the real card (image, name in two lines, price block,
|
|
147
|
+
button) and use it everywhere.
|
|
148
|
+
- **Pick the skeleton per section type.** `{ run: false }` already gives the page
|
|
149
|
+
loader each section's `__resolveType` (saved references are expanded, so a reference
|
|
150
|
+
to a saved block shows the saved block's type). The page loader can return it next to
|
|
151
|
+
`key` and `value`, and the route can map it to a skeleton, with one generic fallback
|
|
152
|
+
for the rest.
|
|
153
|
+
- **Above the fold.** The first sections (header, hero, product summary) are what the
|
|
154
|
+
user sees first. Keep their loaders fast, or await them, rather than showing a
|
|
155
|
+
skeleton where the main content should be.
|