@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,16 @@
|
|
|
1
|
+
# Hosted releases, bundled content and v7 leftovers
|
|
2
|
+
|
|
3
|
+
From the site migrations; the sites and what the commit hashes refer to are listed in `SKILL.md` ("Gotchas by subject").
|
|
4
|
+
|
|
5
|
+
## Hosted releases and bundled content
|
|
6
|
+
|
|
7
|
+
**v7 fast deploy becomes the hosted CMS.** A v7 TanStack site that published content without a deploy (`DECO_FAST_DEPLOY` plus a `DECO_KV` namespace) needs `site` on `createCMS` for the same feature (and `token` for hosted telemetry): the site reads its own `DECO_SITE` var and `DECO_SITE_TOKEN` secret and passes them, since the SDK reads no environment variable; without `site` every content change needs a deploy. Put the two `wrangler secret put` commands in the deploy checklist. v8 keeps content out of the bundle too: with `site`, it is fetched at runtime only. On a site with ~300 saved blocks (11 MB of JSON), Node measured about 13 MB per parsed copy, plus a transient string up to twice the JSON while a snapshot parses: under the Workers 128 MB limit, but measure memory and cold start with `wrangler tail` on a preview before turning it on.
|
|
8
|
+
|
|
9
|
+
With `site` set on `createCMS`, a published release goes live without a deploy, but only for what reads through the CMS client. Before turning it on, grep for direct imports of `.deco/blocks/*.json` (redirects, proxy tables, config blocks) and for build-time scripts that read `.deco/blocks`: those stay on the last deploy. v7 behaved the same, so it isn't a parity break; route them through the client or document the limitation and keep hosted releases off until you do.
|
|
10
|
+
|
|
11
|
+
## v7 leftovers to delete
|
|
12
|
+
|
|
13
|
+
- Env vars and comments for the v7 admin protocol (`DANGEROUSLY_ALLOW_PUBLIC_ACCESS`, admin public keys) and for settings that lived in the v7 `site` app block.
|
|
14
|
+
- Middleware/proxy exclusions for `/deco`, `/live` and `/.decofile`: the routes are gone. Removing the exclusion sends these paths down the unknown-path route, which may ask upstream (a redirect lookup) on every stray hit from old tooling and scanners; keeping it may send them to a catch-all that does worse (a search fallback answering 200). Skip the upstream work for them explicitly, and check the status (404) and the upstream calls for each path in the parity run.
|
|
15
|
+
- Add the site's new env vars (`DECO_SITE`, `DECO_SITE_TOKEN`, which the site passes as `createCMS({ site, token })`) to its env example, the token marked secret, and blank them in parity runs.
|
|
16
|
+
- **Editor settings that disappear with the `site` block.** Deleting the v7 `site` app block (apps are code now) also deletes any setting editors changed there, such as the site's name. Moving it to code is fine, but it is an editor-visible change: list it for the product owner. Its preview hosts need nothing: Studio writes where each site previews into the release metadata, and `createCMS({ site })` reads them.
|
|
@@ -0,0 +1,81 @@
|
|
|
1
|
+
# Import map: v7 → v8
|
|
2
|
+
|
|
3
|
+
What `scripts/imports.ts` does with each v7 `@decocms/*` import in the site's `src/`. Source of truth: `V8_API`, `MOVES`, `NAME_HINTS` and `HINTS` in that file; keep these tables in step with them.
|
|
4
|
+
|
|
5
|
+
## Rewritten by the script
|
|
6
|
+
|
|
7
|
+
| v7 import | Becomes |
|
|
8
|
+
|---|---|
|
|
9
|
+
| `@decocms/apps-<x>/loaders/…`, `…/actions/…` that the content calls | the vendored copy in `src/vendor/<app>/…` (relative import) |
|
|
10
|
+
| `createInstrumentedFetch` from `@decocms/blocks/sdk/instrumentedFetch` | `createInstrumentedFetch` from `@decocms/blocks/fetch`; `createInstrumentedFetch("x")` becomes `createInstrumentedFetch({ provider: "x" })` |
|
|
11
|
+
| `createDecoRouter`, `decoParseSearch`, `decoStringifySearch` (`@decocms/tanstack`) | the same names from `@decocms/tanstack/router` |
|
|
12
|
+
| `NavigationProgress`, `StableOutlet` (`@decocms/tanstack`) | the same names from `@decocms/tanstack/react` |
|
|
13
|
+
| `decoServerFnFetch` (`@decocms/tanstack/sdk/serverFnFetch`) | `@decocms/tanstack/start` |
|
|
14
|
+
| `Image`, `Picture`, `Source` and their props types (`@decocms/blocks/hooks`), on a TanStack site | `@decocms/tanstack/react`, same props and markup. The binding knows no platform, so the script writes `src/imageUrl.ts` (v7's URLs: the platforms' helpers from `@decocms/apps-vtex/image` and `@decocms/apps-shopify/image`, then `decoCdn` with the site's release rules, or its own copy's, and its registered domain and quality) and puts `<ImageUrlProvider value={imageUrl}>` in `createDecoRouter`'s `Wrap` |
|
|
15
|
+
| `DRAFT_PARAM`, `DRAFT_COOKIE`, `draftResponseHeaders`, `STUDIO_ORIGINS`, `STUDIO_FRAME_ANCESTORS`, `isStudioOrigin` (`@decocms/blocks`, a prerelease) | the site's binding root: `@decocms/tanstack` or `@decocms/nextjs` (reported when the site has neither) |
|
|
16
|
+
| `@decocms/apps-commerce/<subpath>` (`types`, `types/cart`, `sdk/*`, `utils/*`; also a stray 6.x `@decocms/apps/commerce/<subpath>`) | `@decocms/compat-v7/commerce/<subpath>`: the same files, React-free, v7's output. v7's app runtime (`app-types`, `registry`, `resolve`, `manifest-utils`) is reported |
|
|
17
|
+
| `clx` (`@decocms/blocks/sdk/clx`, `/sdk`) | `@decocms/compat-v7/clx` |
|
|
18
|
+
| `useScript`, `useScriptAsDataURI`, `inlineScript` (`/sdk/useScript`, `/sdk`) | `@decocms/compat-v7/script`, v7's bytes |
|
|
19
|
+
| `detectDevice`, `isMobileUA`, `Device`, `MOBILE_RE`, `TABLET_RE` (`/sdk/detectDevice`, `/sdk/useDevice`, `/sdk`) | `@decocms/compat-v7/device` |
|
|
20
|
+
| `useDevice`, `DeviceProvider`, `DeviceContext` (`/sdk/useDevice`, `/sdk`) | `@decocms/compat-v7/tanstack` or `/nextjs`, by binding; the report says how to seed the provider with `requestDevice()` |
|
|
21
|
+
| `SectionProps`, `Resolved`, `LoadingFallbackProps`, `Flag` (`@decocms/blocks`, `/types`); the widgets (`ImageWidget`, `Color`, `RichText`, …, `/types/widgets`) | `@decocms/compat-v7/types`, `@decocms/compat-v7/types/widgets` (`deco schema` reads the widget names from there too) |
|
|
22
|
+
| `compose`, `withDevice`, `withMobile`, `withSearchParam`, `withSectionLoader` (`@decocms/blocks/cms`) | `@decocms/compat-v7/sections` |
|
|
23
|
+
| `registerSectionLoaders({ … })`, `registerNonCriticalSections([…])` | `export const sectionLoaders` and `nonCriticalSections` in the same file, run by `loadSections` in `.deco/index.ts` (`runSectionLoaders` with v7's rules; the nested walk follows the site's 7.x release) |
|
|
24
|
+
| `ctx.device` in a v7 loader `(props, req, ctx)` | `detectDevice(req.headers.get("user-agent") ?? "")`, exactly v7's `ctx.device`; any other `ctx.*` read is reported (it throws in v8) |
|
|
25
|
+
|
|
26
|
+
An import that mixes moved and other names is split; the rest is reported.
|
|
27
|
+
|
|
28
|
+
## Left alone (already the v8 API)
|
|
29
|
+
|
|
30
|
+
`@decocms/blocks` (the root's v8 names: `createCMS`, `matchRoute`, `remoteLoader`, `parseDraftPointer`, `Blocks`, `Lazy`, `Seo`, …), `@decocms/blocks/fetch`, `/analytics`, `/cli`, `/image` (platform-neutral: `createImageUrl`, `decoCdn`, `srcSet`, `parseSrcSet`, `preloadLink`), `/vite`, `/preview` (`DraftBadge`, `StudioBridge`, `StudioPage`); the platforms' image helpers, `@decocms/apps-vtex/image` and `@decocms/apps-shopify/image`; the root of `@decocms/tanstack` 8 (the draft names and Studio's origins) and every subpath (`/worker`, `/server`, `/start`, `/router`, `/react`, `/scope`, and `/vite`'s `decoTanstack`), and of `@decocms/nextjs` 8 (`/proxy`, `/server`, `/image-loader`, `/config`'s `withDeco`, the root's `StudioBridge`, `StudioPage`, `DraftBadge`, draft names and Studio's origins); every `@decocms/compat-v7` entry point.
|
|
31
|
+
|
|
32
|
+
## Reported, with where the replacement lives (first match wins)
|
|
33
|
+
|
|
34
|
+
| v7 import | Replacement |
|
|
35
|
+
|---|---|
|
|
36
|
+
| `@decocms/start`, `@decocms/start/*` | a 6.x import: upgrade the site to 7.x first |
|
|
37
|
+
| `@decocms/blocks/sdk/cachedLoader` | gone: an upstream cache is your own `fetch`, passed to `createInstrumentedFetch` (`/next/caching#upstream-data`) |
|
|
38
|
+
| `…/invoke`, `createInvoke`, `@decocms/blocks/sdk/invoke` | `/deco/invoke` is gone: the script writes one server function per key and imports it at each call site (`references/server-functions.md`), never a rebuilt invoke tree (`/next/renames-and-migrations#loaders-actions-and-invoke`) |
|
|
39
|
+
| `@decocms/blocks-admin/*` | v8 sites serve no admin endpoints; the site editor uses the content protocol (`/next/studio-compatibility`) |
|
|
40
|
+
| `@decocms/blocks-cli/*` | codegen is the `deco` CLI in `@decocms/blocks`: `deco schema`, `deco content`, `deco check` (`/next/cli`) |
|
|
41
|
+
| `@decocms/blocks/setup`, `@decocms/blocks/cms/*` | `createCMS` from `@decocms/blocks`, with the block map in `.deco/index.ts` (`/next/content#create-the-cms`) |
|
|
42
|
+
| `@decocms/blocks/sdk/instrumentedFetch` (other names) | `createInstrumentedFetch({ provider, fetch?, retry?, circuitBreaker? })` from `@decocms/blocks/fetch` |
|
|
43
|
+
| `@decocms/blocks/sdk/otel`, `/sdk/observability`, `/sdk/logger`, `/middleware/observability` | the `telemetry` option of `createCMS` (`/next/telemetry`) |
|
|
44
|
+
| `…/Analytics`, `…/OneDollarStats`, `@decocms/blocks/sdk/analytics` | `AnalyticsScript` and `track` from `@decocms/blocks/analytics`, with the `analytics` section of `cms.settings()` (`/next/analytics`) |
|
|
45
|
+
| `@decocms/apps-salesforce`, `@decocms/apps/salesforce` | `@decocms/apps-sfmc-personalization` |
|
|
46
|
+
| `@decocms/apps-website`, `@decocms/apps/website` | SEO, sitemaps, redirects live in your platform template |
|
|
47
|
+
| any other `@decocms/apps-<x>`, `@decocms/apps/<x>` | apps are thin upstream clients: call `create<X>Client` from your own code (`/next/upstream-clients`) |
|
|
48
|
+
| `@decocms/blocks/sdk/cacheHeaders`, `/responseCache`, `/cacheStorage`, `/mergeCacheControl` | on TanStack, the page cache in the site's worker entry (the example worker entry you copy: `PROFILES` are v7's); a Next.js site keeps its own |
|
|
49
|
+
| `@decocms/blocks/sdk/csp`, `/sdk/redirects` | `createDecoWorker`'s `csp` option; the worker applies CMS redirects |
|
|
50
|
+
| `createDecoWorkerEntry` (`@decocms/tanstack`) | `createDecoWorker({ serverEntry, cms, pageCache })` from `@decocms/tanstack/worker`, behind the site's own page cache: copy the example worker entry and carry v7's `buildSegment` and `csp` over by hand, as the report lists (`references/framework-code.md`) |
|
|
51
|
+
| `DecoRootLayout`, `PreviewProviders`, `DraftPreviewIndicator` (`@decocms/tanstack`) | `DecoDocument` from `@decocms/tanstack/react` |
|
|
52
|
+
| `cmsRouteConfig`, `loadCmsPage`, `DecoPageRenderer`, … (`@decocms/tanstack`) | `createCMS` and `matchRoute` (`/next/tanstack-start-descriptors`), the draft from `contentClient(cms)` (`@decocms/tanstack/server`) |
|
|
53
|
+
| `decoInvokeRouteConfig`, `decoMetaRouteConfig`, `decoRenderRouteConfig` | delete: the worker answers 404 on v7's admin paths |
|
|
54
|
+
| `setupTanstackFastDeploy`, `kvLoader` | `createCMS({ site, token })` (`references/hosted-releases.md`) |
|
|
55
|
+
| `@decocms/tanstack/vite` (`decoVitePlugin`) | `decoTanstack({ buildHash })` from `@decocms/tanstack/vite` |
|
|
56
|
+
| `@decocms/tanstack/sdk/startEntry`, `/sdk/cdnSegment`, `/sdk/cookiePassthrough` | `decoServerFnFetch` in `createStart`; `buildSegment` in the worker entry's page cache; the worker's Set-Cookie handling |
|
|
57
|
+
| `createDecoPage`, `DecoPageRenderer`, `DecoRootLayout`, … (`@decocms/nextjs`) | `createCMS` (`/next/nextjs`); `bindDraft` and `contentClient` from `@decocms/nextjs/server`; `StudioBridge` in the root layout |
|
|
58
|
+
| `DraftPreviewIndicator` (`@decocms/nextjs`) | the same name in v8, showing what `bindDraft` bound: call that first |
|
|
59
|
+
| `@decocms/nextjs/middleware` | `decideDraft` … `applyDraft` (or `draftProxy`) from `@decocms/nextjs/proxy` |
|
|
60
|
+
| `@decocms/nextjs/routeHandlers`, `DECO_REWRITES` | delete: no `/deco/*` handlers in v8 |
|
|
61
|
+
| `LiveControls` (`@decocms/blocks/hooks`) | `StudioBridge`: `DecoDocument` mounts it (`DecoPreview` in a site's own document); a Next.js layout renders it from `@decocms/nextjs`, and each page renders `StudioPage` |
|
|
62
|
+
| `DraftPreviewBadge` (`@decocms/blocks/preview`, `@decocms/nextjs`) | `DraftBadge` from `@decocms/blocks/preview` |
|
|
63
|
+
| `registerImageCdnDomain`, `registerImageQuality`, `getOptimizedMediaUrl`, `getSrcSet` | `createImageUrl({ providers: [vtexCatalog(), shopifyCdn(), decoCdn({ domain, quality, sources: "all", ...byRelease })] })` (`byRelease` by the site's 7.x release, or read from the site's own copy of the helper: `framework-code.md`): `createImageUrl`, `decoCdn` from `@decocms/blocks/image`, `vtexCatalog` from `@decocms/apps-vtex/image`, `shopifyCdn` from `@decocms/apps-shopify/image`; `url(src, opts)` and `srcSet(url, src, opts)`; on TanStack, `ImageUrlProvider` |
|
|
64
|
+
| `Image`, `Picture` on a Next.js site | next/image with `createDecoImageLoader` from `@decocms/nextjs/image-loader` |
|
|
65
|
+
| other v7 names under `@decocms/tanstack`, `@decocms/nextjs` | the v8 binding has no such name; see the rows above and `references/framework-code.md` |
|
|
66
|
+
| anything else under `@decocms/*` | no v8 equivalent (several have a site-code replacement: the next table) |
|
|
67
|
+
|
|
68
|
+
## What sites ended up writing themselves
|
|
69
|
+
|
|
70
|
+
From the storefront and blog migrations, the reported imports with no binding equivalent were replaced by site code like this:
|
|
71
|
+
|
|
72
|
+
| v7 import | Site code |
|
|
73
|
+
|---|---|
|
|
74
|
+
| `BreadcrumbJsonLd`, `PLPJsonLd`, `ProductJsonLd` (`@decocms/blocks/hooks`) | `src/vendor/blocks/JsonLd.tsx` |
|
|
75
|
+
| `ANALYTICS_SCRIPT` (`@decocms/blocks/sdk/analytics`) on a site with no analytics SDK | on TanStack, nothing: `DecoDocument` renders the `data-event` observer; elsewhere the same observer string in the site's root document, copied from the installed version (7.6x defers it until a Speculation Rules prerender activates) |
|
|
76
|
+
| `withABTesting` (`@decocms/blocks/sdk/abTesting`), or a vendored copy | on TanStack Start, `abTestingRoutes({ worker: () => worker, kvBinding, shouldBypassAB, preHandler })` from `@decocms/compat-v7/tanstack/worker`, run first in `createDecoWorker`'s `routes`; the script reports the import (a wrapper becomes a routes handler, so it isn't rewritten). If the KV holds no config for the site's hosts, nothing was split: delete it and the binding instead ([`site-code.md`](./site-code.md)) |
|
|
77
|
+
| `signal` (`@decocms/blocks/sdk/signal`) | delete it when nothing imports the site's re-export; otherwise a local signal |
|
|
78
|
+
| `withFetchTimeout`, `FetchFn` (`@decocms/blocks/sdk/fetchTimeout`, 7.6x) in vendored loaders | a local `fetch(url, { ...init, signal: AbortSignal.timeout(10_000) })` (v7's default), or the v8 client's own fetch |
|
|
79
|
+
| `getCookies`/`setCookie`, `RequestContext` | read the request and write response headers explicitly, or a site-owned `AsyncLocalStorage` (`src/request-state.server.ts`) |
|
|
80
|
+
| `useCart`/`useUser`/`useWishlist`, cart loaders (`@decocms/apps-<x>`) | `src/vendor/<platform>/…` copies, sending through the v8 client (`createShopifyClient`, …) |
|
|
81
|
+
| `Seo`, JSON-LD components | the site's head builder (`src/head.ts`) and `src/vendor/blocks` |
|
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
# Legacy type names
|
|
2
|
+
|
|
3
|
+
Saved content stores type names in `__resolveType`. Treat them like database columns: renaming one breaks the content that stores it.
|
|
4
|
+
|
|
5
|
+
## Resolved by the alias table (no change needed)
|
|
6
|
+
|
|
7
|
+
`LEGACY_ALIASES` in `@decocms/blocks/cli` maps these to built-ins. The site editor's screens look for them, so they keep working as saved:
|
|
8
|
+
|
|
9
|
+
| v7 name | Built-in |
|
|
10
|
+
|---|---|
|
|
11
|
+
| `website/pages/Page.tsx`, `$live/pages/LivePage.tsx` | `page` |
|
|
12
|
+
| `website/flags/multivariate.ts`, `website/flags/multivariate/section.ts` | `multivariate` (each plain variant `value` is wrapped in a `lazy` block on the way) |
|
|
13
|
+
| `website/matchers/always.ts` | `always` |
|
|
14
|
+
| `website/matchers/never.ts` | `never` |
|
|
15
|
+
| `website/loaders/redirect.ts` | `redirect` (resolves, but isn't routed: routing reads only the redirects block; the script folds it into `Redirects`) |
|
|
16
|
+
|
|
17
|
+
`website/loaders/redirects.ts` has no alias: v8 routes only a block typed `redirects`. The script folds every v7 redirect block, per-rule and list, and the CSV of every `website/loaders/redirectsFromCsv.ts` loader into one block named `Redirects` (`references/script-steps.md`, step 1), and `deco check` warns about one left over.
|
|
18
|
+
|
|
19
|
+
`website/loaders/secret.ts` has no built-in: secrets live in the deploy platform's secrets, and the script lists each one (`references/script-steps.md`, step 2).
|
|
20
|
+
|
|
21
|
+
## Rewritten in content by the script
|
|
22
|
+
|
|
23
|
+
`RENAMED_TYPES` in `scripts/legacyNames.ts`; same props, same behaviour, except `date`. This is the table in the docs' "Run the migration".
|
|
24
|
+
|
|
25
|
+
| v7 name | Saved as |
|
|
26
|
+
|---|---|
|
|
27
|
+
| `website/flags/multivariate/image.ts`, `website/flags/multivariate/message.ts`, `website/flags/multivariate/page.ts`, `$live/flags/multivariate.ts` | `website/flags/multivariate.ts` |
|
|
28
|
+
| `$live/matchers/MatchAlways.ts` | `website/matchers/always.ts` |
|
|
29
|
+
| `website/matchers/date.ts`, `$live/matchers/MatchDate.ts` | `date`, then reported: v8 has no `date` block and `deco check` rejects it. Move each window into the saved block `campaigns` ([`script-steps.md`](./script-steps.md), step 1) |
|
|
30
|
+
|
|
31
|
+
## Everything else
|
|
32
|
+
|
|
33
|
+
Site types (`site/sections/Product/Shelf.tsx`) and app types (`shopify/loaders/ProductList.ts`) stay as saved: the block map registers each function under its v7 names only. A block under a short name too would be listed twice in the site editor's pickers, so the script writes no short names (PO 2026-10-15); add one only when new content needs it.
|
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
# Manual steps (what the report leaves)
|
|
2
|
+
|
|
3
|
+
The full text behind `SKILL.md` ("Manual steps"). Work through the report top to bottom; these are the steps it groups its "Left to do" lines under.
|
|
4
|
+
|
|
5
|
+
1. **Dependencies.** Depend on `@decocms/blocks@^8.4`, the v8 binding at the same version (`@decocms/tanstack@^8.4` or `@decocms/nextjs@^8.4`; they take blocks as a peer, so one copy installs), `@decocms/compat-v7@^8.4` when the script pointed imports at it and the v8 `@decocms/apps-<platform>` client. Remove `@decocms/blocks-admin`, `@decocms/blocks-cli`, `@decocms/apps-commerce`, `@decocms/apps-website` and `@decocms/apps-blog` once nothing imports them, and drop the v7 codegen from `build`. On Next.js, check what the installed `@decocms/blocks` publishes: when its `exports` default to `dist/*.js` (`8.1.0` does), it needs no `transpilePackages` entry; a prerelease whose `exports` point at `src/*.ts` needs `@decocms/blocks` in `transpilePackages` (v7's `withDeco` wrapper used to add it), or a clean install fails `next build` with `Module parse failed: Unexpected token`.
|
|
6
|
+
2. **Check the page setup the script wrote, on the binding.** It follows the framework guide (`/next/tanstack-start-descriptors`, `/next/nextjs`): `src/cms.ts` (`createCMS` and the binding's `contentClient`), `src/open-page.server.ts` (`matchRoute`, every section resolved, then `loadSections` at the page's URL, and on TanStack `matchPage(url)` first), the page's server function (`src/page.functions.ts`: it takes the page's path, so a client-side navigation loads the page and not `/_serverFn/…`), and the catch-all route rendering `src/views.ts` (`src/routes/$.tsx`, or the Next.js `[[...slug]]/page.tsx`, with `bindDraft`). It replaced v7's page routes (`cmsRouteConfig`, `createDecoPage`), keeping their options, v7's head and v7's section wrapper: carry over what the site added to them (a not-found component, a head tag or loader of its own, a wrapper such as a `<main>` landmark around the sections) from git. The block map has no `page` of its own: the built-in page takes the views' descriptors as its sections, and in its `seo` field any block that returns only optional SEO fields (a `title` or a `description`, strings), such as one returning the block map's `PageSeo`; a loader whose result has required fields (a blog post, a category) stays out. A file that already existed was kept and reported. Still by hand: `pageUrlRequestHeaders` in the proxy (Next.js) when the report says so, the visitor and the decisions in the proxy (Next.js: `draftProxy`, or `decideVisitor`/`decideAssignments`/`visitorRequestHeaders`/`assignmentsRequestHeaders`/`applyVisitor`) when the content has `experiments` or `campaigns`, the A/B tests and date rules the report lists, moved into the saved blocks `experiments` and `campaigns` (`/next/matchers-and-variants#run-an-a-b-test`, `#schedule-a-campaign`), and the binding wired as its README shows: on TanStack, `createDecoWorker` as the worker entry, `DecoDocument` as the root, `createDecoRouter`, `decoServerFnFetch` and `decoTanstack()`; on Next.js, the draft proxy and route, `StudioBridge`, `withDeco` and the image loader (`references/framework-code.md`). The script deleted v7's admin routes; delete the v7 setup files too, and the v7 CI jobs: a `.github/workflows/regen-blocks.yml` (or any job that runs `generate:blocks` or calls the shared `regen-blocks` workflow) regenerated `blocks.gen.json` on every content push to `main`. v8 has no such file and the script it calls is gone, so once merged every publish starts a job that fails or does nothing useful.
|
|
7
|
+
3. **Replace v7's framework code with the binding, and move the rest into the site** (`references/framework-code.md`): the worker, drafts, the Studio bridge, the badge and the image components come from the binding, a platform's image URLs from its client's `/image` (`@decocms/apps-vtex/image`, `@decocms/apps-shopify/image`); SEO/head, device detection, cookies, cart/user/wishlist flows, commerce loaders and converters are site code ([`site-code.md`](./site-code.md)). On TanStack Start, copy the example worker entry the report names (the site's own page cache and purge) and carry over what the report lists from v7's `createDecoWorkerEntry`.
|
|
8
|
+
4. **Finish `/deco/invoke`.** The script wrote one server function per key the site invoked (`src/server/invoke.functions.ts` with TanStack `createServerFn`, loaders as private GETs; `src/server/invoke.actions.ts` with Next.js `"use server"`), each calling its handler with `(props, request)` as v7's endpoint did, and pointed every call site at its own: `invoke.site.loaders.spin(props)` → `$siteLoadersSpin({ data: props })`. Give each a zod validator and a typed result (they're `any`, as v7's invoke was), and set the cookies a handler needs with the framework's API. What it couldn't port is a `@deprecated` stub in `src/migration-stubs.ts`: `unportedInvoke` (`ctx.invoke` in a loader, a key no file answers), `appState` (an app's state off `ctx`); both reject, as reading `ctx` does in v8. `useSection` keeps v7 7.x's placeholder URL, so `hx-*` attributes render as before and still do nothing. Replace each stub, then delete the file. Don't rebuild the `invoke.x.y` tree or a string-keyed dispatcher (see DO NOT in `SKILL.md`). Details in `references/server-functions.md`.
|
|
9
|
+
5. **Fix the content `deco check` rejects**: fields no type declares, `.tsx`-named preview blocks, v7 app blocks (the script wrote each one's client config to `src/clients/<app>.ts`: set the credentials it names, then delete the block), `requestToParam` blocks in string fields.
|
|
10
|
+
6. **Telemetry, analytics and previews**: the `telemetry` option of `createCMS` (`/next/telemetry`), with switches and rates in the `telemetry` section of `CMS.json`; `AnalyticsScript` with `const { analytics } = await cms.settings()` and `track` from `@decocms/blocks/analytics`; drafts through the binding (the TanStack worker, or `decideDraft`/`bindDraft` on Next.js), on the hosts the CMS allows: the addresses Studio writes into each release's metadata (read with `createCMS({ site })`), so the site declares none and v7's `previewHosts` and `DECO_ALLOWED_PREVIEW_HOSTS` go away. Until the site's first publish from Studio writes that list (no `latest.json` yet, or one without `previewHosts`), and for content with no `site`, previews work on every host; `createCMS({ preview: { hosts: ["localhost"] } })` narrows local content without a `site` to the dev host. The report carries GTM/GA4 IDs over. If v7 sent no CMS telemetry, pointing `telemetry` at the site's existing collector is new traffic and cost there: list it as a behaviour change.
|
|
@@ -0,0 +1,43 @@
|
|
|
1
|
+
# Apps that render content natively
|
|
2
|
+
|
|
3
|
+
Some v7 projects aren't websites. They're native or mobile apps (a v7 binding such as `@decocms/eitri`) that bundle `.deco/blocks/*.json` at build time and render sections through their own component table. For these apps, the v7 package only generated Studio's files (`.deco/meta.gen.json`, `.deco/blocks.gen.json`). No runtime file imports a `@decocms/*` package.
|
|
4
|
+
|
|
5
|
+
v8 has no binding for them, and needs none. The app keeps reading its JSON. Only the editor tooling moves to `@decocms/blocks` v8. Keep app-specific code in the app; don't add it to a package.
|
|
6
|
+
|
|
7
|
+
## What changes
|
|
8
|
+
|
|
9
|
+
1. **Run the script as usual** and commit its output unedited. It writes `.deco/index.ts` with descriptor-returning section blocks, which `deco schema` and `deco check` need. Manual steps 2 to 4 (`createCMS`, framework code, `/deco/invoke`) don't apply.
|
|
10
|
+
2. **Dependencies.**
|
|
11
|
+
- Remove the v7 binding package.
|
|
12
|
+
- Add `@decocms/blocks@^8.4` and `typescript`, which `deco schema` needs as a peer.
|
|
13
|
+
- Check the Node version that `@decocms/blocks`'s `engines` requires against the app's toolchain.
|
|
14
|
+
3. **Scripts.**
|
|
15
|
+
- These apps usually have no `dev`/`build` npm scripts. Run `deco schema && deco check` in whatever runs before the app's own start (`prestart`, a CI step).
|
|
16
|
+
- Keep the old v7 script names as aliases when other tooling, such as a content importer, calls them.
|
|
17
|
+
4. **Generated files.**
|
|
18
|
+
- Commit `.deco/schema.gen.json`, which Studio reads for the editor forms, and delete `meta.gen.json`, `blocks.gen.json` and `generate.digests.json`.
|
|
19
|
+
- Skip `deco content` when the app imports the JSON directly, and gitignore `.deco/blocks.gen.ts`.
|
|
20
|
+
5. **The block map isn't auto-discovered.** v7 listed every file under `sections/` as a section. In v8, a section that isn't in `.deco/index.ts` has no editor form. Say so in the app's AGENTS.md or contributor docs: a new section goes in the block map **and** in the app's component table.
|
|
21
|
+
- Remove files that only hold shared types (`types.ts`) from the block map. They were never sections.
|
|
22
|
+
6. **Studio.**
|
|
23
|
+
- `deco serve` is gone: content is edited in Studio's hosted CMS, or locally with `deco pull` and `deco push --draft=<name>` (`/next/cli`).
|
|
24
|
+
- Expect an empty preview pane: there's no web renderer.
|
|
25
|
+
- `deco pull` writes each block as formatted JSON, so compact inline objects become multi-line.
|
|
26
|
+
|
|
27
|
+
## Parity
|
|
28
|
+
|
|
29
|
+
There's no SSR HTML to compare. A static harness covers what changes (Tier 0, no device or network needed):
|
|
30
|
+
|
|
31
|
+
| Check | What it compares |
|
|
32
|
+
|---|---|
|
|
33
|
+
| bundle | sha256 of every file the app's bundler packs, per module, minus the Deco tooling files. Any change fails. |
|
|
34
|
+
| content | canonical-JSON hash of each `.deco/blocks/*.json`. |
|
|
35
|
+
| forms | each section's editor form, from v7 `meta.gen.json` vs v8 `schema.gen.json`, reduced to form keywords (`type`, `title`, `format`, `enum`, `required`, `items`, `properties`, `anyOf`/`oneOf`/`allOf`, `default`, `description`, min/max, `additionalProperties`). |
|
|
36
|
+
|
|
37
|
+
Record the baseline on the last v7 commit, before the script runs. Add device screenshots (Tier 1) once a device or emulator build is available. Until then, rendering parity rests on the bundle check showing the packed files didn't change: say that in the PR.
|
|
38
|
+
|
|
39
|
+
Most form differences are expected. Sort them with [`editor-forms.md`](./editor-forms.md) before you approve or fix anything.
|
|
40
|
+
|
|
41
|
+
## Before merging
|
|
42
|
+
|
|
43
|
+
`prestart` regenerates `schema.gen.json` from the **installed** `@decocms/blocks`. Pin a range that includes every CLI fix the committed schema depends on. Otherwise the next start brings the old form differences back. The CLI fixes in [`editor-forms.md`](./editor-forms.md) (cause 3) shipped after `8.1.0-next.1`.
|
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
# Next.js App Router
|
|
2
|
+
|
|
3
|
+
From the site migrations; the sites and what the commit hashes refer to are listed in `SKILL.md` ("Gotchas by subject").
|
|
4
|
+
|
|
5
|
+
- **`transpilePackages: ['@decocms/blocks']`** only while the installed package's `exports` point at `.ts` source (see `manual-steps.md`, step 1); `8.1.0` ships `dist/` and needs none. A linked local checkout ships `dist/` and hides the difference; so does every parity run made against it.
|
|
6
|
+
- **Drafts on Pages Router SSG pages** (no proxy available, as on FastStore; `@decocms/nextjs` is for the App Router): Next 16's compiled pages runtimes inline `tryGetPreviewData`, so a `require.cache` patch never runs. See `faststore.md`.
|
|
7
|
+
- **Drafts come from `@decocms/nextjs`.** Don't hand-write the draft proxy, the draft route or the Studio bridge. In `proxy.ts`: 404 direct hits on the internal route (`isDraftRoutePath`), `decideDraft(proxyCms, request)`, then `decideVisitor(request, draft)` and `decideAssignments(proxyCms, draft, visitor)`, then `rewriteToDraftRoute(request, draft, visitor, assignments)` or `NextResponse.next({ request: { headers: assignmentsRequestHeaders(visitorRequestHeaders(draftRequestHeaders(request, draft), visitor), assignments) } })`, and `applyVisitor(applyDraft(response, draft), visitor)` for the cookies and the preview headers (`max-age=0, no-cache, must-revalidate`, noindex) (`@decocms/nextjs/proxy`). The visitor (the `deco_segment` cookie, v7's format plus an id) is what the saved `experiments` block decides A/B tests for; the proxy decides each test and campaign once (`decideAssignments`, forwarded with `assignmentsRequestHeaders`), `bindDraft` binds what it decided and `contentClient` builds `cms.client({ version, experiments, campaigns })` (`draftProxy` does all of it). On the dynamic `src/app/%5Fdraft/[[...path]]` route and in a layout that reads content: `bindDraft(cms, { searchParams })` and `contentClient(cms)` (`@decocms/nextjs/server`), with `<DraftPreviewIndicator />` on the page. A cached page can't read a request, which is why drafted requests go to that dynamic route; published CMS pages are ISR with `export const revalidate = 600` (Next renders a stored page again in the background on the first request after it is 10 minutes old, so a cached page is about that stale, which is accepted), never `force-static`, on the assignments route where the proxy decides the tests and campaigns and the page renders that (`await assignedClient(cms, segment)`). The package's README has the files in full.
|
|
8
|
+
- **Same CMS options in the proxy and the pages.** Keep `createCMS`'s options in one module both handles import (`cmsConfig`, with `site`): the proxy decides on the hosts Studio writes into the release metadata, and `bindDraft` checks again against the same ones.
|
|
9
|
+
- **Keep the block map out of the proxy.** The proxy only touches the CMS for a request with `?__draft=` or the draft cookie, but it is bundled whole. Give it its own `createCMS` handle with `blocks: {}` and the same options as the app's (one shared options module, since a second call with other options keeps the first): the draft check reads only the `CMS` settings block, so the block map, its section loaders and what they import (a GraphQL engine) leave the proxy bundle. Measured on one store: 2.2 MB to 1.5 MB, traced files 3,245 to 364. The content module still lands there.
|
|
10
|
+
- **`next start -H 127.0.0.1`** makes Next treat the draft rewrite as an external URL, and the request comes back through the proxy. Bind the default host in local checks; production hostnames aren't affected.
|
|
11
|
+
- **`Vary: Cookie`** doesn't arrive on a draft page: Next sets `Vary` itself. `Cache-Control: max-age=0, no-cache, must-revalidate` and noindex do.
|
|
12
|
+
- **next.config**: `withDeco(config)` from `@decocms/nextjs/config` (plain CommonJS) puts v7's draft header rules first and adds Studio's origins to `allowedDevOrigins`. Delete hand-written copies of those rules.
|
|
13
|
+
- **Images**: `createDecoImageLoader(imageUrl, { fallback: nextImageOptimizer })` from `@decocms/nextjs/image-loader` as `images.loaderFile`, over `createImageUrl` from `@decocms/blocks/image` with the platform's helpers first (`@decocms/apps-vtex/image`; see `framework-code.md`). A Server Component can't pass the URL function to a client component, so use the loader file, not a wrapper component.
|
|
14
|
+
- **A pointer that doesn't parse.** `cms.draftPointer` ignores a `?__draft=`/cookie value that doesn't parse (it returns `null`, so `?__draft=junk` gets the release). On a `@decocms/blocks` release without that fix it returned the raw value and `cms.forDraft` failed with `LOADER_FAILED`, so `?__draft=junk` on a preview host answered 500: there, treat `parseDraftPointer(pointer) === null` as no draft, in the proxy and the page.
|
|
15
|
+
- **Views wrapped in `next/dynamic`.** The script types each section from its view (`PropsOf<view>`). A lazy view that re-exports a `next/dynamic` wrapper loses its props type, and its form collapses. Type those sections from the component module (`section<import("…").Props>(…)`) and diff the forms against v7's.
|
|
16
|
+
- **`list('page')` order.** It sorts by block name; v7 listed saved pages in file order. Output that lists pages in order (a sitemap) has to keep v7's order explicitly.
|
|
17
|
+
- **List pages once per revision.** `list('page')` expands every page's saved-block references; on a site with hundreds of pages that is tens of milliseconds of CPU. Keep the routable list per revision (a revision never changes, a draft has its own) and hand the same array to `matchRoute` so it reuses its lookup. Health and readiness probes go through the same cache, never a fresh `list`.
|
|
18
|
+
- **Head meta order.** If v7 emitted `theme-color`/`color-scheme` after the root layout's metas on some routes, that was a race with Next's viewport resolution. To keep the order deterministic, render those tags from the segment layout (React hoists in tree order) rather than approving a reorder. The race can go the other way: where v7 had the viewport tags *before* the root layout's metas and v8's faster shell now wins, a segment layout can't move them earlier. Look for a deterministic fix (the tags rendered ahead of the root layout's metas on every route, checked against every route's head), and keep the reorder pending, with that reasoning, if none holds.
|
|
19
|
+
- **Jest** is CJS-only: transform `@decocms/blocks` (ESM) with ts-jest and keep it out of `transformIgnorePatterns`. When mocking a site module in a test, spread `jest.requireActual` so sibling exports other code imports stay real.
|
|
@@ -0,0 +1,66 @@
|
|
|
1
|
+
# Parity: approved v7 → v8 differences
|
|
2
|
+
|
|
3
|
+
Compare the migrated site with the v7 one with a parity harness (SSR HTML, hydrated DOM, JSON-LD, analytics calls, cache headers, third-party requests, pixels). Any difference fails unless the product owner approved it. Sort editor-form differences with [`editor-forms.md`](./editor-forms.md) first.
|
|
4
|
+
|
|
5
|
+
## How to encode an approval
|
|
6
|
+
|
|
7
|
+
Add it to an `approvedDifferences` list (e.g. in `parity/pages.json`), applied at compare time to both snapshots. Each rule names **one snapshot field**, **the cases it covers**, and **exactly what the new value must be**, so any other change to that field still fails. List the rules applied per case in the summary. Never ignore a field wholesale.
|
|
8
|
+
|
|
9
|
+
### Pending approval
|
|
10
|
+
|
|
11
|
+
A difference you've explained but the product owner hasn't approved yet still needs a state. Otherwise it's either a failing diff or an approval nobody signed. List it like an approval, with its reason, plus `"status": "pending"`:
|
|
12
|
+
|
|
13
|
+
- the default compare matches the entry and prints the case as `PENDING` on every run. Report three counts, ok, PENDING and DIFF; never fold PENDING cases into "N/M identical" in the summary, the README or the PR;
|
|
14
|
+
- `compare --strict` fails until each one is approved, which means deleting its `status` field. Run it in CI or before merging.
|
|
15
|
+
|
|
16
|
+
Never hide a pending entry: the compare summary and the PR list every one.
|
|
17
|
+
|
|
18
|
+
## Running it
|
|
19
|
+
|
|
20
|
+
- **Record what v7 actually does, even when it is broken.** A v7 page that is already wrong (one storefront's product listing showed "12 of 0 results" on every category and search page, live too, because its listing loader never got the page URL) is still the baseline. Record it as it is, mark the flows it makes impossible (filter, show more, listing to product) as blocked in the manifest with the reason, and compare them only once both sides can run. The v8 page that works is a product change: list it as pending with screenshots of both.
|
|
21
|
+
- **v7's catch-all answers 200.** A `/*` page (a category catch-all) renders for every unknown path, `/products/<unknown>` and `/sitemap.xml` included, with status 200 and no sitemap. Pin that in cases (status, body type) instead of assuming real 404s or a sitemap; turning them into 404s is a product change to list, not a parity fix.
|
|
22
|
+
- **No analytics SDK?** Record the site's own event bus (`window.DECO.events.dispatch`) from an init script instead of a third-party stub, so `view_item_list`, `select_item`, `add_to_cart` and `search` are compared.
|
|
23
|
+
- **Settle before clicking a card scrolled into view.** An IntersectionObserver `view` event can race a click that navigates: scroll the element into view, settle, then click, or the event lands on either page from run to run.
|
|
24
|
+
- **`parity:build` on v7 regenerates the v7 codegen** (`.deco/sections.gen.ts` and friends) with a different order: revert those files before committing the harness.
|
|
25
|
+
|
|
26
|
+
- **Build against what ships.** Do the final compare on a build from the committed lockfile, not a linked local checkout: a published package can differ (source vs compiled output, older CLI).
|
|
27
|
+
- **ISR and prerendered routes.** Pages prerendered at build time with `revalidate` were stale when the baseline recorded them. Compare a build older than the longest `revalidate`, or those cases differ only in `x-nextjs-cache`/`x-nextjs-prerender`.
|
|
28
|
+
- **Flakes.** Rerun a single failing case (`--only <case>`) before treating it as a regression, and avoid running two harnesses on one machine at once: font rasterization under load produced one-off weight diffs. Record each full run's flake count and which cases flipped; a count that grows between runs is a determinism regression to document or fix, not noise. A case that fails again on rerun isn't a flake: look up its differing pixels in every earlier run, v7 self-compares included, with each run's value. If v7 against its own baseline flipped the same pixel, write that evidence and the rate on each side into a pending pixel rule (a rectangle that covers only those pixels), not a mask; if only v8 flips it, fix it or list it as pending. Never report N/N on a run where it failed.
|
|
29
|
+
- **A `harMisses` flake from the screenshot itself.** Chromium's full-page capture can re-run `<picture>` source selection against a transient narrow frame, so a desktop capture sometimes requests (and the harness aborts) the mobile `<source>` images, on v7 and v8 alike. Key `harMisses` by the full URL: an image proxy (`decoims.com/image?src=…`) names the image in the query, so origin + path lumps every image of the page into one entry and a drop list hides them all. Drop only the named URLs, on both sides, for those cases, and give the list a `status: "pending"` that the summary prints and `--strict` fails on whenever it changed a result: it is a suppression the product owner sees, not harness housekeeping.
|
|
30
|
+
- **Re-run the v7 self-compares after every harness change.** Two v7-vs-v7 runs at 0 diffs prove the harness as it was then; a later change to compare, capture or the manifest needs two new ones (`--strict --strict-upstream`, pending rules off) before a v8 number means anything. After a snapshot format change, re-capture the baseline from its fixtures (pass 2 of `record`, no live traffic) on the v7 build and check it equals the old one apart from that field.
|
|
31
|
+
- **Wait loops that find themselves.** A `pgrep -f '<pattern>'` (or `pkill -f`) "is a heavy job running" check matches the shell running the loop, since the pattern is in its command line: the loop never ends, holds up every agent that runs the same check, and `pkill` kills your own shell. Wait on a PID (`while kill -0 <pid>`) or bracket a character (`pgrep -f '[r]un.mjs'`).
|
|
32
|
+
- **Pin the Workers `request.cf` object.** A local Workers runtime (Miniflare/wrangler) fills `request.cf` from a cache file fetched for the machine's network location (`node_modules/.mf/cf.json`), once per checkout. Two checkouts fetched at different times can disagree (region, city, colo), and anything keyed on the region (a cache segment, regional prices) differs. Copy one checkout's file into the other before recording, and record and compare on the same ports: URLs built from the origin can carry the port.
|
|
33
|
+
- **A bad baseline is re-recorded, never masked.** If the v7 baseline itself captured a rendering flake (an icon laid out but not painted), re-record that case from the v7 site (`record --only <case>`) instead of adding a pixel-ignore rect. The re-record also refreshes that case's upstream fixtures live, so its page can change (prices, stock, page height); run a full compare afterwards.
|
|
34
|
+
- **Fix in code what code can fix, then prove it on every page type.** Before asking for approval, try removing a pending difference in site code; then run the full compare, not just the cases the rule named. A popup gated on the footer's position fixed the home page cases and broke the product page ones (`rendering.md`), so that rule stayed pending.
|
|
35
|
+
- **A fixed upstream request gets a pending baseline.** When v8 fixes a v7 bug in what it asks upstream (a listing loader that now gets the page URL), its requests were never recorded and miss in replay. Don't re-record the v7 baseline to hide it, and don't leave them as nondeterministic diffs called "now working" (in one run the section was missing entirely). Record what v7's fixtures lack once from live upstream, at the fixed time, into a store and HAR used only for those cases and only on a miss in v7's; capture v8 from them in replay; compare those cases against that pinned capture, reported PENDING (never ok), with the v7-vs-v8 diffs beside it. A later regression there still fails.
|
|
36
|
+
- **A replay miss must not drop a section.** A section whose loader throws on an upstream error vanished from the page (header straight to the footer), which is also what a real upstream outage would do in production. Make the loader return the empty state v7 showed (breadcrumb, filters, "0 results"), log the error, and check that path once with a deliberate miss.
|
|
37
|
+
- **Check claims about v7 against the baseline.** "v7 sent `X-Frame-Options`" came from a v7 code comment; the recorded headers had neither it nor `frame-ancestors`. Keep parity and list the hardening (`frame-ancestors` with the Studio origins) as a product-owner decision.
|
|
38
|
+
- **A harness without pending support.** If the copied harness only knows approvals, add the `status: "pending"` state (and `--strict`) before encoding anything, so no explained difference is ever written as an approval.
|
|
39
|
+
- **Reduced motion hides dead sections.** Capturing with `reducedMotion: reduce` shows content a scroll-reveal animation would keep invisible, so a section that never hydrates still matches. Load the main page types once without it, in a plain browser, and compare against the live v7 site.
|
|
40
|
+
- **Not covered by pixels.** Name what the cases don't exercise (draft rendering through the pointer, coupons, region pricing, signed-in shoppers, device-only variants on per-request pages, hosted releases) in the PR so it gets a manual check. A replaying harness also can't see latency: a page that now waits on an upstream call before hydrating, or a draft check that no longer lets the edge cache serve, passes every compare. Review those code paths by hand.
|
|
41
|
+
|
|
42
|
+
## Approved so far
|
|
43
|
+
|
|
44
|
+
**Approvals are per site.** The lists below are what each site's product owner signed. When a harness is copied from another site, copy its mechanics and leave `approvedDifferences` and `ignoreHeaders` empty: the same difference becomes `pending` on the new site until its own product owner approves it. Say so in the harness README.
|
|
45
|
+
|
|
46
|
+
storefront-tanstack (`5a5a4d4`):
|
|
47
|
+
|
|
48
|
+
- **JSON-LD in the first SSR HTML** for Lazy-wrapped sections (`ssr.jsonLd`): equal to the hydrated DOM's. v8 has no async rendering: the script unwraps Lazy wrappers to their sections, which render on the server.
|
|
49
|
+
- **Extra product image requests** (`thirdPartyRequests`/`harMisses`) on flows that render more images server-side.
|
|
50
|
+
- **PLP "show more" page-2 `view_item_list` item indexes.**
|
|
51
|
+
- **Fixed cache headers** where v7 sent the wrong ones (the v7 QueryClient bug on `home@mobile`).
|
|
52
|
+
- Approved response headers ignored on both sides (`x-powered-by`; `b37a24b`).
|
|
53
|
+
|
|
54
|
+
blog-tanstack (`9e97455`):
|
|
55
|
+
|
|
56
|
+
- **Collector beacons recorded as analytics**: `AnalyticsScript` sends One Dollar Stats beacons straight to the collector instead of loading the SDK; decode them into the same view/event records, and compare `location.pathname` without the query string.
|
|
57
|
+
- **Real 404s** for unknown slugs and `/404` (v7 answered 200).
|
|
58
|
+
|
|
59
|
+
A native app with a v7 binding (bundled JSON, native rendering; `references/native-apps.md`), pending product-owner approval:
|
|
60
|
+
|
|
61
|
+
- **Bundle and content unchanged.** No packed file and no saved block differs.
|
|
62
|
+
- **Editor forms.** The differences fall under the three causes in [`editor-forms.md`](./editor-forms.md):
|
|
63
|
+
- stale v7 `meta.gen.json`: a shared action type's new field across 15 sections, plus one removed CTA field;
|
|
64
|
+
- list fields without "Select from saved";
|
|
65
|
+
- two black/white text-color fields without the color picker: not approved (the product owner keeps the picker); annotate their alias `@format color`;
|
|
66
|
+
- `types.ts` no longer listed as a section.
|
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
# Rendering
|
|
2
|
+
|
|
3
|
+
From the site migrations; the sites and what the commit hashes refer to are listed in `SKILL.md` ("Gotchas by subject").
|
|
4
|
+
|
|
5
|
+
- **v8 has no async rendering; the script removes it.** v7's `website/sections/Rendering/Lazy.tsx` and `SingleDeferred.tsx` (`{ section }`) and `Deferred.tsx` (`{ sections: [...] }`) are unwrapped in the saved content: each wrapper becomes the section(s) it held, with their props, and its own options (`loading`, `display`, `behavior`) go. Don't register a block under those names. Content that used to arrive after hydration (JSON-LD in particular) is now in the first SSR HTML. That is an approved parity difference, not a bug (`5a5a4d4`). A wrapper the script reports (several sections where one block goes) is unwrapped by hand.
|
|
6
|
+
- **Blocks that render nothing** (theme fonts, SEO sections' `jsonLD`): wrap their data arguments in `lazy` in content so nothing is fetched for them (`9a097a1`).
|
|
7
|
+
- **Check that streamed sections hydrate.** On TanStack Start 1.166 with the block promises returned through the page server function and wrapped in `defer`, a block still pending when the document streams arrives as a late resolution script, and the browser's copy of its promise never settled: the section showed its server markup but never hydrated (no effects, no handlers). It hid behind reduced motion in a parity run (a scroll-reveal grid looked right) and behind plain links (filters still navigated). After the port, load a page whose blocks fetch upstream and check in the browser that every block promise in the route's loader data is fulfilled and that a section's DOM node has React's `__reactFiber` key; if not, await every block on the server too (one storefront did, and its hydrated pages then matched v7's live behaviour).
|
|
8
|
+
- **Awaited blocks are an exception.** The TanStack guide keeps block promises unawaited. A site whose blocks only read in-memory content may await them so every section lands in the first HTML chunk and the hero preload stays in `<head>`; stop awaiting a block once it fetches upstream (blog `dee30a5`).
|
|
9
|
+
- **Awaited because of response headers.** A page whose response headers depend on how its blocks resolved (a degraded-page header when a loader failed) has to await every block before answering, so time to first byte is the slowest block's, as in v7. That departs from the guide: say so in `open-page.server.ts`'s header and in the PR, and list streaming as a follow-up.
|
|
10
|
+
- **Side effects of deferred sections now start on load.** v7 rendered a deferred section once its placeholder came within 300px of the viewport, one frame after mount, so a popup, banner, timer or view event inside it started then; now it starts on page load. Gating it on the section's position in v8's layout does *not* reproduce v7: v7's pages were short while their other deferred sections were still placeholders, so a footer near the fold of a short v7 layout (a product page) mounted on load, and the gate then hides a popup v7 showed. Compare a page whose v7 layout was short as well as a long one before keeping such a gate; otherwise keep the difference as pending and explain it.
|
|
11
|
+
- **Section keys and wrappers.** Keep v7's `<section id data-manifest-key>` wrapper and section keys so CSS and client state survive navigations (`5bcc12b`, `0512e60`).
|
|
12
|
+
- **Tailwind reads every text file it scans, comments and Markdown included.** A word that is a utility name (`isolate`, `hidden`, `fixed`) in a new comment or an `AGENTS.md` line generates that class and changes the stylesheet's hash, which shows up as a different `Link` preload header on every page. It works the other way too: deleting a README section that said "this stack" dropped DaisyUI's `.stack` rules. Diff the built CSS against v7's after editing or deleting docs, comments or dead files, and list a lost class inline (`@source inline("… stack")`).
|
|
13
|
+
- **Tailwind.** Code moved out of the v7 packages changes Tailwind's scan; list the classes v7 generated from deleted files inline so the stylesheet stays byte-identical. If you exclude the vendored folder from the scan (`@source not "../vendor"`, because v7 never scanned `node_modules`), a class written only there is never generated: say so in the site's agent/contributor notes.
|
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
# Running the script: before, and dependencies after
|
|
2
|
+
|
|
3
|
+
From the site migrations; the sites and what the commit hashes refer to are listed in `SKILL.md` ("Gotchas by subject").
|
|
4
|
+
|
|
5
|
+
## Before you run the script
|
|
6
|
+
|
|
7
|
+
- **Install `@decocms/blocks@^8.4` first** (`^8` resolves to the accidental v7 build published as `8.0.0`). A v7 site already has `@decocms/blocks@7`, which has no `/cli` or `/protocol/keys`; the script fails to import. Keep v7 `@decocms/apps-*` installed until after the run: vendoring copies from them.
|
|
8
|
+
- **Commit the script's output unedited** (`046de4d`, `de03793`), then do the manual work in follow-up commits.
|
|
9
|
+
- **The script vendors every app loader the content calls**, including ones the v7 site never ran (a v7 Next.js site resolved many VTEX loader blocks to `null`). Check which ones actually rendered before keeping a vendored copy; delete the rest along with the saved blocks nothing references.
|
|
10
|
+
|
|
11
|
+
- **A generated `invoke.gen.ts` for another platform** (VTEX checkout and session actions on a Shopify store) that nothing imports: delete it and drop that `@decocms/apps-*` dependency; don't port its actions. Check with `grep` that no call site uses it first.
|
|
12
|
+
- **Don't reformat vendored request documents.** Running Prettier over `src/` reflows the GraphQL documents in a vendored `queries.ts`, which changes every request body sent upstream: a replaying parity harness then misses every call. Keep such files out of the formatter (`.prettierignore`).
|
|
13
|
+
- **Two lockfiles.** A stale `package-lock.json` next to the `bun.lock` the site really installs from (different `@decocms/*` versions) is a trap for CI and deploy tooling that picks the npm lock: delete the stale one in the dependency commit and say so.
|
|
14
|
+
|
|
15
|
+
## From an installed copy of the skill
|
|
16
|
+
|
|
17
|
+
The script resolves `@decocms/blocks` relative to its own files. From outside a `decocms/blocks` checkout, copy `scripts/` into the site so it resolves the site's `@decocms/blocks@8`, run it, then delete the copy:
|
|
18
|
+
|
|
19
|
+
```bash
|
|
20
|
+
cd <site> && bun add @decocms/blocks@^8.4
|
|
21
|
+
cp -R <skill>/scripts .deco-migrate
|
|
22
|
+
bun .deco-migrate/main.ts --root .
|
|
23
|
+
rm -rf .deco-migrate
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
## Dependencies
|
|
27
|
+
|
|
28
|
+
- `bun.lock`: don't commit a lock produced by `bun link`; regenerate once the v8 packages resolve from npm.
|
|
29
|
+
- A linked checkout writes `"version": "0.0.0"` into `.deco/schema.gen.json`; the published CLI writes its own version. Commit what a clean `install --frozen-lockfile && build` writes.
|
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
# What the script does
|
|
2
|
+
|
|
3
|
+
The full list behind `SKILL.md` ("Run"). What it does, in order (`scripts/migrate.ts`):
|
|
4
|
+
|
|
5
|
+
1. **content**: saved blocks into `.deco/blocks`, v7 generated files removed, v7 async-rendering wrappers (`website/sections/Rendering/Lazy.tsx`, `SingleDeferred.tsx`, `Deferred.tsx`) unwrapped to the sections they held (v8 has no async rendering), the seven legacy names outside the alias table rewritten (`references/legacy-names.md`); every v7 redirect block (per-rule `website/loaders/redirect.ts`, `{ redirect: { from, to, type } }`, and list `website/loaders/redirects.ts` or `deco-sites/std/loaders/x/redirects.ts`, `{ redirects: [{ from, to, type }] }`: the saved blocks v7 routed) and the CSV of every `website/loaders/redirectsFromCsv.ts` loader, saved or inline (read as 7.x read it: from `public/`, `static/x.csv`, `public/x.csv`, `/x.csv` and `x.csv` alike, `../x.csv` the site's `x.csv`; `from,to`, then `type` and `discardQueryParameters` by value in any column; `,` or `;`; `#` comments and a `from,to` header skipped; an untyped row permanent under `forcePermanentRedirects`) folded into one block named `Redirects` of type `redirects`, the only block v8 routes: v7's `type: "permanent"` (or `"301"`) becomes `permanent: true` (301) and `temporary` (or no type) `permanent: false` (v8's temporary 307: under 7.x's default `legacy` semantics a temporary rule answered 302, so it now answers 307), `discardQueryParameters` kept, an absolute `from` its path. Rules are deduped by `from` in 7.x's load order, the CSV rows first (file by file, in the order the loaders are found), then the v7 blocks in code-unit name order: for one exact `from` the last rule wins (a later row, a later block, so a saved block's rule over a CSV row), as 7.x's exact map kept it, and for a glob (`*`) the first, as 7.x scanned its patterns; an existing `Redirects` block of type `redirects` keeps its rules first and they always win; each rule that loses to one sending its route elsewhere is reported, and so is a rule or row with no `from`/`to`, a v7 redirect inline in another block (not folded: v7 routed only saved blocks) and a CSV loader whose file 7.x couldn't read (a URL, a path outside the site, a missing file: left as it is; a saved one's own `redirects`, which 7.x routed, named too). The v7 blocks and the folded CSV loaders are deleted (each CSV file is kept and reported: delete it once checked); a block named `Redirects` of another type stops the step and is reported. v7's random matchers and every date rule (v7's, or the prerelease `date`, which `deco check` now rejects) are left as they are and reported, one line each: move each test into the saved block `experiments` under its saved-block name (Run an A/B test, `/next/matchers-and-variants#run-an-a-b-test`) and each window into the saved block `campaigns` (type `calendar`, each `start` and `end` a date and time with the store's offset, such as `2026-11-27T00:00-03:00`: `deco check` rejects a date alone or a time without an offset), each rule becoming `{ "__resolveType": "campaign", "name": … }` (Schedule a campaign, `/next/matchers-and-variants#schedule-a-campaign`). The binding reads the visitor and decides the tests and campaigns once (`cms.client({ visitor, ...version })`), hands the page `cms.client({ version, experiments, campaigns })` and is the only writer of `deco_segment` (TanStack: the worker; Next.js: the proxy, reported; elsewhere `readVisitor`, reported);
|
|
6
|
+
**settings**: site settings folded into the `CMS` block (`.deco/blocks/CMS.json`, type `cms-settings`): a literal `collectorAddress` on `OneDollarStats` → `analytics.collector`, and an earlier prerelease's `Telemetry.json`/`Analytics.json` → their sections, field for field and variants included (the old files are deleted). It keeps what `CMS.json` already has, writes nothing when there's nothing to fold, and a second run changes nothing. The report lists the environment-only settings to move by hand (`DECO_OTEL_*` sampling, `DECO_ANALYTICS_ENABLED`/`ONEDOLLAR_ENABLED`/`ONEDOLLAR_COLLECTOR`);
|
|
7
|
+
**apps**: each v7 app block v7's autoconfig read by name (`deco-vtex`, `deco-shopify`, `deco-wake`, `deco-resend`) → `src/clients/<app>.ts`, a function creating the v8 client (`createVtexClient`, …) with the block's settings and v7's defaults (VTEX's sales channel `"1"`, Wake's checkout URL, the Storefront API version the installed Shopify app spoke), each encrypted credential read from the environment variable v7 fell back to (`VTEX_APP_KEY`, `SHOPIFY_STOREFRONT_TOKEN`, `WAKE_TOKEN`, `RESEND_API_KEY`; the Worker's `env` or `process.env`), never its value; what v7 kept beside the client (`publicUrl`, Resend's sender) is an exported constant. The block stays until the variables are set; the report says to delete it then. The HTMX and analytics app blocks are reported for deletion;
|
|
8
|
+
2. **secrets**: each v7 secret (`website/loaders/secret.ts`, a block of its own or inside another block) is listed, with the variable v7 read it from when it names one; nothing is decrypted or written. Content holds no secrets on v8: put each value in the deploy platform's secrets (on Workers, `wrangler secret put`), read it in the site's code where it creates the client that needs it, pass it as a param, then delete the block (`deco check` points out any left, `/next/renames-and-migrations#secrets`);
|
|
9
|
+
3. **block map**: the site's `registerSectionLoaders({ … })` (and `registerNonCriticalSections`) turned into exports of the same map; then `.deco/index.ts` with each block under its v7 names only (the names the content stores, and `site/sections/….tsx` for every section in `src/sections`), so the site editor lists each block once (PO 2026-10-15), after vendoring the app loaders and actions the content calls into `src/vendor`. A section's descriptor names it by its v7 type name (`site/sections/….tsx`), and `src/views.ts` maps each name to its module. On a TanStack Start or Next.js site, v7's matchers the content uses (`device`, `cookie`, `host`, `pathname`, `queryString`, `location`, `multi`) are registered from `@decocms/compat-v7/matchers` over the binding's `matcherContext()` (TanStack: `matchPage(href)` in the page's server function tells them the page); `random` never is (step 1 reports it, for `experiments`), and `environment` is reported. `loadSections(sections, request, pageUrl)` runs v7's section loaders with v7's rules (`@decocms/compat-v7/sections`; the nested walk of the site's 7.x release), and also every section's own `loader` v7 never ran because `registerSectionLoaders` didn't list it: an approved difference (PO 2026-10-15), each one reported by name to list in the PR (v7 rendered its saved props). The site's registered map wins where it lists a section;
|
|
10
|
+
4. **invoke**: each `/deco/invoke` key the site calls (`invoke.a.b(props)`, bracket and flat keys, `invoke(key, props)`, `Runtime.invoke`, from `@decocms/blocks/sdk/invoke` or a site module that fetches `/deco/invoke`) → one server function calling its handler with `(props, request)`, as v7's endpoint did: `src/server/invoke.functions.ts` (TanStack `createServerFn`; loaders GET with `markPrivate()`, actions POST) or `src/server/invoke.actions.ts` (Next.js `"use server"`), imported by each call site; v7's proxy module is deleted once unused. `site/<path>` resolves to `src/<path>`, an app key to its vendored module, and a key v7's VTEX app answered from its own invoke map (`vtex/actions/checkout/addItemsToCart`) to what `--vtex-invoke` says (no default: without it, a site that calls such keys stops before step 1 with the list): `keep` vendors v7's module and calls that export, `v8` writes `src/server/vtex-invoke.server.ts` over `@decocms/apps-vtex`'s client where it has the operation, else `unportedVtexInvoke` (`references/server-functions.md`). Then the stubs in `src/migration-stubs.ts` (all `@deprecated`): `unportedInvoke` for a key with no handler and for `ctx.invoke` in a v7 loader, `appState` for an app's state read off its `ctx`, and `useSection`/`usePartialSection` with v7 7.x's placeholder URL; `hx-*` attributes are reported (inert in v7 and v8);
|
|
11
|
+
5. **scaffold**: on TanStack Start or Next.js, the page setup from the docs' guides: `src/cms.ts`, `src/open-page.server.ts` (every section resolved, then `loadSections` and `matchPage` when the block map has them, `requestDevice` when the site calls `useDevice`), TanStack's `src/page.functions.ts` (the page's server function, taking the page's path, so a client-side navigation opens the page and not `/_serverFn/…`) and `src/page-view.tsx`, and the catch-all route (`src/routes/$.tsx` and v7's home route; Next.js `[[...slug]]/page.tsx` with `bindDraft`, which also binds the visitor the proxy forwarded). Each section renders in v7's wrapper (`<section id data-manifest-key>` around v7's error boundary, `src/section-error-boundary.tsx`). The page's SEO is v7's (`PageSeo` in the block map; on TanStack the saved `site` block's `seo` defaults and templates too), and the TanStack routes keep what v7's `cmsRouteConfig` gave them: the options the site passed (titles, ignored search params, pending times), every other search param reaching the loader, its cache times and its head (robots, Open Graph, Twitter Card, canonical, JSON-LD); Next.js gets v7's metadata (canonical, robots). The router's module-scope `QueryClient` moves into `getRouter`. It replaces v7's page routes (`cmsRouteConfig`, `createDecoPage`, …), deletes v7's admin routes, and keeps any other file that exists. On TanStack it writes no worker entry: the report asks you to copy the example worker entry ([`examples/tanstack-worker-smoke/src/worker-entry.ts`](https://github.com/decocms/blocks/blob/main/examples/tanstack-worker-smoke/src/worker-entry.ts)) over wrangler's `main` (else `src/worker-entry.ts`) and lists what v7's `createDecoWorkerEntry` set there (`buildSegment`, `csp`, `proxyHandler`, …), each with where it goes, to carry over by hand from git;
|
|
12
|
+
6. **imports**: `ctx.device` in v7 loaders read from the loader's request (other `ctx` reads reported), then the codemod over `src/` (`references/import-map.md`): v7's pure helpers and `@decocms/apps-commerce` move to `@decocms/compat-v7`, and on TanStack Start `src/imageUrl.ts` is written and given to `createDecoRouter`'s `Wrap`; v7 names the bindings keep move to `@decocms/tanstack` subpaths, the draft names and Studio's origins to the site's binding root (`@decocms/tanstack` or `@decocms/nextjs`, never `@decocms/blocks`), the rest are reported name by name. The image URLs it reports (`createImageUrl` with `decoCdn`'s options) follow the site's 7.x release, or, when the site kept its own copy of v7's image helper, that copy's rules and the site's register calls. `stripAssetHosts` is left at decoCdn's default, `"leading"`, even for a site whose v7 code stripped the asset hosts anywhere (7.x before 7.71.4, or such a copy): the PO approved the switch (2026-10-15), and the report's "image URLs" line counts and lists the content and code URLs whose image URL changes (a URL that merely contains an asset URL, `https://other.host/https://assets.decocache.com/…`);
|
|
13
|
+
7. **scripts**: `predev`/`prebuild` run `deco schema && deco content` (`&& deco check`), and `deco schema --check` goes into the site's CI right after the install step (the pull-request workflows when there are any; never v7's `regen-blocks`), run through the lockfile's runner (`bunx`, `pnpm exec`, `yarn`, `npx`) and the install's working directory. It fails a pull request whose `.deco/schema.gen.json` differs from what `deco schema` writes. A workflow it can't edit (none, or a multi-line install) is reported.
|
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
# `/deco/invoke` → server functions
|
|
2
|
+
|
|
3
|
+
From the site migrations; the sites and what the commit hashes refer to are listed in `SKILL.md` ("Gotchas by subject").
|
|
4
|
+
|
|
5
|
+
v8 has no invoke endpoint. Every call the browser made through `/deco/invoke` becomes a TanStack Start server function (`createServerFn`) or a Next server action, taking the request and response headers explicitly (`89895c3`). Validate inputs with zod; reject protocol-relative hrefs. Loaders that 404'd through invoke and fell back to placeholders now return real state: check those flows.
|
|
6
|
+
|
|
7
|
+
- **One server function per key, imported by the call site: the script writes them.** `src/server/invoke.functions.ts` (TanStack; a loader is a GET with `markPrivate()`, an action a POST) or `src/server/invoke.actions.ts` (Next.js, `"use server"`), named after the key (`site/loaders/gateway/wishlist/add-item` → `$siteLoadersGatewayWishlistAddItem`), each calling its handler module with the props (`{}` for none, as v7 sent) and the request. Each call becomes `invoke.a.b(props)` → `$aB({ data: props })` (Next.js: `$aB(props)`), across lines, bracket keys (`["can-spin"]`), flat keys (`invoke["vtex/loaders/x.ts"]`), `invoke(key, props)` and `Runtime.invoke` included; v7's proxy module (`src/runtime.ts`) is deleted once nothing imports it. An app's key vendors the app's module when it default-exports the handler. A computed key is reported and left. Then type each function (input and result are `any`, as v7's invoke was) and forward the cookies a handler sets. Never a `runInvoke(key)` lookup over the commerce-loader map: that is v7's endpoint again.
|
|
8
|
+
- **The VTEX keys v7's VTEX app answered from its own invoke map** (a named export of one of its modules, `invoke.vtex.actions.checkout.addItemsToCart` → `addItemsToCart` in `vtex/actions/checkout`, no handler file of its own) follow the migration's choice, `--vtex-invoke` (PO 2026-10-15: each migration chooses). It has no default: when the site calls such keys and the flag is missing, the script stops before writing anything, lists the keys and both choices, and you run it again with one. A site that calls none needs no flag.
|
|
9
|
+
- `keep`: the module is vendored into `src/vendor` and the server function calls that export, so the call works as in v7. Rewrite it over the client later, like any vendored loader.
|
|
10
|
+
- `v8`: no v7 code. A key `@decocms/apps-vtex`'s client has an operation for (the cart: `getOrCreateCart`, `addItemsToCart`, `updateCartItems`, `addCouponToCart`, `updateOrderFormAttachment`; `simulateCart`, `getSellersByRegion`) becomes a function over the site's client (`src/clients/vtex.ts`) in `src/server/vtex-invoke.server.ts`, which also sends VTEX's cookies to the browser as v7 did (Intelligent Search's session cookies kept back, the site's domain). The report lists what each one does differently from v7's handler; put that in the PR. Every other key is `unportedVtexInvoke(key, props)`, which rejects with the key, and a report line: write it over the client, or rerun with `keep`. On Next.js the cart calls stay stubs too: a server action sets cookies only through `cookies()`, which percent-encodes VTEX's `checkout.vtex.com=__ofid=…`, so they need a route handler that appends the client's `setCookies` to its response.
|
|
11
|
+
- **What has no server function is a stub.** `unportedInvoke(key, props)` from `src/migration-stubs.ts` rejects: `ctx.invoke` in a loader (call the handler module directly with `(props, req)`), and a key nothing answers. `appState(name)` throws where a loader read an app's state off `ctx` (`ctx.vtex`, `ctx.getAppState("x")`); pass the setting in, or call the client in `src/clients/`. Only a v7 loader's `ctx` (`(props, req, ctx)`) is rewritten, never another third argument such as React Query's `onError` context.
|
|
12
|
+
- **v7's invoke passed no app context.** It called `handler(body, request)`. A site loader that reads its third argument (account, secrets) worked when a page ran it (the block map passed them) and threw through invoke. Give its server function the context the block map passes.
|
|
13
|
+
- **Keys v7 had no handler for** failed with "handler not found". The script keeps them failing at the call site (`unportedInvoke`, reported as such), not as stubs in a rebuilt `invoke` tree: list them as follow-ups.
|
|
14
|
+
- **Check the client bundle.** TanStack Start's compiler replaces each handler with an RPC stub and drops its imports; grep `dist/client` JavaScript (not source maps) for secret env names and `node:async_hooks` after the build.
|
|
15
|
+
- v7's generated `invoke.gen.ts` (cart and session actions) is site code now: export each action as its own server function and delete the ones nothing calls.
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
# Porting from a sibling site
|
|
2
|
+
|
|
3
|
+
From the site migrations; the sites and what the commit hashes refer to are listed in `SKILL.md` ("Gotchas by subject").
|
|
4
|
+
|
|
5
|
+
A three-way merge from a site that is already on v8 (`SKILL.md`, "A sibling site already migrated?") brings everything that site changed, not only the migration:
|
|
6
|
+
|
|
7
|
+
- **Its own later product changes.** Read the sibling's history after its script run (`git log <run>..<v8> -- src`) and back out what came from merging its main (a cart read switched from GET to POST, an SSR prefetch skipped) unless the site being migrated has it on its own main.
|
|
8
|
+
- **Vendored copies of another version.** The sibling vendored its installed `@decocms/*`. Diff that version's sources with the site's (`npm pack @decocms/<pkg>@<version>`) and re-vendor what changed (commerce types, `useOffer`); keep the sibling's v8 edits on top. A sibling migrated before the bindings vendored `Image`, `NavigationProgress`, the worker entry or the draft code: take those from `@decocms/tanstack`/`@decocms/nextjs` instead of merging the copies (`framework-code.md`).
|
|
9
|
+
- **Content.** Saved blocks byte-identical on both sides on v7 can take the sibling's migrated version, but check each field it dropped against this site's own types: `deco check` on the site's unmodified content must list every dropped field as unknown.
|
|
10
|
+
- **Editor forms.** The sibling's SEO and loader types match its v7 forms, not necessarily this site's (7.6x added fields to the SEO sections, such as Structured Data and Omit variants, and offered loaders such as `RelatedProducts` in product pickers). Diff the forms against this site's own v7 schema.
|
|
11
|
+
- **Security headers.** Compare the site's v7 `createDecoWorkerEntry` options with the sibling's: a site that passed `securityHeaders: { "Content-Security-Policy": … }` sent an enforced CSP that replaces the default `frame-ancestors` one, and no `X-Frame-Options`. The copied edge cache must send that header, not the sibling's report-only list. The worker adds Studio's origins to that policy's `script-src` (the Studio channel imports the editor's modules from them) and `frame-ancestors`; drop a copy of Studio's origin the sibling wrote into its own `script-src`. A Next.js site passes its policy through `withStudioCsp` from `@decocms/nextjs`.
|
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
# Site code: what the bindings leave to the site
|
|
2
|
+
|
|
3
|
+
From the site migrations; the sites and what the commit hashes refer to are listed in `SKILL.md` ("Gotchas by subject"). The bindings themselves are in [`framework-code.md`](./framework-code.md). This applies on TanStack Start and Next.js alike.
|
|
4
|
+
|
|
5
|
+
- **SEO/head**: a head builder; SEO blocks return the page's SEO.
|
|
6
|
+
- **Device detection**: v7's own from `@decocms/compat-v7` (`detectDevice` from `/device`; `useDevice` under `DeviceProvider` from `/tanstack` or `/nextjs`, seeded with `requestDevice()` from their `/server`). The TanStack worker keys its cache by device on its own.
|
|
7
|
+
- **Cookies and request state**: pass the request and response headers explicitly, or a site-owned `AsyncLocalStorage`, instead of v7's `RequestContext`.
|
|
8
|
+
- **Cart, user, wishlist, sign-in flows and commerce loaders**: vendored next to the loaders the script copied, sending through the v8 client.
|
|
9
|
+
- **Section loaders**: v7's registered map, run once per page by `loadSections` (`.deco/index.ts`, over `runSectionLoaders` from `@decocms/compat-v7/sections`), globals included; a loader that throws keeps its section's saved props and lands in `degraded`.
|
|
10
|
+
- **Module-level config from v7 apps is cross-request state.** A v7 app's `configureX({...})` singleton (the website app's SEO defaults, for one) called from the page loader on every request is shared by every request in the isolate. A preview host and production share the worker, so a draft's values can land in a concurrent release render that the edge then caches. Put per-page values in the page's own state and pass them to whatever read the singleton.
|
|
11
|
+
- **Identification headers** (`x-powered-by`, the outbound `User-Agent`) are the site's own values; if they change (v7 sent its package version), list it as the site's difference.
|
|
12
|
+
- **Keep v7's platform client, or adopt the v8 one?** Keeping the vendored v7 client (and its cached loaders and fetch cache) keeps every upstream request identical, so recorded upstream fixtures replay. If you keep it, drop the v8 `@decocms/apps-<platform>` dependency nothing imports, and list the move to its client plus the `/next/caching` recipe (`cachedLoader` is gone in v8) as a follow-up.
|
|
13
|
+
- **Error reporting.** v7's `onResolveError` sent every failed section or loader to the site's exception reporting. v8 has no hook: `client.resolve` returns `[value, error]`, and a section loader that throws is caught in its block function. Report both explicitly there (same attributes as before, so dashboards keep working); `console.error` alone only reaches the SDK's sampled log export.
|
|
14
|
+
- **A worker-level A/B split (`withABTesting`, `SITES_KV`).** If the KV holds no config for the site's hosts, nothing was split: delete the wrapper and the binding. If it does, on TanStack Start replace the wrapper with `abTestingRoutes` from `@decocms/compat-v7/tanstack/worker` (v7's split as a handler run first in `createDecoWorker`'s `routes`, with `worker: () => worker` so the worker's own bucket still gets its cookie; README of `@decocms/compat-v7`). One difference a site sees: legacy-origin HTML leaves through the worker, so it gets the worker's `preload` hints and security headers, which v7 added only to its own pages.
|
|
15
|
+
- **Not ported to the TanStack worker**: v7's caching of POST server functions by body. A site that relied on it keeps that wrapper or lists it.
|
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
# Telemetry and analytics
|
|
2
|
+
|
|
3
|
+
From the site migrations; the sites and what the commit hashes refer to are listed in `SKILL.md` ("Gotchas by subject").
|
|
4
|
+
|
|
5
|
+
- Telemetry is explicit params only: the SDK reads no environment variable (`OTEL_*` and v7's `DECO_OTEL_*` are ignored). A site that kept a collector reads its own variables and passes `telemetry: { endpoint, headers }`; with `createCMS({ site, token })` and no `endpoint`, telemetry goes to the hosted collector (a `token` without `site` is a configuration error). Pass `telemetry: false` in dev or parity runs (`89eae7d`). v7's per-signal `DECO_OTEL_{METRICS,LOGS,TRACES}_ENDPOINT` have no v8 equivalent: every signal goes to `<endpoint>/v1/<signal>`.
|
|
6
|
+
- **New telemetry is a behaviour change.** A site with its own OpenTelemetry export that v7 never fed CMS telemetry starts sending it once `telemetry` points at that collector. List the new traffic for the product owner.
|
|
7
|
+
- `service.name`, `service.version` and `deployment.environment.name` come from `telemetry.resource`, on the hosted collector too (`telemetry: { resource }` without `endpoint`). v7 took them from `DECO_SITE_NAME`, the `CF_VERSION_METADATA` binding and `DECO_ENV_NAME`: keep the `version_metadata` binding in `wrangler.jsonc`, read the three in the site and pass them (or a Vite `define` of the commit). Vars left in `wrangler.jsonc` that nothing reads are dead config a reviewer will flag. v7's `DECO_OTEL_ERROR_PROMOTION_RATE` becomes `errorSampleRate` in `CMS.json`'s telemetry section (default 0.05, capped by `telemetry.limits`, default 0.1); `DECO_OTEL_LOGS_MIN_LEVEL` has no equivalent (v8 sends error logs only): list it.
|
|
8
|
+
- **Local development and hosted releases.** `createCMS` reads no `NODE_ENV` and has no `dev` option. With `site`, content always comes from the CDN, on the dev server too; without `site`, it is the `content` the site passes. Passing both throws. A site that wants local files in dev picks one or the other in its own code.
|
|
9
|
+
- **v7 Workers bindings with no v8 writer.** v7's `instrumentWorker` wrote per-route request counts, edge cache hit/miss and request duration to an Analytics Engine dataset (`DECO_METRICS`) and read `CF_VERSION_METADATA`. In v8, `createDecoWorker` records every request as `http.server.request.duration` (seconds) in the CMS's own telemetry, with `http.route` (the content's page template, `redirect` for every CMS redirect, a fixed one such as `/_serverFn/*` or `/assets/*`, else `unmatched`), `http.request.method`, `status_class`, `cache` (`DRAFT` for a preview, else from the `X-Cache` the site's `pageCache` answers: `HIT`/`MISS`/`BYPASS`) and `device`; with no `token` and no `endpoint` it records nothing. On Next.js, `export { register } from "@decocms/nextjs/instrumentation"` in `instrumentation.ts` records the same metric from Next's own request span: `http.route` is Next's route template (`/[[...path]]`, `/_draft/[[...path]]`; RSC requests under their page's), `cache` is `DRAFT` for a draft render and otherwise `BYPASS` (Next's `x-nextjs-cache` is not visible to the span), no `device`; responses the proxy answers itself are not counted and Edge routes are `unmatched`. A site with its own OpenTelemetry SDK (`@vercel/otel`) adds `serverRequestSpanProcessor()` to its span processors instead. Both bindings record through `recordServerRequest` from `@decocms/blocks/metrics`; a site never imports it (and `@decocms/blocks/fetch` is only `createInstrumentedFetch`). Nothing writes `DECO_METRICS`; a site that still wants it writes there from its worker entry's `pageCache` (it knows the profile and the decision). Don't keep a binding nothing writes, and don't drop one silently: list each by name (and the edge layer's `deco.cache.requests` counter) as a product decision in the PR.
|
|
10
|
+
- Analytics: `AnalyticsScript` with `(await cms.settings()).analytics` plus `track` replace OneDollarStats (the collector lives in the `analytics` section of `CMS.json`); it sends collector beacons directly instead of loading the SDK (`4a50b13`, blog `9e97455`).
|
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
# Verify
|
|
2
|
+
|
|
3
|
+
The full checklist behind `SKILL.md` ("Verify").
|
|
4
|
+
|
|
5
|
+
```bash
|
|
6
|
+
bunx deco schema && bunx deco content && bunx deco check # 0 errors
|
|
7
|
+
bun run typecheck && bun run build
|
|
8
|
+
```
|
|
9
|
+
|
|
10
|
+
The committed `.deco/schema.gen.json` must carry the top-level `"blocksMajor": 8` that `deco schema` writes: Studio treats a site as v8 **only** when its schema has `blocksMajor === 8` (the file name doesn't count; anything else edits as v7), and `deco check` fails without it. A schema generated by a CLI that predates the field must be regenerated with one that writes it, then committed.
|
|
11
|
+
|
|
12
|
+
A v7 site often carries type errors of its own. Count them on the v7 commit first, and report the v8 count against it per file: name every remaining error in a file the migration touched instead of claiming there are none. Fix them with type-only changes, and rerun `deco schema` + `deco check` after each: a section's `Props` type *is* its editor form, so repairing a broken type import there (one that resolved to `any`) changes the schema and can make `deco check` reject saved content. Leave such an error, or fix the content with it, never silently. Don't fix an error by giving code that never ran (an undefined variable in a component) real values: that changes what renders.
|
|
13
|
+
|
|
14
|
+
Run it once more **without any local link** (a `decocms/blocks` checkout linked into `node_modules` ships compiled `dist/`, the npm package may not): a clean `install --frozen-lockfile && build` from the committed lockfile, the way CI and the deploy run it. Then `git diff .deco/schema.gen.json`: the build regenerates it, so commit what the committed dependency's CLI writes, or every clean build leaves the tree dirty. If it differs from the linked checkout's, check both against v7's forms; when the published one is the worse, list a follow-up to bump once the fix is released.
|
|
15
|
+
|
|
16
|
+
**Probe drafts by hand** on the dev server and on a production build: `?__draft=<pointer>` on an allowed host renders the draft and sets the cookie, the cookie alone keeps the next page in the draft, a host outside the release's preview hosts (Studio's) and a malformed pointer get the release, `?__draft=off` clears the cookie. Check the headers too: any request with `?__draft=` (`off` included) or the draft cookie answers `Cache-Control: max-age=0, no-cache, must-revalidate` and `noindex`, a link to a deleted draft renders the release with a calm notice (never a 500), and on TanStack the release's `X-Cache` still goes MISS then HIT. A parity harness can't catch a dead draft path when v7's was dead too: both sides render the release.
|
|
17
|
+
|
|
18
|
+
Grep the tree for v7 tooling in comments, docs and `.gitattributes` (`blocks-cli`, `meta.gen.json`, `sections.gen.ts`, `generate-schema`, `ts-morph`) and reword each to `deco schema` or the block map. Check that the claim still holds under `deco schema` instead of renaming the tool: some v7 quirks are gone, and the comment should then say it was v7.
|
|
19
|
+
|
|
20
|
+
Then compare the migrated site with the v7 one page by page (a parity harness: SSR HTML, JSON-LD, analytics calls, cache headers, third-party requests). Compare the editor forms as well (v7 `meta.gen.json` vs v8 `schema.gen.json`): many differences are stale v7 files or v7 heuristics v8 drops on purpose, a few are CLI bugs to fix ([`editor-forms.md`](./editor-forms.md)). Encode every difference the product owner approves as an explicit rule, never a blanket ignore. Keep explained-but-unapproved ones as `pending`, and have a strict compare fail on them ([`parity.md`](./parity.md)).
|