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