@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,177 @@
|
|
|
1
|
+
# The proxy and draft previews
|
|
2
|
+
|
|
3
|
+
The proxy (`src/proxy.ts`, Next 16's name for middleware) decides once per
|
|
4
|
+
request what the request reads. The pages only render that decision. This
|
|
5
|
+
split is what lets published pages stay cached while Studio previews render
|
|
6
|
+
fresh.
|
|
7
|
+
|
|
8
|
+
## What the proxy decides
|
|
9
|
+
|
|
10
|
+
| Step | Function (`@decocms/nextjs/proxy`) | Result |
|
|
11
|
+
|---|---|---|
|
|
12
|
+
| Version | `decideDraft(proxyCms, request)` | A Studio link's draft or old release on an allowed host, its preview moment (`__at`) and switched tests and campaigns (`__test`, `__campaign`), the cookie to set |
|
|
13
|
+
| Visitor | `decideVisitor(request, draft)` | The `deco_segment` cookie, or a new visitor. Its cookie is sent on a first visit only, never when the request renders a draft or an old release |
|
|
14
|
+
| Tests and campaigns | `decideAssignments(proxyCms, draft, visitor)` | Each test of the saved `experiments` block on or off, each campaign of the saved `campaigns` block running or not. Missing blocks give none, never an error |
|
|
15
|
+
|
|
16
|
+
It forwards them to the page on request headers, always removing copies sent
|
|
17
|
+
from outside:
|
|
18
|
+
|
|
19
|
+
| Header | Set by |
|
|
20
|
+
|---|---|
|
|
21
|
+
| `x-deco-version` | `draftRequestHeaders(request, draft)` |
|
|
22
|
+
| `x-deco-visitor` | `visitorRequestHeaders(headers, visitor)` |
|
|
23
|
+
| `x-deco-assignments` | `assignmentsRequestHeaders(headers, assignments)` |
|
|
24
|
+
|
|
25
|
+
On the response, `applyDraft(response, draft)` sets the draft cookie and, on
|
|
26
|
+
any preview, `Cache-Control: max-age=0, no-cache, must-revalidate`,
|
|
27
|
+
`Vary: Cookie` and `X-Robots-Tag: noindex, nofollow`. `applyVisitor` sets the
|
|
28
|
+
visitor cookie.
|
|
29
|
+
|
|
30
|
+
## The proxy
|
|
31
|
+
|
|
32
|
+
```ts
|
|
33
|
+
// src/proxy.ts
|
|
34
|
+
import {
|
|
35
|
+
applyDraft, applyVisitor, assignmentsRequestHeaders, decideAssignments, decideDraft,
|
|
36
|
+
decideVisitor, draftRequestHeaders, isAssignmentsRoutePath, isDraftRoutePath,
|
|
37
|
+
rewriteToAssignmentsRoute, rewriteToDraftRoute, visitorRequestHeaders,
|
|
38
|
+
} from "@decocms/nextjs/proxy";
|
|
39
|
+
import { type NextRequest, NextResponse } from "next/server";
|
|
40
|
+
import { proxyCms } from "./cms.proxy";
|
|
41
|
+
|
|
42
|
+
export async function proxy(request: NextRequest) {
|
|
43
|
+
const { pathname } = request.nextUrl;
|
|
44
|
+
// Only the rewrites below may reach these routes.
|
|
45
|
+
if (isDraftRoutePath(pathname) || isAssignmentsRoutePath(pathname)) {
|
|
46
|
+
return new NextResponse("Not found", { status: 404 });
|
|
47
|
+
}
|
|
48
|
+
const draft = await decideDraft(proxyCms, request);
|
|
49
|
+
const visitor = decideVisitor(request, draft);
|
|
50
|
+
const assigned = isCmsPage(pathname)
|
|
51
|
+
? await rewriteToAssignmentsRoute(proxyCms, request, draft, visitor)
|
|
52
|
+
: null;
|
|
53
|
+
if (assigned) return applyVisitor(applyDraft(assigned, draft), visitor);
|
|
54
|
+
const assignments = await decideAssignments(proxyCms, draft, visitor);
|
|
55
|
+
const headers = assignmentsRequestHeaders(
|
|
56
|
+
visitorRequestHeaders(draftRequestHeaders(request, draft), visitor),
|
|
57
|
+
assignments,
|
|
58
|
+
);
|
|
59
|
+
const response =
|
|
60
|
+
rewriteToDraftRoute(request, draft, visitor, assignments) ??
|
|
61
|
+
NextResponse.next({ request: { headers } });
|
|
62
|
+
return applyVisitor(applyDraft(response, draft), visitor);
|
|
63
|
+
}
|
|
64
|
+
|
|
65
|
+
// The app's own routes, outside the CMS.
|
|
66
|
+
function isCmsPage(pathname: string): boolean {
|
|
67
|
+
return pathname !== "/blog";
|
|
68
|
+
}
|
|
69
|
+
|
|
70
|
+
// Next's own files must not go through the proxy: rewritten, every script and style is a 404.
|
|
71
|
+
export const config = { matcher: ["/((?!_next/|favicon.ico).*)"] };
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
- `rewriteToAssignmentsRoute` returns `null` for a preview, so a preview
|
|
75
|
+
falls through to `rewriteToDraftRoute`.
|
|
76
|
+
- `rewriteToDraftRoute` returns `null` when the request carries no draft
|
|
77
|
+
signal; the request then goes on with the forwarded headers.
|
|
78
|
+
- `isCmsPage` is the site's own. Routes the app owns (a blog index, an API
|
|
79
|
+
route) render as before and still get the forwarded headers.
|
|
80
|
+
|
|
81
|
+
**A site with no proxy logic of its own** exports
|
|
82
|
+
`draftProxy(proxyCms, options)` instead:
|
|
83
|
+
|
|
84
|
+
```ts
|
|
85
|
+
export const proxy = draftProxy(proxyCms, {
|
|
86
|
+
assignments: (request) => isCmsPage(request.nextUrl.pathname),
|
|
87
|
+
});
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
`assignments` picks the paths rewritten to the assignments route (default:
|
|
91
|
+
none) and makes direct hits on that route a 404. `rewrite` picks which
|
|
92
|
+
previews go to the draft route (default: all); return `false` for a route
|
|
93
|
+
that is already dynamic and binds the draft itself.
|
|
94
|
+
|
|
95
|
+
## The draft route
|
|
96
|
+
|
|
97
|
+
```tsx
|
|
98
|
+
// src/app/%5Fdraft/[[...path]]/page.tsx
|
|
99
|
+
import { DraftPreviewIndicator } from "@decocms/nextjs";
|
|
100
|
+
import { bindDraft, type SearchParams } from "@decocms/nextjs/server";
|
|
101
|
+
import { cms } from "../../../cms";
|
|
102
|
+
import { openPage, pathnameFor } from "../../../open-page.server";
|
|
103
|
+
import { PageView } from "../../PageView";
|
|
104
|
+
|
|
105
|
+
export const dynamic = "force-dynamic";
|
|
106
|
+
|
|
107
|
+
type Props = { params: Promise<{ path?: string[] }>; searchParams: Promise<SearchParams> };
|
|
108
|
+
|
|
109
|
+
export default async function DraftPage({ params, searchParams }: Props) {
|
|
110
|
+
await bindDraft(cms, { searchParams: await searchParams });
|
|
111
|
+
const opened = await openPage(pathnameFor((await params).path));
|
|
112
|
+
return (
|
|
113
|
+
<>
|
|
114
|
+
<PageView {...opened} />
|
|
115
|
+
<DraftPreviewIndicator />
|
|
116
|
+
</>
|
|
117
|
+
);
|
|
118
|
+
}
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
- The folder is `%5Fdraft`. A literal `_draft` folder is private in Next and
|
|
122
|
+
never routes.
|
|
123
|
+
- `bindDraft(cms, { searchParams })` binds, for this request: the page's own
|
|
124
|
+
`?__draft=` (`off` ends the preview), else `x-deco-version`, else the draft
|
|
125
|
+
cookie, each checked against the preview hosts. It also binds the visitor
|
|
126
|
+
and the assignments the proxy forwarded (on the current release, only when
|
|
127
|
+
it saves an `experiments` or `campaigns` block, and a test at 0% stays
|
|
128
|
+
off). It returns whether a version was bound.
|
|
129
|
+
- `contentClient(cms)` then builds `cms.client({ version, experiments, campaigns })`
|
|
130
|
+
from what was bound. Create one per request. `openPage` in
|
|
131
|
+
[rendering.md](./rendering.md) calls it.
|
|
132
|
+
- `DraftPreviewIndicator` renders the "Preview mode" badge only when a draft
|
|
133
|
+
is bound. Render it inside the page, after `bindDraft`, never in a layout:
|
|
134
|
+
a layout may render before the page binds. `exitHref` overrides where
|
|
135
|
+
"Exit preview" goes (default: the current URL with `?__draft=off`).
|
|
136
|
+
- A layout under the draft route that reads content
|
|
137
|
+
(`app/%5Fdraft/layout.tsx`) calls `bindDraft(cms)` and `contentClient(cms)`
|
|
138
|
+
without `searchParams`; it reads the forwarded headers.
|
|
139
|
+
- `activeDraftPointer()` from `@decocms/nextjs/server` returns the bound
|
|
140
|
+
version, or `null` on the current release.
|
|
141
|
+
|
|
142
|
+
## Preview hosts
|
|
143
|
+
|
|
144
|
+
A draft link previews only on hosts the CMS allows: the `previewHosts`
|
|
145
|
+
Studio writes into the current release's metadata, plus
|
|
146
|
+
`createCMS({ preview: { hosts } })`. The host is the one the visitor asked
|
|
147
|
+
for (`x-forwarded-host`, else `host`).
|
|
148
|
+
|
|
149
|
+
| Situation | Who may preview |
|
|
150
|
+
|---|---|
|
|
151
|
+
| A site whose release lists `previewHosts` | Those hosts and `preview.hosts` |
|
|
152
|
+
| No release on the CDN yet, or one published before Studio wrote the list | Every host |
|
|
153
|
+
| No `site` and no `preview.hosts` | Every host |
|
|
154
|
+
| The release metadata can't be read (network, 5xx, bad file) | Only `preview.hosts`, until a read succeeds |
|
|
155
|
+
|
|
156
|
+
On a host that may not preview, the page renders the release. `?__draft=off`
|
|
157
|
+
ends a preview on any host.
|
|
158
|
+
|
|
159
|
+
`preview.draftHosts` replaces the hosts a draft pointer may point at
|
|
160
|
+
(default: `.decocms.com` and loopback).
|
|
161
|
+
|
|
162
|
+
## Debugging a draft that shows the published page
|
|
163
|
+
|
|
164
|
+
1. Is the request reaching the proxy? Check the `matcher`.
|
|
165
|
+
2. Is the host allowed? Compare `x-forwarded-host` or `host` with the release's
|
|
166
|
+
`previewHosts` and `preview.hosts`. Add a local host such as `localhost`
|
|
167
|
+
to `preview.hosts` to preview in development.
|
|
168
|
+
3. Does the page call `bindDraft` before reading content, on the draft route?
|
|
169
|
+
4. Does the page show a notice (`data-deco-preview-unavailable`) instead of
|
|
170
|
+
the "Preview mode" badge? The link's draft can no longer be read (deleted,
|
|
171
|
+
or the drafts host failing). The page renders the release, with that
|
|
172
|
+
notice instead of an error page.
|
|
173
|
+
5. Is a CDN or a `headers()` rule caching responses that carry `?__draft=` or
|
|
174
|
+
the `__deco_draft` cookie? Draft responses must not be stored.
|
|
175
|
+
|
|
176
|
+
Studio links, draft names and `deco push --draft`: load `deco-site-workflow`.
|
|
177
|
+
Variant previews with `__test` and `__campaign`: load `deco-variants`.
|
|
@@ -0,0 +1,171 @@
|
|
|
1
|
+
# Reading and rendering a page
|
|
2
|
+
|
|
3
|
+
Pages are Server Components. They get one content client, match the path,
|
|
4
|
+
follow redirects, resolve the page block and render its sections. The same
|
|
5
|
+
function serves the draft route, the assignments route and
|
|
6
|
+
`generateMetadata`.
|
|
7
|
+
|
|
8
|
+
## The client
|
|
9
|
+
|
|
10
|
+
| Where | Client | Why |
|
|
11
|
+
|---|---|---|
|
|
12
|
+
| Assignments route (published CMS pages) | `await assignedClient(cms, segment)` | Built from the path segment, reads no request, so Next can cache the page. `null` for a segment the proxy never writes: answer `notFound()` |
|
|
13
|
+
| Draft route, and the app's own dynamic routes | `contentClient(cms)`, after `await bindDraft(...)` | Built from what `bindDraft` bound from the request and the proxy's headers |
|
|
14
|
+
|
|
15
|
+
Both come from `@decocms/nextjs/server`. Create a client per request. A client
|
|
16
|
+
runs each block function once per distinct input and memoizes the result, so
|
|
17
|
+
results are shared and read-only: copy before changing one.
|
|
18
|
+
|
|
19
|
+
## The page function
|
|
20
|
+
|
|
21
|
+
```ts
|
|
22
|
+
// src/open-page.server.ts
|
|
23
|
+
import "server-only";
|
|
24
|
+
import { cache, type ReactNode } from "react";
|
|
25
|
+
import { notFound, permanentRedirect, redirect } from "next/navigation";
|
|
26
|
+
import { matchRoute, type Page } from "@decocms/blocks";
|
|
27
|
+
import { assignedClient, contentClient } from "@decocms/nextjs/server";
|
|
28
|
+
import { cms } from "./cms";
|
|
29
|
+
|
|
30
|
+
export const openPage = cache(async (pathname: string, assignments?: string) => {
|
|
31
|
+
const c = assignments === undefined ? contentClient(cms) : await assignedClient(cms, assignments);
|
|
32
|
+
if (!c) notFound();
|
|
33
|
+
|
|
34
|
+
const [routes, routesError] = await c.routes();
|
|
35
|
+
if (routesError) throw routesError;
|
|
36
|
+
const match = matchRoute(pathname, { routes });
|
|
37
|
+
// Start downloading the page's blocks while the redirects block loads.
|
|
38
|
+
if (match.kind === "match") c.prefetch(match.entry.name);
|
|
39
|
+
|
|
40
|
+
const [redirects, redirectsError] = await c.redirects();
|
|
41
|
+
if (redirectsError) throw redirectsError;
|
|
42
|
+
const moved = matchRoute(pathname, { routes: [], redirects });
|
|
43
|
+
if (moved.kind === "redirect") {
|
|
44
|
+
if (moved.status === 301 || moved.status === 308) permanentRedirect(moved.location);
|
|
45
|
+
redirect(moved.location);
|
|
46
|
+
}
|
|
47
|
+
if (match.kind !== "match") notFound();
|
|
48
|
+
|
|
49
|
+
const [page, error] = await c.resolve<Page<ReactNode>>(match.entry.name);
|
|
50
|
+
if (error) throw error;
|
|
51
|
+
return page;
|
|
52
|
+
});
|
|
53
|
+
|
|
54
|
+
export const pathnameFor = (segments: string[] = []) =>
|
|
55
|
+
"/" + segments.map(encodeURIComponent).join("/");
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
Why each step is there:
|
|
59
|
+
|
|
60
|
+
- **`cache()`** from React: `generateMetadata` and the page call `openPage`
|
|
61
|
+
with the same arguments in one request; they share one result.
|
|
62
|
+
- **`routes()`** reads `{ name, path }` of every page from the content index,
|
|
63
|
+
without page bodies. Do not route with `list("page")`: it fetches every
|
|
64
|
+
page and warns outside production.
|
|
65
|
+
- **`matchRoute(pathname, { routes, redirects })`** returns
|
|
66
|
+
`{ kind: "match", entry, params }`, `{ kind: "redirect", location, status }`
|
|
67
|
+
or `{ kind: "not-found" }`. Exact segments win over `:params`, params over a
|
|
68
|
+
trailing `*`. `match.params` holds the matched params.
|
|
69
|
+
- **`prefetch(name)`** starts fetching the page and everything it references
|
|
70
|
+
in one parallel wave, with the redirects block. It never throws.
|
|
71
|
+
- **Redirects** run before the not-found. Statuses are 301, 302, 307 or 308.
|
|
72
|
+
Next's `permanentRedirect` answers 308 and `redirect` 307.
|
|
73
|
+
- **`resolve(name)`** runs the page: `seo` and every block in `sections` are
|
|
74
|
+
resolved, so `sections` holds what each block function returned.
|
|
75
|
+
|
|
76
|
+
The example app also routes a custom block type (blog posts that carry a
|
|
77
|
+
`path`): it adds `(await c.list<Post>("post"))` to the routes it matches and
|
|
78
|
+
renders a matched post without resolving it.
|
|
79
|
+
|
|
80
|
+
## Results and errors
|
|
81
|
+
|
|
82
|
+
`resolve`, `list`, `routes` and `redirects` return a tuple instead of
|
|
83
|
+
throwing: `[value, null]` or `[null, CMSError]`. (`revision()` is the
|
|
84
|
+
exception: it rejects when content can't load.) `CMSError` has `code`, `message`, `path` (where in the
|
|
85
|
+
tree, such as `["sections", 2, "product"]`) and, for function failures,
|
|
86
|
+
`cause`.
|
|
87
|
+
|
|
88
|
+
| Code | Meaning |
|
|
89
|
+
|---|---|
|
|
90
|
+
| `NOT_FOUND` | No saved block by that name |
|
|
91
|
+
| `UNKNOWN_BLOCK` | A `__resolveType` not in the block map |
|
|
92
|
+
| `CYCLE` | Blocks reference each other in a loop |
|
|
93
|
+
| `BLOCK_FAILED` | A block function threw |
|
|
94
|
+
| `LOADER_FAILED` | The content didn't load. On a site with `site`, its `cause` is a `ContentUnavailableError` until the first load succeeds |
|
|
95
|
+
|
|
96
|
+
Throwing the error renders Next's error boundary. Decide per page whether a
|
|
97
|
+
failed block should fail the page or be skipped.
|
|
98
|
+
|
|
99
|
+
## Rendering sections
|
|
100
|
+
|
|
101
|
+
```tsx
|
|
102
|
+
// src/app/PageView.tsx
|
|
103
|
+
import { StudioPage } from "@decocms/nextjs";
|
|
104
|
+
import { Fragment, type ReactNode } from "react";
|
|
105
|
+
import type { Page } from "@decocms/blocks";
|
|
106
|
+
|
|
107
|
+
export function PageView({ page }: { page: Page<ReactNode> }) {
|
|
108
|
+
return (
|
|
109
|
+
<main>
|
|
110
|
+
{page.sections.map((section, index) => (
|
|
111
|
+
<Fragment key={index}>{section}</Fragment>
|
|
112
|
+
))}
|
|
113
|
+
<StudioPage pathTemplate={page.path} />
|
|
114
|
+
</main>
|
|
115
|
+
);
|
|
116
|
+
}
|
|
117
|
+
```
|
|
118
|
+
|
|
119
|
+
- A section function returns a React element, so the page renders the list
|
|
120
|
+
as is. A site may return descriptors instead (`{ component, props }`) and
|
|
121
|
+
map them itself; `Page<Section>` takes either.
|
|
122
|
+
- `StudioPage` renders a `<meta>` that tells the Studio bridge which page
|
|
123
|
+
template is on screen. See [studio-bridge.md](./studio-bridge.md).
|
|
124
|
+
- Sections are Server Components by default. Put interactive parts in a
|
|
125
|
+
`"use client"` component the section renders (the example's `ProductHero`
|
|
126
|
+
renders a client `CartButton`). Props passed to a client component must be
|
|
127
|
+
serializable.
|
|
128
|
+
- A client component that calls `useSearchParams()` renders on the client up
|
|
129
|
+
to its nearest `<Suspense>` on a cached page. Wrap it.
|
|
130
|
+
- A block prop that is a `lazy` block arrives as a function
|
|
131
|
+
`() => Promise<T>` that resolves only when called. Lazy blocks and loading
|
|
132
|
+
states: load `deco-site-authoring`.
|
|
133
|
+
|
|
134
|
+
## The two routes
|
|
135
|
+
|
|
136
|
+
```tsx
|
|
137
|
+
// src/app/%5Fassignments/[assignments]/[[...path]]/page.tsx
|
|
138
|
+
import { openPage, pathnameFor } from "../../../../open-page.server";
|
|
139
|
+
import { PageView } from "../../../PageView";
|
|
140
|
+
|
|
141
|
+
export const revalidate = 600;
|
|
142
|
+
export async function generateStaticParams() {
|
|
143
|
+
return [];
|
|
144
|
+
}
|
|
145
|
+
|
|
146
|
+
type Props = { params: Promise<{ assignments: string; path?: string[] }> };
|
|
147
|
+
|
|
148
|
+
export default async function Page({ params }: Props) {
|
|
149
|
+
const { assignments, path } = await params;
|
|
150
|
+
return <PageView page={await openPage(pathnameFor(path), assignments)} />;
|
|
151
|
+
}
|
|
152
|
+
```
|
|
153
|
+
|
|
154
|
+
The draft route is the same page with `bindDraft` first and
|
|
155
|
+
`DraftPreviewIndicator` after; see [proxy-and-drafts.md](./proxy-and-drafts.md).
|
|
156
|
+
Why the assignments route looks like this: [caching.md](./caching.md).
|
|
157
|
+
|
|
158
|
+
## Routes the app owns
|
|
159
|
+
|
|
160
|
+
A route outside the CMS (a blog index, an account page) calls
|
|
161
|
+
`await bindDraft(cms)` (with `{ searchParams }` on a page) and then reads with
|
|
162
|
+
`contentClient(cms)`, which uses the version, visitor and assignments the
|
|
163
|
+
proxy forwarded. Leave it out of the proxy's `isCmsPage` so it is not
|
|
164
|
+
rewritten. `bindDraft` reads request headers, so Next renders the route per
|
|
165
|
+
request.
|
|
166
|
+
|
|
167
|
+
`contentClient` only reads what `bindDraft` bound. Called without it, it
|
|
168
|
+
reads the current release with no visitor: every test is off, and campaigns
|
|
169
|
+
are checked against the current time.
|
|
170
|
+
|
|
171
|
+
Writing sections, loaders and page blocks: load `deco-site-authoring`.
|
|
@@ -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`.
|