@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,175 @@
|
|
|
1
|
+
# Proving nothing changed
|
|
2
|
+
|
|
3
|
+
Every conversion PR is checked three ways before merge: the HTML, the pixels,
|
|
4
|
+
and a live edit. A PR built from a Figma file is compared with the design
|
|
5
|
+
instead of with `main`.
|
|
6
|
+
|
|
7
|
+
## Two servers side by side
|
|
8
|
+
|
|
9
|
+
Run `main` and the branch at once. A separate worktree keeps `main` untouched:
|
|
10
|
+
|
|
11
|
+
```sh
|
|
12
|
+
git worktree add ../site-main origin/main
|
|
13
|
+
(cd ../site-main && bun install --frozen-lockfile && npx vite dev --port 5192) &
|
|
14
|
+
npx vite dev --port 5191 &
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
On a hosted site the branch reads its new blocks from a draft (see
|
|
18
|
+
[seeding-content.md](./seeding-content.md#a-hosted-site-site-set)). Add the
|
|
19
|
+
`__draft` value from `deco drafts url <name>` to every branch URL
|
|
20
|
+
(`?__draft=…`). Three things to know about draft pages on a site whose
|
|
21
|
+
document is `DecoDocument` (`@decocms/tanstack/react`):
|
|
22
|
+
|
|
23
|
+
- Once hydrated, a draft page shows a badge, fixed at the bottom left
|
|
24
|
+
(`[data-deco-preview-badge]`). Hide it before taking screenshots.
|
|
25
|
+
- If the link names a draft that cannot be read (deleted, or its host
|
|
26
|
+
failing), the page renders the release and shows a notice
|
|
27
|
+
(`[data-deco-preview-unavailable]`) instead of the badge.
|
|
28
|
+
- If the host is not allowed to preview, the page renders the release with
|
|
29
|
+
no badge and no notice (see "Draft hosts" in the `@decocms/tanstack`
|
|
30
|
+
README). So check that the badge is there: without it, the screenshot
|
|
31
|
+
compared the wrong content.
|
|
32
|
+
|
|
33
|
+
## HTML parity
|
|
34
|
+
|
|
35
|
+
Strip what is expected to differ (scripts and comments) and diff the rest.
|
|
36
|
+
The draft badge mounts in the browser after hydration, so it is not in the
|
|
37
|
+
server HTML:
|
|
38
|
+
|
|
39
|
+
```python
|
|
40
|
+
# body.py: normalize a page for diffing. Usage: curl -s URL | python3 body.py
|
|
41
|
+
import re, sys
|
|
42
|
+
s = sys.stdin.read()
|
|
43
|
+
t = re.search(r"<title>(.*?)</title>", s, flags=re.S)
|
|
44
|
+
print("TITLE", t.group(1) if t else None)
|
|
45
|
+
b = s[s.find("<body"):]
|
|
46
|
+
b = re.sub(r"<script.*?</script>", "", b, flags=re.S)
|
|
47
|
+
b = re.sub(r"<!--.*?-->", "", b, flags=re.S) # also React's streaming markers
|
|
48
|
+
print(b.replace("><", ">\n<"))
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
```sh
|
|
52
|
+
for p in / /pt /pricing /pt/pricing /docs/some-article; do
|
|
53
|
+
f=$(echo "$p" | tr / _)
|
|
54
|
+
curl -s "localhost:5192$p" | python3 body.py > "/tmp/main$f"
|
|
55
|
+
curl -s "localhost:5191$p?__draft=$DRAFT" | python3 body.py > "/tmp/new$f"
|
|
56
|
+
echo "$p: $(diff "/tmp/main$f" "/tmp/new$f" | grep -c '^[<>]') changed lines"
|
|
57
|
+
done
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
Zero changed lines is the goal. The site writes the loop that renders
|
|
61
|
+
sections, so it controls the markup: if a wrapper element appears, remove it
|
|
62
|
+
rather than accept it.
|
|
63
|
+
|
|
64
|
+
Include a few pages you did **not** convert but whose components you moved or
|
|
65
|
+
touched. They must be identical too.
|
|
66
|
+
|
|
67
|
+
## Pixel parity
|
|
68
|
+
|
|
69
|
+
Full-page screenshots of each page, in each language, at desktop and mobile
|
|
70
|
+
widths, on both servers, then a per-pixel diff.
|
|
71
|
+
|
|
72
|
+
Headless Chrome's `--screenshot` flag can hang on a Vite dev server (the HMR
|
|
73
|
+
socket never goes idle). `playwright-core` with a local Chromium works:
|
|
74
|
+
|
|
75
|
+
```js
|
|
76
|
+
// shot.mjs: npm i playwright-core in a scratch folder; CHROMIUM=path to a Chromium binary
|
|
77
|
+
import { chromium } from "playwright-core";
|
|
78
|
+
const DRAFT = process.env.DRAFT ? `?__draft=${process.env.DRAFT}` : "";
|
|
79
|
+
const browser = await chromium.launch({ executablePath: process.env.CHROMIUM });
|
|
80
|
+
for (const [w, h] of [[1440, 900], [390, 844]])
|
|
81
|
+
for (const [name, port, query] of [["main", 5192, ""], ["new", 5191, DRAFT]])
|
|
82
|
+
for (const path of ["/", "/pt", "/pricing"]) {
|
|
83
|
+
const page = await browser.newPage({ viewport: { width: w, height: h } });
|
|
84
|
+
page.on("pageerror", (e) => console.error(name, path, String(e)));
|
|
85
|
+
await page.goto(`http://localhost:${port}${path}${query}`, { waitUntil: "load" });
|
|
86
|
+
// The badge mounts after hydration; no badge means the release rendered, not the draft.
|
|
87
|
+
if (query) await page.waitForSelector("[data-deco-preview-badge]", { timeout: 10_000 });
|
|
88
|
+
await page.addStyleTag({ content: "[data-deco-preview-badge]{display:none!important}" });
|
|
89
|
+
// Scroll once so reveal-on-scroll animations and lazy images run.
|
|
90
|
+
await page.evaluate(async () => {
|
|
91
|
+
for (let y = 0; y < document.body.scrollHeight; y += 400) { scrollTo(0, y); await new Promise((r) => setTimeout(r, 50)); }
|
|
92
|
+
scrollTo(0, 0);
|
|
93
|
+
});
|
|
94
|
+
await page.waitForLoadState("networkidle").catch(() => {});
|
|
95
|
+
await page.waitForTimeout(700);
|
|
96
|
+
await page.screenshot({ path: `shots/${name}${path.replaceAll("/", "_")}-${w}.png`, fullPage: true });
|
|
97
|
+
await page.close();
|
|
98
|
+
}
|
|
99
|
+
await browser.close();
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
```python
|
|
103
|
+
# diff.py: pip install pillow
|
|
104
|
+
from PIL import Image, ImageChops
|
|
105
|
+
import glob
|
|
106
|
+
for m in sorted(glob.glob("shots/main*.png")):
|
|
107
|
+
n = m.replace("main", "new", 1)
|
|
108
|
+
a, b = Image.open(m).convert("L"), Image.open(n).convert("L")
|
|
109
|
+
if a.size != b.size: print(m, "SIZE", a.size, b.size); continue
|
|
110
|
+
d = ImageChops.difference(a, b); px = [p for p in d.getdata() if p]
|
|
111
|
+
print(m, "identical" if not px else f"{len(px)} px, max {max(px)}/255 in {d.getbbox()}")
|
|
112
|
+
```
|
|
113
|
+
|
|
114
|
+
Reading the result:
|
|
115
|
+
|
|
116
|
+
- A different page height, or any visible difference, is a regression.
|
|
117
|
+
- In a real conversion, a few dozen pixels at an intensity of 7/255 or less,
|
|
118
|
+
around a transition (a select chevron, an animated demo), were rendering
|
|
119
|
+
noise. Crop that box from both images and look before dismissing it.
|
|
120
|
+
- Sections that stream in (a `Suspense` boundary per section) can be caught
|
|
121
|
+
half-rendered. If one run shows a fallback, wait for it to go away
|
|
122
|
+
(`page.waitForSelector`) instead of raising the timeout everywhere.
|
|
123
|
+
|
|
124
|
+
## Against a Figma design
|
|
125
|
+
|
|
126
|
+
With no `main` to compare with, the baseline is the design:
|
|
127
|
+
|
|
128
|
+
1. Call `get_screenshot` on each section frame (desktop and mobile). Save as
|
|
129
|
+
`tests/visual-qa/baselines/<device>/<order>-<Section>.png`.
|
|
130
|
+
2. Screenshot each section of the page at the frame's width (1440 and 375 are
|
|
131
|
+
common). If the site renders an attribute per section, use it as a
|
|
132
|
+
locator; otherwise screenshot by section element order.
|
|
133
|
+
3. Compare by eye and list each mismatch. A pixel diff against a Figma render
|
|
134
|
+
is noisy (font rendering, antialiasing); it finds regions, it does not
|
|
135
|
+
judge them.
|
|
136
|
+
|
|
137
|
+
What to compare, per section:
|
|
138
|
+
|
|
139
|
+
- **Layout:** direction, alignment, grid columns, max width and centering,
|
|
140
|
+
order of elements.
|
|
141
|
+
- **Spacing:** padding, gaps, vertical rhythm between sections.
|
|
142
|
+
- **Type:** family, size, weight, line height, letter spacing, case, color.
|
|
143
|
+
- **Color:** backgrounds, borders, buttons, links, hover states.
|
|
144
|
+
- **Images:** the right asset, aspect ratio, crop (`object-fit`), radius.
|
|
145
|
+
- **Responsive:** both widths, and no jump at the breakpoints in between
|
|
146
|
+
(768px, 1024px).
|
|
147
|
+
|
|
148
|
+
Write the mismatches as a table and fix them one by one:
|
|
149
|
+
|
|
150
|
+
| # | Device | Section | Issue | Expected | Actual | Fix |
|
|
151
|
+
|---|---|---|---|---|---|---|
|
|
152
|
+
| 1 | desktop | Hero | title size | 48px | 36px | use the `display` text token |
|
|
153
|
+
| 2 | mobile | Header | menu icon missing | present | missing | render the menu button below `md` |
|
|
154
|
+
|
|
155
|
+
Re-screenshot after each fix and mark the row fixed. Done means every row is
|
|
156
|
+
fixed at both widths.
|
|
157
|
+
|
|
158
|
+
## Live edit
|
|
159
|
+
|
|
160
|
+
With the branch running, change the content and watch it land:
|
|
161
|
+
|
|
162
|
+
- change a text in each language and confirm it changes on that language's
|
|
163
|
+
pages only;
|
|
164
|
+
- empty a `fooPt` and confirm the secondary language falls back to `foo`;
|
|
165
|
+
- remove and reorder sections of a page and confirm the rendered order follows;
|
|
166
|
+
- break a required field and confirm `deco check` names it (`deco check
|
|
167
|
+
--draft=<name>` on a hosted site: without a flag it checks production).
|
|
168
|
+
|
|
169
|
+
With content in git, edit the block files (`deco content --watch` reloads the
|
|
170
|
+
page). On a hosted site, make the same edits in the draft, from Studio or with
|
|
171
|
+
`deco push --draft=<name>`. Restore the content afterwards.
|
|
172
|
+
|
|
173
|
+
Then the real path, end to end: open the page in Studio, edit, preview, and
|
|
174
|
+
publish (with the owner's OK) or discard the draft. Confirm the change on the
|
|
175
|
+
site. This is the half of the goal that the pixel checks do not prove.
|
|
@@ -0,0 +1,119 @@
|
|
|
1
|
+
# Seeding content from the current code
|
|
2
|
+
|
|
3
|
+
Never retype content. Extract it from the code that ships today. Byte-identical
|
|
4
|
+
content is what makes the [pixel comparison](./pixel-parity.md) mean
|
|
5
|
+
something: if a single apostrophe changed, you cannot tell a typo from a
|
|
6
|
+
regression.
|
|
7
|
+
|
|
8
|
+
## Extract with a throwaway script
|
|
9
|
+
|
|
10
|
+
Most hardcoded content is already data: a `COPY` object, a `LINKS` array. Load
|
|
11
|
+
it in isolation and write the block JSON from it.
|
|
12
|
+
|
|
13
|
+
```ts
|
|
14
|
+
// scripts/seed-header.ts (run once with `bun scripts/seed-header.ts`, then delete)
|
|
15
|
+
import fs from "node:fs";
|
|
16
|
+
import { LINKS } from "../src/components/Header.constants";
|
|
17
|
+
|
|
18
|
+
const block = {
|
|
19
|
+
__resolveType: "header-menu",
|
|
20
|
+
links: LINKS.map(({ label, labelPt, href }) => ({ label, labelPt, href })),
|
|
21
|
+
};
|
|
22
|
+
const name = "Header menu";
|
|
23
|
+
fs.writeFileSync(`.deco/blocks/${encodeURIComponent(name)}.json`, `${JSON.stringify(block, null, 2)}\n`);
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
- If the constant lives in a component file that imports React or CSS, move it
|
|
27
|
+
to its own module first (the component then imports it). That is a
|
|
28
|
+
refactor with no visual change; commit it separately.
|
|
29
|
+
- Component references in the data (`icon: RocketIcon`) cannot go into JSON.
|
|
30
|
+
Replace them with string keys and keep a closed list in code:
|
|
31
|
+
`const ICONS = { rocket: RocketIcon, book: BookIcon }`, with
|
|
32
|
+
`icon: keyof typeof ICONS` in `Props`. Editors then pick from a list instead
|
|
33
|
+
of typing a free-text name. `deco-cms-schema` shows how the form renders it.
|
|
34
|
+
- Text written straight in JSX has no constant to load. Copy it with the
|
|
35
|
+
script anyway (read the file, cut the strings), or paste it once and check
|
|
36
|
+
the [HTML diff](./pixel-parity.md#html-parity) shows no change.
|
|
37
|
+
- Once the block exists, delete the constant. Keeping it "as a fallback"
|
|
38
|
+
creates a second source of truth.
|
|
39
|
+
|
|
40
|
+
The file name is `encodeURIComponent(name)` plus `.json`, directly in
|
|
41
|
+
`.deco/blocks` (subfolders are not read).
|
|
42
|
+
|
|
43
|
+
## Content in git (no `site`)
|
|
44
|
+
|
|
45
|
+
A site created with `createCMS({ blocks, content })` and no `site` reads the
|
|
46
|
+
content module, `.deco/blocks.gen.ts`, bundled with the build.
|
|
47
|
+
|
|
48
|
+
```sh
|
|
49
|
+
deco schema # .deco/index.ts → .deco/schema.gen.json
|
|
50
|
+
deco content # .deco/blocks → .deco/blocks.gen.ts
|
|
51
|
+
deco check # every saved block against the schema (no DECO_SITE set)
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
During `vite dev`, `deco content --watch` rewrites the module on each save,
|
|
55
|
+
and the `decoContent()` plugin (included in `decoTanstack()`) swaps the new
|
|
56
|
+
content into the running CMS and reloads open pages. Edit a block file, and
|
|
57
|
+
the page shows it.
|
|
58
|
+
|
|
59
|
+
## A hosted site (`site` set)
|
|
60
|
+
|
|
61
|
+
A site created with `createCMS({ blocks, site })` reads its content from the
|
|
62
|
+
delivery CDN at runtime. The CLI finds the same site in `DECO_SITE` (the
|
|
63
|
+
environment, `.env`, `.dev.vars` or `vars` in the wrangler config). The local
|
|
64
|
+
`.deco/blocks` is what `deco pull` wrote, and changes travel as drafts:
|
|
65
|
+
|
|
66
|
+
```sh
|
|
67
|
+
deco pull # production into .deco/blocks
|
|
68
|
+
# write or edit the seeded files
|
|
69
|
+
deco diff # what changed since the pull
|
|
70
|
+
deco push --draft=header-menu # one save into the draft (creates it); prints its preview link
|
|
71
|
+
deco check --draft=header-menu # the draft against the local .deco/schema.gen.json
|
|
72
|
+
deco drafts url header-menu # the preview link again
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
- `deco push` sends only the blocks changed since the pull. Deletes are sent
|
|
76
|
+
only with `--prune`.
|
|
77
|
+
- One push is one save, at most 500 blocks and 8 MiB. A larger push fails with
|
|
78
|
+
"don't fit one save": push fewer blocks at a time.
|
|
79
|
+
- `deco check --draft` validates the draft against the schema on disk, so it
|
|
80
|
+
checks the branch's new types before anything is deployed.
|
|
81
|
+
- Open the preview link on a local dev server of the branch to see the seeded
|
|
82
|
+
content with the new code. A draft page shows a "Preview mode" badge. With
|
|
83
|
+
no badge, the page rendered the release: either the host is not allowed to
|
|
84
|
+
preview (no notice; see "Draft hosts" in the `@decocms/tanstack` README, and
|
|
85
|
+
`deco-site-workflow`), or the draft could not be read (a notice says so).
|
|
86
|
+
|
|
87
|
+
The full set of content commands (`drafts`, `publish`, `releases`, rollback)
|
|
88
|
+
is in `deco-site-workflow`.
|
|
89
|
+
|
|
90
|
+
## Order of publish and deploy
|
|
91
|
+
|
|
92
|
+
On a hosted site, content and code ship separately. Pick the order so that the
|
|
93
|
+
live site never runs code that reads a block that is not published yet:
|
|
94
|
+
|
|
95
|
+
1. Publish the draft with the **new** blocks first. Old code never reads them,
|
|
96
|
+
so this changes nothing on the live site.
|
|
97
|
+
2. Deploy the code that reads them. The production deploy should also run
|
|
98
|
+
`deco schema push` (see `deco-site-workflow`): that is what gives Studio
|
|
99
|
+
the forms for the new types.
|
|
100
|
+
3. Only then publish changes to **existing** blocks that the old code would
|
|
101
|
+
not understand, such as a page whose sections now use a new section type.
|
|
102
|
+
|
|
103
|
+
Do not run `deco publish` without the site owner's explicit OK for that
|
|
104
|
+
publish.
|
|
105
|
+
|
|
106
|
+
## What `deco check` covers
|
|
107
|
+
|
|
108
|
+
`deco check` validates each saved block against the generated schema:
|
|
109
|
+
|
|
110
|
+
- required fields that are missing, unknown fields, wrong types, values
|
|
111
|
+
outside an `@options` list;
|
|
112
|
+
- a `__resolveType` that names no block type, built-in or saved block;
|
|
113
|
+
- a block placed in a field it does not fit;
|
|
114
|
+
- page paths that conflict, and redirect rules outside the redirects block.
|
|
115
|
+
|
|
116
|
+
It does not check that an internal link (`href: "/pricing"`) points at a page
|
|
117
|
+
that exists, and an empty string passes a required string field. If either
|
|
118
|
+
matters for your site, add a small script to CI that walks `.deco/blocks` for
|
|
119
|
+
link fields and compares them with the page paths and the site's own routes.
|
|
@@ -0,0 +1,74 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: deco-nextjs-site
|
|
3
|
+
description: "Wiring a Next.js App Router site to @decocms/nextjs 8 (with @decocms/blocks 8, Next 16, React 19): the block map in .deco/index.tsx and the two createCMS handles, withDeco in next.config, the proxy (@decocms/nextjs/proxy: decideDraft, decideVisitor, decideAssignments, the /_draft and /_assignments rewrites, or draftProxy), reading and rendering resolved pages in Server Components (@decocms/nextjs/server: bindDraft, contentClient, assignedClient; matchRoute, redirects, notFound), page metadata from the page's seo block, ISR caching on the assignments route (revalidate = 600, never force-static, assignmentsKey for a CDN), the Studio bridge (StudioBridge, StudioPage, withStudioCsp), the next/image loader (@decocms/nextjs/image-loader) and the request metric (@decocms/nextjs/instrumentation). Load it for any v8 site built on Next.js: scaffolding, a draft that does not show, a page that renders on every request instead of caching, Studio not driving the page, or wrong metadata."
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Deco on Next.js (v8)
|
|
7
|
+
|
|
8
|
+
`@decocms/nextjs` 8 is a set of small helpers a Next.js App Router site calls
|
|
9
|
+
from its own `proxy.ts`, layouts, pages and `next.config`. It makes no hosting
|
|
10
|
+
assumption: no CDN, no platform rules. Content comes from `@decocms/blocks`
|
|
11
|
+
(`createCMS`, `client.resolve`, `matchRoute`); this package adds draft
|
|
12
|
+
previews, tests and campaigns decided once per request, Next's cache, and the
|
|
13
|
+
Studio bridge.
|
|
14
|
+
|
|
15
|
+
Load the reference for the job in front of you. Every name below exists in
|
|
16
|
+
`packages/nextjs/src` or `packages/blocks/src/v8`. The full working app is
|
|
17
|
+
`examples/nextjs-binding-smoke` in this repository: when this skill and that
|
|
18
|
+
example disagree, the example wins.
|
|
19
|
+
|
|
20
|
+
## When to load what
|
|
21
|
+
|
|
22
|
+
| Reference | Load it when |
|
|
23
|
+
|---|---|
|
|
24
|
+
| [`references/setup.md`](./references/setup.md) | Starting a site or adding Deco to a Next app: packages, file layout, the block map, the two CMS handles, `withDeco`, scripts, the image loader, the request metric |
|
|
25
|
+
| [`references/proxy-and-drafts.md`](./references/proxy-and-drafts.md) | Writing `proxy.ts`; a Studio draft link shows the published page; preview hosts; the draft route and `bindDraft`; the preview badge |
|
|
26
|
+
| [`references/rendering.md`](./references/rendering.md) | Reading and rendering a page in a Server Component: routes, redirects, `resolve`, sections, client components, errors |
|
|
27
|
+
| [`references/metadata-seo.md`](./references/metadata-seo.md) | `<title>` or description wrong or missing; the `seo` block; noindex on drafts |
|
|
28
|
+
| [`references/caching.md`](./references/caching.md) | ISR, the assignments route, a page that renders on every request, a CDN in front, stale content after publish |
|
|
29
|
+
| [`references/studio-bridge.md`](./references/studio-bridge.md) | Studio cannot select or reload sections, "." opens the wrong page, CSP blocks Studio, a local Studio |
|
|
30
|
+
|
|
31
|
+
## The shape of a request
|
|
32
|
+
|
|
33
|
+
1. `proxy.ts` decides once: the version (a Studio link's draft or old
|
|
34
|
+
release, on an allowed host), the visitor (`deco_segment` cookie) and every
|
|
35
|
+
test and campaign on or off.
|
|
36
|
+
2. A published CMS page is rewritten to `/_assignments/<segment>/<path>`. The
|
|
37
|
+
page reads no request, so Next caches it (ISR).
|
|
38
|
+
3. A preview request is rewritten to `/_draft/<path>`. That route is dynamic,
|
|
39
|
+
binds the draft with `bindDraft`, and is never cached.
|
|
40
|
+
4. Both routes build one content client, match the path, follow redirects,
|
|
41
|
+
resolve the page and render its sections.
|
|
42
|
+
|
|
43
|
+
## Rules that are easy to break
|
|
44
|
+
|
|
45
|
+
- The route folders are `app/%5Fdraft/...` and `app/%5Fassignments/...`. A
|
|
46
|
+
folder named `_draft` is private in Next and never routes.
|
|
47
|
+
- Never call `bindDraft`, `headers()`, `cookies()` or `searchParams` on the
|
|
48
|
+
assignments route or in the root layout. Any of them makes Next render the
|
|
49
|
+
page on every request.
|
|
50
|
+
- Never `export const dynamic = "force-static"` on a CMS page. Use
|
|
51
|
+
`revalidate`.
|
|
52
|
+
- The proxy imports a CMS handle with an empty block map
|
|
53
|
+
(`createCMS({ blocks: {}, ...cmsConfig })`), so no section reaches the proxy
|
|
54
|
+
bundle.
|
|
55
|
+
- Never edit generated files (`.deco/schema.gen.json`, `.deco/blocks.gen.ts`).
|
|
56
|
+
Change the types or the content and run the CLI again.
|
|
57
|
+
|
|
58
|
+
## Not in v8
|
|
59
|
+
|
|
60
|
+
v7's `createNextSetup`, `createDecoRouteHandlers`, `createDecoPreviewPage`,
|
|
61
|
+
the `/setup` and `/routeHandlers` subpaths, `src/sections/*` shims as block
|
|
62
|
+
keys, `generate:deco` and the `/deco/*` admin routes do not exist in
|
|
63
|
+
`@decocms/nextjs` 8. Moving a v7 site: load `deco-v7-to-v8-migration`.
|
|
64
|
+
|
|
65
|
+
## Related skills
|
|
66
|
+
|
|
67
|
+
- `deco-site-workflow`: the `deco` CLI (`schema`, `schema push`, `check`,
|
|
68
|
+
`pull`, `push --draft`, `publish`) and how releases reach the site.
|
|
69
|
+
- `deco-site-authoring`: writing sections, pages and loaders.
|
|
70
|
+
- `deco-cms-schema`: how a Props type becomes the Studio form.
|
|
71
|
+
- `deco-variants`: multivariate blocks, tests and campaigns.
|
|
72
|
+
- `deco-images-media`: image providers, quality and LCP.
|
|
73
|
+
- `deco-storefront-caching`: cache keys and egress, with the Next equivalents.
|
|
74
|
+
- `deco-tanstack-site`: the same wiring on TanStack Start.
|
|
@@ -0,0 +1,116 @@
|
|
|
1
|
+
# Caching and ISR on Next
|
|
2
|
+
|
|
3
|
+
The binding caches nothing itself. It shapes requests so Next's own cache
|
|
4
|
+
(ISR, keyed by path) can keep published pages, while previews and
|
|
5
|
+
per-visitor decisions stay out of it.
|
|
6
|
+
|
|
7
|
+
## The assignments route
|
|
8
|
+
|
|
9
|
+
Next caches a page by its path. Tests and campaigns change what a page shows,
|
|
10
|
+
so the proxy puts its decision into the path:
|
|
11
|
+
|
|
12
|
+
```
|
|
13
|
+
/shoes → /_assignments/<segment>/shoes
|
|
14
|
+
```
|
|
15
|
+
|
|
16
|
+
- The segment lists every test of the saved `experiments` block on or off for
|
|
17
|
+
this visitor, and every campaign of the saved `campaigns` block running or
|
|
18
|
+
not now. `-` means none; otherwise it is base64url, one spelling per set.
|
|
19
|
+
- The visitor id is never in it. Visitors on the same side of every test
|
|
20
|
+
share one path and one cache entry.
|
|
21
|
+
- A campaign starting or ending moves every visitor to a new path.
|
|
22
|
+
- The rewritten request carries no visitor and no draft header. The page
|
|
23
|
+
builds its client from the path alone (`assignedClient`), so it reads no
|
|
24
|
+
request.
|
|
25
|
+
|
|
26
|
+
```tsx
|
|
27
|
+
// src/app/%5Fassignments/[assignments]/[[...path]]/page.tsx
|
|
28
|
+
export const revalidate = 600; // 10 minutes; never force-static
|
|
29
|
+
export async function generateStaticParams() {
|
|
30
|
+
return []; // nothing at build time: each path renders on first request, then is cached
|
|
31
|
+
}
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
## What the numbers mean
|
|
35
|
+
|
|
36
|
+
`revalidate = 600`: Next serves a stored page for 10 minutes. The first
|
|
37
|
+
request after that still gets the stored copy while Next renders the page
|
|
38
|
+
again in the background. So:
|
|
39
|
+
|
|
40
|
+
- A published change shows within about 10 minutes on a page people visit.
|
|
41
|
+
- A page nobody opened for longer shows its old copy once more.
|
|
42
|
+
- A banner can switch on a few minutes late. That delay is accepted.
|
|
43
|
+
|
|
44
|
+
On a site with `site`, the CMS also checks for a new release every `interval`
|
|
45
|
+
(default and minimum 60 000 ms). A re-render picks up whatever release the
|
|
46
|
+
process holds at that moment.
|
|
47
|
+
|
|
48
|
+
Never use `force-static` on a CMS page. A page that never expires keeps what
|
|
49
|
+
it rendered first, forever.
|
|
50
|
+
|
|
51
|
+
## What makes a page render on every request
|
|
52
|
+
|
|
53
|
+
Any of these anywhere in the route, its layouts included:
|
|
54
|
+
|
|
55
|
+
- `headers()`, `cookies()` or `searchParams`;
|
|
56
|
+
- `bindDraft` (it reads `headers()`), so the `contentClient(cms)` pattern
|
|
57
|
+
that needs it (use `assignedClient` here);
|
|
58
|
+
- `export const dynamic = "force-dynamic"`.
|
|
59
|
+
|
|
60
|
+
A client component calling `useSearchParams()` does not stop the cache, but
|
|
61
|
+
renders on the client up to its nearest `<Suspense>`.
|
|
62
|
+
|
|
63
|
+
Check with `curl -sI https://<host>/<path>` twice: the second response should
|
|
64
|
+
show `x-nextjs-cache: HIT` (or `STALE` after 10 minutes). The example app's
|
|
65
|
+
smoke test checks exactly this.
|
|
66
|
+
|
|
67
|
+
## Rules the route depends on
|
|
68
|
+
|
|
69
|
+
- **Direct hits are a 404.** The proxy answers `/_assignments/…` and
|
|
70
|
+
`/_draft/…` with 404 (`isAssignmentsRoutePath`, `isDraftRoutePath`), so only
|
|
71
|
+
its own rewrite reaches the route. Otherwise anyone could switch a test on
|
|
72
|
+
by typing a path.
|
|
73
|
+
- **Unknown names stay off, not 404.** `assignedClient` keeps off a test at 0%
|
|
74
|
+
and drops a test or campaign the content doesn't have. It returns `null`
|
|
75
|
+
(answer `notFound()`) only for a segment the proxy never writes. Next would
|
|
76
|
+
cache a 404 under the path, and a path written just before a publish must
|
|
77
|
+
still render.
|
|
78
|
+
- **Previews never land here.** `rewriteToAssignmentsRoute` returns `null` for
|
|
79
|
+
any preview; those render on the dynamic `/_draft` route.
|
|
80
|
+
- **Only CMS pages.** The proxy calls it only for paths its `isCmsPage` (the
|
|
81
|
+
site's own function) accepts.
|
|
82
|
+
|
|
83
|
+
## A CDN in front of Next
|
|
84
|
+
|
|
85
|
+
The URL the visitor asked for (`/shoes`) answers by their cookie and the
|
|
86
|
+
current time, even though Next's entry is shared. So when the content saves
|
|
87
|
+
tests or campaigns, the rewrite marks the response
|
|
88
|
+
`Cache-Control: private, no-cache`. Do not override that with a shared
|
|
89
|
+
`s-maxage` at the CDN.
|
|
90
|
+
|
|
91
|
+
A site that caches pages in front of Next keys on the assignments, never on
|
|
92
|
+
the visitor:
|
|
93
|
+
|
|
94
|
+
```ts
|
|
95
|
+
import { assignmentsKey, decideAssignments } from "@decocms/nextjs/proxy";
|
|
96
|
+
|
|
97
|
+
const key = assignmentsKey(await decideAssignments(proxyCms, draft, visitor));
|
|
98
|
+
// the version, the tests on and the campaigns running; "" when there are none
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
Never store a response that carries `?__draft=` or the `__deco_draft` cookie.
|
|
102
|
+
Those responses carry `Cache-Control: max-age=0, no-cache, must-revalidate`
|
|
103
|
+
and `Vary: Cookie`.
|
|
104
|
+
|
|
105
|
+
## Stale content after publishing
|
|
106
|
+
|
|
107
|
+
1. Wait out `revalidate` and request the page twice: the second request
|
|
108
|
+
gets the new render.
|
|
109
|
+
2. Check the release the process holds: a site with `site` reloads it every
|
|
110
|
+
`interval`.
|
|
111
|
+
3. Check that no CDN or `headers()` rule adds a long shared `max-age` on top.
|
|
112
|
+
4. A page on the draft route is never stale: if the draft shows the change
|
|
113
|
+
and the published page doesn't, it is the cache, not the content.
|
|
114
|
+
|
|
115
|
+
Cache keys, hit rate and egress in general: load `deco-storefront-caching`.
|
|
116
|
+
Tests and campaigns content: load `deco-variants`.
|
|
@@ -0,0 +1,100 @@
|
|
|
1
|
+
# Metadata from blocks
|
|
2
|
+
|
|
3
|
+
On Next, a page's `<title>`, description and other head tags come from
|
|
4
|
+
`generateMetadata`. On a Deco page, the source is the page block's `seo`
|
|
5
|
+
field. This file covers the wiring; what to put in SEO content and JSON-LD is
|
|
6
|
+
in `deco-site-authoring`.
|
|
7
|
+
|
|
8
|
+
## The seo block
|
|
9
|
+
|
|
10
|
+
`@decocms/blocks` types it as `Seo { title: string; description: string }`,
|
|
11
|
+
and the built-in `page` block carries an optional `seo` next to `sections`.
|
|
12
|
+
There is no built-in `seo` block function: the site registers one in its block
|
|
13
|
+
map, so Studio can draw the form and saved pages can reference it.
|
|
14
|
+
|
|
15
|
+
```tsx
|
|
16
|
+
// .deco/index.tsx
|
|
17
|
+
import type { Blocks, Seo } from "@decocms/blocks";
|
|
18
|
+
|
|
19
|
+
export default {
|
|
20
|
+
seo: (input: Seo) => input,
|
|
21
|
+
// … sections …
|
|
22
|
+
} satisfies Blocks;
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
```json
|
|
26
|
+
{
|
|
27
|
+
"__resolveType": "page",
|
|
28
|
+
"name": "Summer shirt",
|
|
29
|
+
"path": "/:slug/p",
|
|
30
|
+
"seo": {
|
|
31
|
+
"__resolveType": "seo",
|
|
32
|
+
"title": "Summer shirt | My store",
|
|
33
|
+
"description": "Light cotton shirt for hot days."
|
|
34
|
+
},
|
|
35
|
+
"sections": []
|
|
36
|
+
}
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
When `resolve` runs the page, `seo` is resolved too: `page.seo` holds what the
|
|
40
|
+
`seo` function returned.
|
|
41
|
+
|
|
42
|
+
Need more fields (canonical, Open Graph image, noindex)? Give the site's `seo`
|
|
43
|
+
function its own Props type that extends `Seo`, and type the resolved page
|
|
44
|
+
with your own interface instead of `Page`. The CMS passes the props through;
|
|
45
|
+
nothing in the binding reads them.
|
|
46
|
+
|
|
47
|
+
## generateMetadata
|
|
48
|
+
|
|
49
|
+
```tsx
|
|
50
|
+
// src/app/%5Fassignments/[assignments]/[[...path]]/page.tsx
|
|
51
|
+
import type { Metadata } from "next";
|
|
52
|
+
import { openPage, pathnameFor } from "../../../../open-page.server";
|
|
53
|
+
|
|
54
|
+
type Props = { params: Promise<{ assignments: string; path?: string[] }> };
|
|
55
|
+
|
|
56
|
+
export async function generateMetadata({ params }: Props): Promise<Metadata> {
|
|
57
|
+
const { assignments, path } = await params;
|
|
58
|
+
const page = await openPage(pathnameFor(path), assignments);
|
|
59
|
+
return { title: page.seo?.title, description: page.seo?.description };
|
|
60
|
+
}
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
- `openPage` is wrapped in React's `cache()` ([rendering.md](./rendering.md)),
|
|
64
|
+
so the metadata and the page share one resolve per request.
|
|
65
|
+
- On the assignments route, read only `params`. Reading `headers()`,
|
|
66
|
+
`cookies()` or `searchParams` in `generateMetadata` makes the page render
|
|
67
|
+
on every request, the same as in the page.
|
|
68
|
+
- On the draft route, call `bindDraft` before `openPage` in
|
|
69
|
+
`generateMetadata` too: Next may run it before the page body.
|
|
70
|
+
- Leave a field `undefined` when the page has no `seo`. Next then uses the
|
|
71
|
+
root layout's `metadata` (site defaults, a `title.template`).
|
|
72
|
+
|
|
73
|
+
## Drafts are noindex
|
|
74
|
+
|
|
75
|
+
A preview must never be indexed. Two layers already do it:
|
|
76
|
+
|
|
77
|
+
- The proxy's `applyDraft` sets `X-Robots-Tag: noindex, nofollow`,
|
|
78
|
+
`Cache-Control: max-age=0, no-cache, must-revalidate` and `Vary: Cookie` on
|
|
79
|
+
every preview response.
|
|
80
|
+
- `withDeco`'s header rules add `X-Robots-Tag: noindex, nofollow` to any
|
|
81
|
+
request with `?__draft=` or the `__deco_draft` cookie.
|
|
82
|
+
|
|
83
|
+
Do not remove either to "fix" a header conflict. If a site-wide rule in
|
|
84
|
+
`headers()` sets `Cache-Control`, `withDeco` already places the draft rules
|
|
85
|
+
first.
|
|
86
|
+
|
|
87
|
+
## Head tags the binding adds
|
|
88
|
+
|
|
89
|
+
`StudioPage` renders `<meta name="deco:page" content="<path template>">`.
|
|
90
|
+
React hoists it into `<head>`; it does not change the page's markup or SEO.
|
|
91
|
+
|
|
92
|
+
## Checks
|
|
93
|
+
|
|
94
|
+
- `curl -s https://<host>/<path> | grep -i '<title>'` shows the page's
|
|
95
|
+
`seo.title`, not the layout default.
|
|
96
|
+
- A page with a `:slug` path has one `seo` for every slug. Per-item titles
|
|
97
|
+
(a product name) come from a loader that the `seo` block reads; load
|
|
98
|
+
`deco-site-authoring`.
|
|
99
|
+
- `curl -sI 'https://<host>/<path>?__draft=<name>'` shows
|
|
100
|
+
`X-Robots-Tag: noindex, nofollow`.
|