@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,145 @@
|
|
|
1
|
+
# Providers and the Deco image CDN
|
|
2
|
+
|
|
3
|
+
`@decocms/blocks/image` is pure functions: no React, no framework, no module
|
|
4
|
+
state. A site composes an `ImageUrl` from `ImageProvider`s and passes it to its
|
|
5
|
+
binding (see [components-per-binding.md](./components-per-binding.md)).
|
|
6
|
+
|
|
7
|
+
## The pieces
|
|
8
|
+
|
|
9
|
+
```ts
|
|
10
|
+
interface ResizeOptions { width: number; height?: number; fit?: Fit; quality?: Quality }
|
|
11
|
+
type Fit = "contain" | "cover" | "fill";
|
|
12
|
+
type Quality = "low" | "medium" | "high" | "original" | number;
|
|
13
|
+
|
|
14
|
+
interface ImageProvider {
|
|
15
|
+
name: string;
|
|
16
|
+
match(src: string): boolean; // does this provider handle src?
|
|
17
|
+
format(src: string, o: ResizeOptions): string | null; // null: leave src to the next provider
|
|
18
|
+
hosts?: string[]; // hosts its URLs point at
|
|
19
|
+
}
|
|
20
|
+
|
|
21
|
+
const imageUrl = createImageUrl({ providers: [/* in order */] });
|
|
22
|
+
imageUrl(src, { width: 640 }); // resized URL
|
|
23
|
+
imageUrl.isOptimizable(src); // some provider matches (false for "", data:, unknown)
|
|
24
|
+
imageUrl.hosts(); // every provider's hosts, deduplicated
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
Order matters. `createImageUrl` walks the list, skips providers whose `match`
|
|
28
|
+
is false, and returns the first non-null `format`. Put the narrow providers
|
|
29
|
+
(platform catalogs) first and the broad one (`decoCdn({ sources: "all" })`) last.
|
|
30
|
+
|
|
31
|
+
## `decoCdn(options)`
|
|
32
|
+
|
|
33
|
+
Builds `https://<domain>/image?fit=&width=[&height=][&quality=]&src=<path>`.
|
|
34
|
+
|
|
35
|
+
| Option | Default | What it does |
|
|
36
|
+
|---|---|---|
|
|
37
|
+
| `domain` | `"assets.decocms.com"` | CDN host. `decoims.com` and `deco-assets.edgedeco.com` serve the same endpoint. A scheme or trailing slash is stripped. |
|
|
38
|
+
| `quality` | none | Tier used when a call names none. Without it, no `quality` param is sent and the CDN uses its own default (60% per the code's comment). |
|
|
39
|
+
| `fit` | `"cover"` | Fit when a call names none. |
|
|
40
|
+
| `sources` | `"deco"` | Which sources it resizes. `"deco"`: the Deco asset hosts, `domain` and `legacyHosts`. `"all"`: any non-empty, non-`data:` source. Or a predicate `(src) => boolean`. |
|
|
41
|
+
| `legacyHosts` | `["decoims.com"]` when `domain` is `assets.decocms.com`, else `[]` | Older CDN hosts whose URLs are re-served from `domain`. |
|
|
42
|
+
| `stripAssetHosts` | `"leading"` | How `https://assets.decocache.com/` and the `deco-sites-assets` S3 bucket prefix are removed from the source. `"leading"`: only when the source starts with one. `"anywhere"`: the first occurrence of each, wherever it is. |
|
|
43
|
+
| `layout` | `"src-last"` | Query order. `"quality-last"` matches what next/image loaders built on v7's helper wrote. Keep the one the site used before, so the CDN cache stays warm. |
|
|
44
|
+
|
|
45
|
+
Behaviour worth knowing:
|
|
46
|
+
|
|
47
|
+
- **The source's query string is dropped.** `decoCdn` keeps only the part of
|
|
48
|
+
`src` before `?`.
|
|
49
|
+
- **Already-resized URLs are unwrapped.** A source that is itself a Deco CDN
|
|
50
|
+
`/image?…&src=…` URL (on any of its hosts) is re-resized from its inner `src`.
|
|
51
|
+
Resizing twice gives the same URL.
|
|
52
|
+
- **Self-fetch loop on Cloudflare hosts.** On `assets.decocms.com` and
|
|
53
|
+
`decoims.com`, a `decoims.com` source is stripped to its path. The code notes
|
|
54
|
+
that a `decoims.com` `src=` there makes the CDN fetch itself (508). On the
|
|
55
|
+
Azion hosts (`deco-assets.edgedeco.com`, `deco-assets.decoazn.com`) the full
|
|
56
|
+
`decoims.com` URL is kept, since they fetch it fine.
|
|
57
|
+
- **Numbers are ignored.** `quality: 90` on a call falls back to the
|
|
58
|
+
`quality` option. Only the four tier names reach the CDN.
|
|
59
|
+
- `hosts` is `[domain]`.
|
|
60
|
+
|
|
61
|
+
## Platform providers
|
|
62
|
+
|
|
63
|
+
These live in the platform's client package, not in `@decocms/blocks`. List them
|
|
64
|
+
before `decoCdn`.
|
|
65
|
+
|
|
66
|
+
### VTEX: `@decocms/apps-vtex/image`
|
|
67
|
+
|
|
68
|
+
Each reproduces one URL format sites already use, byte for byte. Pick the one
|
|
69
|
+
the site's old helper matched; changing format changes every image URL and
|
|
70
|
+
empties the CDN cache.
|
|
71
|
+
|
|
72
|
+
| Provider | Matches | Output |
|
|
73
|
+
|---|---|---|
|
|
74
|
+
| `vtexCatalog()` | `*.vteximg.com.br`, `*.vtexassets.com`, `*.myvtex.com` URLs with `/arquivos/ids/{id}` | `/arquivos/ids/{id}-{width}-{height ?? width}/…` (v7's `Image`). Ignores quality. |
|
|
75
|
+
| `vtexCatalogFrame({ frame? })` | Any host with `/arquivos/ids/{id}[-w-h]/` | `{id}-{w}-{h}`. With `frame: { width, height }`, height is always `round(width × frame.height / frame.width)`; VTEX fills the rest with white. |
|
|
76
|
+
| `vtexCatalogWebp({ quality? })` | Any URL with `/ids/{id}` and a file extension | `/ids/{id}-{width}-auto/{file}.webp?…&quality=` (VTEX keeps the ratio). Without an extension it returns null. |
|
|
77
|
+
| `vtexFileManager({ via, quality? })` | URLs containing `vtexassets` and `/assets` (file-manager images) | `via: "query"`: `?width=&aspect=true&quality=`. `via: "thumbor"`: PNG/JPEG/WebP through `/unsafe/{w}x0/filters:…:format(webp)/…`; SVG and GIF unchanged. |
|
|
78
|
+
|
|
79
|
+
VTEX quality is on a 1 to 10 scale. Tiers map to 60/70/80/100 and then to
|
|
80
|
+
6/7/8/10; numbers above 10 are read as 1 to 100, divided by 10 and rounded up. Default 8.
|
|
81
|
+
|
|
82
|
+
```ts
|
|
83
|
+
import { createImageUrl, decoCdn } from "@decocms/blocks/image";
|
|
84
|
+
import { vtexCatalog, vtexFileManager } from "@decocms/apps-vtex/image";
|
|
85
|
+
|
|
86
|
+
export const imageUrl = createImageUrl({
|
|
87
|
+
providers: [
|
|
88
|
+
vtexCatalog(),
|
|
89
|
+
vtexFileManager({ via: "query" }),
|
|
90
|
+
decoCdn({ sources: "all", quality: "high" }),
|
|
91
|
+
],
|
|
92
|
+
});
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
### Shopify: `@decocms/apps-shopify/image`
|
|
96
|
+
|
|
97
|
+
`shopifyCdn()` matches `https://cdn.shopify.com…` and sets `width`, `height`
|
|
98
|
+
(when given) and `crop=center` on the query. It ignores `quality` and `fit`.
|
|
99
|
+
|
|
100
|
+
### Other platforms
|
|
101
|
+
|
|
102
|
+
No other `@decocms/apps-*` package ships an image provider. If a platform's CDN
|
|
103
|
+
resizes by URL, write a provider in the site:
|
|
104
|
+
|
|
105
|
+
```ts
|
|
106
|
+
import type { ImageProvider } from "@decocms/blocks/image";
|
|
107
|
+
|
|
108
|
+
export const platformCdn: ImageProvider = {
|
|
109
|
+
name: "platform",
|
|
110
|
+
hosts: ["images.platform.example"],
|
|
111
|
+
match: (src) => src.startsWith("https://images.platform.example/"),
|
|
112
|
+
format(src, { width, height }) {
|
|
113
|
+
const url = new URL(src);
|
|
114
|
+
url.searchParams.set("w", String(width));
|
|
115
|
+
if (height) url.searchParams.set("h", String(height));
|
|
116
|
+
return url.href;
|
|
117
|
+
},
|
|
118
|
+
};
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
Return `null` from `format` for a source you matched but cannot resize, so the
|
|
122
|
+
next provider gets it. Without a provider, `decoCdn({ sources: "all" })` sends
|
|
123
|
+
those images through the Deco CDN instead, which also works.
|
|
124
|
+
|
|
125
|
+
## `hosts()` for CSP and preconnect
|
|
126
|
+
|
|
127
|
+
`imageUrl.hosts()` lists every provider's hosts once, wildcards included (the
|
|
128
|
+
VTEX providers report `*.vtexassets.com` and similar). No binding reads it for
|
|
129
|
+
you. If the site sets a Content-Security-Policy, add these hosts to `img-src`;
|
|
130
|
+
the CSP itself is set up as described in `deco-tanstack-site` or
|
|
131
|
+
`deco-nextjs-site`. A source that passes through unchanged loads from its own
|
|
132
|
+
host, which `hosts()` does not list.
|
|
133
|
+
|
|
134
|
+
## Which `decoCdn` setup to start from
|
|
135
|
+
|
|
136
|
+
| Site | Providers |
|
|
137
|
+
|---|---|
|
|
138
|
+
| Content site, images uploaded to Deco | `[decoCdn({ quality: "high" })]` |
|
|
139
|
+
| Images from many hosts, all through the Deco CDN | `[decoCdn({ sources: "all", quality: "high" })]` (this is what TanStack's default does, without the tier) |
|
|
140
|
+
| VTEX storefront | `[vtexCatalog(), decoCdn({ sources: "all", quality: "high" })]` |
|
|
141
|
+
| Shopify storefront | `[shopifyCdn(), decoCdn({ sources: "all", quality: "high" })]` |
|
|
142
|
+
| Migrated v7 site | Match the old domain, quality and layout exactly, so URLs do not change. `deco-v7-to-v8-migration` reads these from the site's old helper. |
|
|
143
|
+
|
|
144
|
+
`"high"` above is a starting point, not a package default. See
|
|
145
|
+
[quality-and-lcp.md](./quality-and-lcp.md).
|
|
@@ -0,0 +1,93 @@
|
|
|
1
|
+
# Quality tiers, sizes and the LCP image
|
|
2
|
+
|
|
3
|
+
## Tiers
|
|
4
|
+
|
|
5
|
+
The Deco CDN takes four named tiers. Other code in the packages maps them to
|
|
6
|
+
percentages:
|
|
7
|
+
|
|
8
|
+
| Tier | Percent (VTEX providers, `nextImageOptimizer`) |
|
|
9
|
+
|---|---|
|
|
10
|
+
| `low` | 60 |
|
|
11
|
+
| `medium` | 70 |
|
|
12
|
+
| `high` | 80 |
|
|
13
|
+
| `original` | 100 |
|
|
14
|
+
|
|
15
|
+
With no tier, `decoCdn` sends no `quality` parameter and the CDN applies its own
|
|
16
|
+
default (60% per the comment in `image.ts`). That is the same percentage the
|
|
17
|
+
table above gives `low`, so a site that never sets a tier should expect
|
|
18
|
+
low-tier quality on every Deco-CDN image.
|
|
19
|
+
|
|
20
|
+
## Where quality is set
|
|
21
|
+
|
|
22
|
+
| Level | How | Notes |
|
|
23
|
+
|---|---|---|
|
|
24
|
+
| Whole site | `decoCdn({ quality: "high" })` in the site's `imageUrl` | The usual place. This is v7's `registerImageQuality`. |
|
|
25
|
+
| One subtree (TanStack) | A nested `<ImageUrlProvider value={otherImageUrl}>` built with another tier | `Image`, `Picture` and `Source` have no `quality` prop. |
|
|
26
|
+
| One URL | `imageUrl(src, { width, quality: "original" })`, `srcSet(imageUrl, src, { …, quality })`, `preloadLink(…, { quality })` | A call's tier wins over the `decoCdn` option. Numbers are ignored by `decoCdn`. |
|
|
27
|
+
| next/image | `decoCdn({ quality })` | next/image's numeric `quality` is ignored by `decoCdn`; `vtexCatalogWebp` and `vtexFileManager` read it. |
|
|
28
|
+
|
|
29
|
+
The "Default Image Quality" field of the Fresh-era website app has no v8
|
|
30
|
+
equivalent. Quality is code. To let editors change it, read a value from a
|
|
31
|
+
settings block and build the `ImageUrl` from it; that is site code, not a
|
|
32
|
+
package feature.
|
|
33
|
+
|
|
34
|
+
Choosing a tier:
|
|
35
|
+
|
|
36
|
+
- `high` for product photos, hero banners, anything people zoom into.
|
|
37
|
+
- `medium` is a fair balance for thumbnails and grids.
|
|
38
|
+
- `low` shows visible artifacts on product photography. Avoid it as a
|
|
39
|
+
site-wide value.
|
|
40
|
+
- `original` adds bytes, not detail. A source that is too small stays blurry
|
|
41
|
+
at any tier (see [troubleshooting.md](./troubleshooting.md)).
|
|
42
|
+
|
|
43
|
+
## `sizes` and the srcset
|
|
44
|
+
|
|
45
|
+
`Image` and `Source` emit two width candidates: `width` and `2 × width`. The
|
|
46
|
+
browser picks one using `sizes`. When `sizes` is not set, `Image` uses
|
|
47
|
+
`"(max-width: 768px) 100vw, 50vw"`.
|
|
48
|
+
|
|
49
|
+
That default fits a two-column layout. For a full-width hero on desktop it
|
|
50
|
+
tells the browser the image is half the viewport, so it may pick the smaller
|
|
51
|
+
candidate and the hero looks soft on large screens. Set `sizes` to the slot's
|
|
52
|
+
real width, e.g. `sizes="100vw"` for a full-bleed banner, or
|
|
53
|
+
`"(max-width: 768px) 100vw, 1280px"` for a fixed container.
|
|
54
|
+
|
|
55
|
+
If one slot spans many widths (fluid grids), pass explicit candidates instead
|
|
56
|
+
of factors: `srcSet={srcSet(useImageUrl(), src, { widths: [360, 720, 1080, 1440], ratio: 0.5 })}`.
|
|
57
|
+
|
|
58
|
+
## Preloading the LCP image
|
|
59
|
+
|
|
60
|
+
Preload exactly one image per page: the one that is the Largest Contentful
|
|
61
|
+
Paint on first view. Usually the first hero banner or the main product photo.
|
|
62
|
+
|
|
63
|
+
- TanStack, one image: `<Image preload … />`. It renders a preload link,
|
|
64
|
+
`loading="eager"` and `fetchPriority="high"`.
|
|
65
|
+
- TanStack, art-directed: `<Picture preload>` with a `Source` per media query.
|
|
66
|
+
Each `Source` preloads with its own `media`, so a phone does not download the
|
|
67
|
+
desktop banner.
|
|
68
|
+
- Head links: `preloadLink(imageUrl, src, { width, sizes, media })` returns the
|
|
69
|
+
attributes for a `<link>` in the route's head.
|
|
70
|
+
- Next.js: use next/image's own preload or priority option.
|
|
71
|
+
|
|
72
|
+
Rules:
|
|
73
|
+
|
|
74
|
+
- **Preload only what renders above the fold on first load.** A preload for a
|
|
75
|
+
carousel's second slide or a below-the-fold section wastes bandwidth the LCP
|
|
76
|
+
image needs.
|
|
77
|
+
- **Make the preload match the `<img>`.** Same `src`, same `width`/`height`,
|
|
78
|
+
same `sizes`. Otherwise the browser downloads two files. `Image` builds both
|
|
79
|
+
from the same props, so this holds as long as you do not also write a manual
|
|
80
|
+
preload. A `Source` preload link carries no `imageSizes`, so give the
|
|
81
|
+
`Source` no `sizes` either, or write that preload yourself with
|
|
82
|
+
`preloadLink`.
|
|
83
|
+
- **Sections decide preload from props.** A banner section usually takes a
|
|
84
|
+
`preload` or "is LCP" boolean, set on the first instance in the page. Do not
|
|
85
|
+
hardcode `preload` in a component that appears many times.
|
|
86
|
+
- **Never lazy-load the LCP image.** `loading="lazy"` on it delays LCP. `Image`
|
|
87
|
+
defaults to lazy unless `preload` is set.
|
|
88
|
+
- **Always set `width` and `height`.** They give the box its aspect ratio
|
|
89
|
+
before the file arrives, which avoids layout shift.
|
|
90
|
+
|
|
91
|
+
For measuring LCP and CLS on a page, and fixes beyond images, load
|
|
92
|
+
`deco-storefront-performance`. Generic HTML guidance (formats, `fetchpriority`,
|
|
93
|
+
media-specific preloads) is in `image-optimizer` (decocms/skills).
|
|
@@ -0,0 +1,147 @@
|
|
|
1
|
+
# Troubleshooting images
|
|
2
|
+
|
|
3
|
+
Start from the symptom. Most checks need two things: the `src` stored in the
|
|
4
|
+
content (in `.deco/blocks` or the loader's output) and the URL the page actually
|
|
5
|
+
requested (DevTools, Network, filter "Img").
|
|
6
|
+
|
|
7
|
+
| Symptom | Likely cause | Section |
|
|
8
|
+
|---|---|---|
|
|
9
|
+
| Every image on the site is a bit soft | No tier, or `low`, in `decoCdn` | [Soft everywhere](#soft-everywhere) |
|
|
10
|
+
| One banner is pixelated, worse on phones and Retina screens | Source has fewer pixels than the slot needs | [Undersized source](#undersized-source) |
|
|
11
|
+
| A full-width hero is soft only on wide screens | `sizes` default says 50vw | [Wrong sizes](#wrong-sizes) |
|
|
12
|
+
| Images are huge (MBs) and slow | Source passes through unresized | [Not resized](#not-resized) |
|
|
13
|
+
| 404 or 508 on `/image?…` | Bad `src` inside the CDN URL | [Broken CDN URLs](#broken-cdn-urls) |
|
|
14
|
+
| Image blocked, console shows a CSP error | Host missing from `img-src` | [providers-and-cdn.md](./providers-and-cdn.md#hosts-for-csp-and-preconnect) |
|
|
15
|
+
| Mobile crop looks wrong, desktop fine | `Source` ratios differ per breakpoint | [Mobile crop](#mobile-crop) |
|
|
16
|
+
| Page jumps as images load | Missing `width`/`height` | [quality-and-lcp.md](./quality-and-lcp.md#preloading-the-lcp-image) |
|
|
17
|
+
|
|
18
|
+
## Soft everywhere
|
|
19
|
+
|
|
20
|
+
Look at the `quality` parameter on any requested `/image?…` URL.
|
|
21
|
+
|
|
22
|
+
- **No `quality` parameter**: the site's `decoCdn` has no `quality` option, so
|
|
23
|
+
the CDN default applies to every image. Set `decoCdn({ quality: "high" })`.
|
|
24
|
+
- **`quality=low`**: someone chose `low` site-wide. Raise it.
|
|
25
|
+
- **Not a Deco CDN URL at all**: the image came from a platform provider.
|
|
26
|
+
`vtexCatalogWebp` and `vtexFileManager` use VTEX's 1 to 10 scale (default
|
|
27
|
+
8); `vtexCatalog`, `vtexCatalogFrame` and `shopifyCdn` ignore quality.
|
|
28
|
+
|
|
29
|
+
A site-wide tier change touches every image URL, so the CDN cache refills
|
|
30
|
+
once. That is expected.
|
|
31
|
+
|
|
32
|
+
## Undersized source
|
|
33
|
+
|
|
34
|
+
The most common "distorted image" report is not stretching. It is a source with
|
|
35
|
+
fewer pixels than the slot needs on a high-density screen, upscaled by the
|
|
36
|
+
browser. Tell-tale sign: **sharp when the file is opened directly, pixelated on
|
|
37
|
+
the site.** Opening it shows its small native size; the site shows it larger.
|
|
38
|
+
|
|
39
|
+
**Mechanism.** `width` on `Image` or `Source` is the 1x CSS width. The srcset
|
|
40
|
+
also offers `2 × width`, and on a DPR 2 screen the browser takes that one. If
|
|
41
|
+
the uploaded file is smaller, the CDN or browser has to invent pixels. No
|
|
42
|
+
parameter fixes that: `quality: "original"` only adds bytes.
|
|
43
|
+
|
|
44
|
+
**Required source pixels = rendered CSS width × device pixel ratio.** Use 2x as
|
|
45
|
+
the target; most phones and laptops are DPR 2 or more.
|
|
46
|
+
|
|
47
|
+
### Diagnose
|
|
48
|
+
|
|
49
|
+
1. Measure the **original** file, not a resized URL. Take the `src` from the
|
|
50
|
+
content (before it went through `ImageUrl`) and download that:
|
|
51
|
+
|
|
52
|
+
```bash
|
|
53
|
+
curl -sL "<original src>" -o /tmp/orig
|
|
54
|
+
sips -g pixelWidth -g pixelHeight /tmp/orig # macOS; or: identify /tmp/orig
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
Measuring a `/image?width=1400…` URL reports 1400, the output size, which
|
|
58
|
+
hides the problem.
|
|
59
|
+
2. Read the `width` on the component. Each `Source` has its own:
|
|
60
|
+
|
|
61
|
+
```tsx
|
|
62
|
+
<Source media="(min-width: 1024px)" src={desktop} width={700} height={342} /> // needs 1400×684
|
|
63
|
+
<Source media="(max-width: 1023px)" src={mobile} width={375} height={184} /> // needs 750×368
|
|
64
|
+
```
|
|
65
|
+
3. Source width ≥ `width × 2`: sharp. Smaller: that is the bug. In one measured
|
|
66
|
+
case a 542px-wide file filled a slot that needed 1400px, a 2.6x upscale.
|
|
67
|
+
|
|
68
|
+
### Fix
|
|
69
|
+
|
|
70
|
+
Upload a larger source, at least 2x the slot, in the slot's aspect ratio. Larger
|
|
71
|
+
is fine: the CDN downscales, which never blurs.
|
|
72
|
+
|
|
73
|
+
These do **not** fix it:
|
|
74
|
+
|
|
75
|
+
- Changing `width`/`height` on the component. The slot on screen is the same,
|
|
76
|
+
so the browser upscales anyway.
|
|
77
|
+
- `quality: "original"`. No detail is added. Go back to `"high"`.
|
|
78
|
+
- Shrinking the component with CSS. It only helps below half the source width,
|
|
79
|
+
and it changes the design everywhere the component is used.
|
|
80
|
+
|
|
81
|
+
No larger original? An AI upscaler can help. Choose a scale that clears the
|
|
82
|
+
target (3x on 542px gives 1626px, above 1400; 2x gives 1084px, below). Check
|
|
83
|
+
fine detail (text, logos, small product features) before shipping. A real
|
|
84
|
+
high-resolution photo is always better.
|
|
85
|
+
|
|
86
|
+
Then stop it from happening again: put the 2x size in the field's
|
|
87
|
+
`@description` (see [components-per-binding.md](./components-per-binding.md#image-fields-in-section-props)).
|
|
88
|
+
|
|
89
|
+
### Explaining it to a non-technical stakeholder
|
|
90
|
+
|
|
91
|
+
> The image looks pixelated because the uploaded file is smaller than the space
|
|
92
|
+
> it fills. The banner needs 1400×684 px (750×368 px on mobile); the current file
|
|
93
|
+
> is 542×280 px, so the site has to stretch it. It looks sharp when you open the
|
|
94
|
+
> file because it is shown at its small original size there. Upload the image at
|
|
95
|
+
> the larger size, ideally the original high-resolution photo.
|
|
96
|
+
|
|
97
|
+
## Wrong sizes
|
|
98
|
+
|
|
99
|
+
`Image` defaults `sizes` to `"(max-width: 768px) 100vw, 50vw"`. On a 1440px
|
|
100
|
+
screen that tells the browser a full-width hero is 720 CSS px wide, so it may
|
|
101
|
+
pick the 1x candidate. Set `sizes` to the real layout (see
|
|
102
|
+
[quality-and-lcp.md](./quality-and-lcp.md#sizes-and-the-srcset)).
|
|
103
|
+
|
|
104
|
+
## Not resized
|
|
105
|
+
|
|
106
|
+
The requested URL equals the `src` in the content: no provider matched it.
|
|
107
|
+
|
|
108
|
+
- `imageUrl.isOptimizable(src)` returns false for it. Check in a test or a
|
|
109
|
+
console.
|
|
110
|
+
- `decoCdn()` without `sources` resizes only Deco-hosted URLs. For other hosts,
|
|
111
|
+
add the platform provider or use `decoCdn({ sources: "all" })`.
|
|
112
|
+
- A provider listed after `decoCdn({ sources: "all" })` never runs. Move it
|
|
113
|
+
earlier.
|
|
114
|
+
- `data:` URIs and empty strings are never resized, by design.
|
|
115
|
+
- On Next.js, a source no provider resizes goes to `fallback`, or is returned
|
|
116
|
+
unchanged. Pass `fallback: nextImageOptimizer` if you want Next to resize it.
|
|
117
|
+
- A relative path like `/assets/banner.jpg` is not a Deco-hosted URL, so the
|
|
118
|
+
default `decoCdn()` leaves it alone and the site serves the file as is. With
|
|
119
|
+
`sources: "all"` it becomes `src=/assets/banner.jpg` on the CDN. Check that the
|
|
120
|
+
CDN can serve such a URL before relying on it.
|
|
121
|
+
|
|
122
|
+
## Broken CDN URLs
|
|
123
|
+
|
|
124
|
+
- **`src=image` or `src=<cdn>/image`**: an already-resized URL was resized
|
|
125
|
+
again by older code. v8 `decoCdn` unwraps these. If you still see them, some
|
|
126
|
+
code builds CDN URLs by hand; switch it to `imageUrl`.
|
|
127
|
+
- **508 on `assets.decocms.com` or `decoims.com`**: the `src` points back at
|
|
128
|
+
`decoims.com`, and the CDN fetches itself. `decoCdn` strips `decoims.com`
|
|
129
|
+
from sources when it is in `legacyHosts` (the default on those domains). With
|
|
130
|
+
a custom `legacyHosts: []` on `assets.decocms.com` and `sources: "all"`, a
|
|
131
|
+
`decoims.com` source is sent whole as `src=` and the loop comes back.
|
|
132
|
+
- **404 with a valid-looking `src`**: characters like `%`, `&`, `#`, `+` in a
|
|
133
|
+
file name. `decoCdn` escapes them only when it unwraps a nested URL; rename
|
|
134
|
+
such files when you upload them. The v8 upload endpoint already does (see
|
|
135
|
+
[asset-upload.md](./asset-upload.md)).
|
|
136
|
+
- **The query string on the source disappeared**: `decoCdn` drops everything
|
|
137
|
+
after `?` in `src`. A source that needs its query (signed URLs) must not go
|
|
138
|
+
through `decoCdn`; give it its own provider or leave it unmatched.
|
|
139
|
+
|
|
140
|
+
## Mobile crop
|
|
141
|
+
|
|
142
|
+
A `Picture` has a `Source` per media query, each with its own `width` and
|
|
143
|
+
`height`, so the ratio can differ. With `fit: "cover"` (the default) the CDN
|
|
144
|
+
crops to that ratio. A common bug: desktop is 700×342 (about 2:1) and mobile
|
|
145
|
+
is 350×350, so the mobile photo is cropped to a square. Decide the intended
|
|
146
|
+
mobile shape by looking at the live mobile render (emulate the device and DPR,
|
|
147
|
+
take a screenshot), then make the `Source` and the uploaded file agree.
|
|
@@ -0,0 +1,122 @@
|
|
|
1
|
+
# Video
|
|
2
|
+
|
|
3
|
+
v8 ships **no `Video` component**. Neither `@decocms/tanstack` nor
|
|
4
|
+
`@decocms/nextjs` has one, and `@decocms/blocks/image` is for images only.
|
|
5
|
+
Render a plain `<video>`.
|
|
6
|
+
|
|
7
|
+
Two layers decide whether a video plays with sound, and they are independent:
|
|
8
|
+
|
|
9
|
+
1. **The file.** Does the served file contain an audio track? For videos on the
|
|
10
|
+
Deco media host, that depends on the URL (below).
|
|
11
|
+
2. **The player.** Is the `<video>` muted, and does it autoplay? That is HTML
|
|
12
|
+
attributes and browser policy.
|
|
13
|
+
|
|
14
|
+
## The media host strips audio by default
|
|
15
|
+
|
|
16
|
+
Videos uploaded to Deco and served from `decoims.com` come without the audio
|
|
17
|
+
track unless the URL asks for it. This is behavior of the media host, not of the
|
|
18
|
+
v8 packages, so verify it on your URL (below).
|
|
19
|
+
|
|
20
|
+
| URL | Audio track | Size in one measured case |
|
|
21
|
+
|---|---|---|
|
|
22
|
+
| `…/video.mp4` | removed | 3.08 MB |
|
|
23
|
+
| `…/video.mp4?muted=true` | removed | 3.08 MB |
|
|
24
|
+
| `…/video.mp4?muted=false` | present | 3.59 MB |
|
|
25
|
+
|
|
26
|
+
The silent version is a different, smaller file. No player setting brings sound
|
|
27
|
+
back to it. Each variant is cached under its own URL, so switching to
|
|
28
|
+
`?muted=false` fetches a separate file with no cache-busting needed.
|
|
29
|
+
|
|
30
|
+
Verify with two requests and compare sizes:
|
|
31
|
+
|
|
32
|
+
```bash
|
|
33
|
+
curl -sI "<video url>" | grep -i content-length
|
|
34
|
+
curl -sI "<video url>?muted=false" | grep -i content-length
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
The `?muted=false` response should be larger.
|
|
38
|
+
|
|
39
|
+
## Do not send video through `ImageUrl`
|
|
40
|
+
|
|
41
|
+
`decoCdn` builds `https://<domain>/image?…&src=<path>` and keeps only the part
|
|
42
|
+
of `src` before `?`. A video passed to `Image`, `useImageUrl()` or the next/image
|
|
43
|
+
loader becomes an image request and loses `?muted=false`. Use the stored URL
|
|
44
|
+
as is.
|
|
45
|
+
|
|
46
|
+
## Browser autoplay
|
|
47
|
+
|
|
48
|
+
Browsers block autoplay with sound in most cases; muted video autoplays. To
|
|
49
|
+
play with sound, plan for a user action (a click on `controls` or your own
|
|
50
|
+
button). This is browser policy; no URL or attribute changes it.
|
|
51
|
+
|
|
52
|
+
| Goal | File URL | `<video>` attributes |
|
|
53
|
+
|---|---|---|
|
|
54
|
+
| Silent background loop | default (no param) | `autoPlay muted loop playsInline` |
|
|
55
|
+
| Plays with sound when the user starts it | `?muted=false` | `controls`, no `autoPlay` |
|
|
56
|
+
| Autoplays silently, user can unmute | `?muted=false` | `autoPlay muted loop playsInline` plus a button that sets `video.muted = false` |
|
|
57
|
+
|
|
58
|
+
`playsInline` stops iOS from going fullscreen on play.
|
|
59
|
+
|
|
60
|
+
```tsx
|
|
61
|
+
import type { ImageWidget, VideoWidget } from "@decocms/compat-v7/types/widgets";
|
|
62
|
+
import { useImageUrl } from "@decocms/tanstack/react";
|
|
63
|
+
|
|
64
|
+
interface Props {
|
|
65
|
+
/** @description MP4 or WebM */
|
|
66
|
+
video: VideoWidget;
|
|
67
|
+
poster?: ImageWidget;
|
|
68
|
+
sound?: boolean;
|
|
69
|
+
}
|
|
70
|
+
|
|
71
|
+
function withSound(src: string) {
|
|
72
|
+
if (!/^https?:\/\//.test(src)) return src; // relative paths: leave alone
|
|
73
|
+
const url = new URL(src);
|
|
74
|
+
url.searchParams.set("muted", "false");
|
|
75
|
+
return url.href;
|
|
76
|
+
}
|
|
77
|
+
|
|
78
|
+
export default function HeroVideo({ video, poster, sound }: Props) {
|
|
79
|
+
const imageUrl = useImageUrl();
|
|
80
|
+
return (
|
|
81
|
+
<video
|
|
82
|
+
src={sound ? withSound(video) : video}
|
|
83
|
+
poster={poster ? imageUrl(poster, { width: 1280, height: 720 }) : undefined}
|
|
84
|
+
width={1280}
|
|
85
|
+
height={720}
|
|
86
|
+
autoPlay
|
|
87
|
+
muted
|
|
88
|
+
loop
|
|
89
|
+
playsInline
|
|
90
|
+
preload="metadata"
|
|
91
|
+
/>
|
|
92
|
+
);
|
|
93
|
+
}
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
Notes on the example:
|
|
97
|
+
|
|
98
|
+
- `withSound` only makes sense for media-host URLs. Other hosts may ignore or
|
|
99
|
+
reject the parameter.
|
|
100
|
+
- The poster is an image, so it does go through `ImageUrl`.
|
|
101
|
+
- `width` and `height` reserve the box, as with images.
|
|
102
|
+
- `preload="metadata"` avoids downloading the whole file before play. For a
|
|
103
|
+
hero video that is the LCP element, consider the poster as the LCP image and
|
|
104
|
+
preload that instead.
|
|
105
|
+
|
|
106
|
+
## Video fields
|
|
107
|
+
|
|
108
|
+
`VideoWidget` (from `@decocms/compat-v7/types/widgets`) or `@format video-uri`
|
|
109
|
+
on a string gives the field a video picker. `deco check` accepts any string
|
|
110
|
+
there, so it will not catch a broken video URL.
|
|
111
|
+
|
|
112
|
+
## "The video has no sound"
|
|
113
|
+
|
|
114
|
+
1. **Check the URL.** If it is a media-host URL without `?muted=false`, the
|
|
115
|
+
served file has no audio. Add the parameter.
|
|
116
|
+
2. **Check the player.** If the URL has `?muted=false` and it is still silent,
|
|
117
|
+
the element is `muted` (required for autoplay). Add `controls` or an unmute
|
|
118
|
+
button.
|
|
119
|
+
3. **Check the code path.** If the rendered `src` is an `/image?…` URL, the
|
|
120
|
+
video went through `ImageUrl`. Render the stored URL directly.
|
|
121
|
+
4. **Verify** by opening the `?muted=false` URL in a tab: it should play with
|
|
122
|
+
sound.
|
|
@@ -0,0 +1,94 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: deco-make-editable
|
|
3
|
+
description: "@decocms/blocks 8: turn a hardcoded site, or a Figma design, into blocks that people edit in deco Studio, without changing how the site looks. Covers the inventory of content vs interface, the three content shapes (global blocks read by name, composed pages of type page, collections read with client.list), the foo/fooPt bilingual field convention, seeding .deco/blocks from the existing code and sending it with deco push --draft and deco check --draft, implementing sections from a Figma file with the Figma MCP tools, pixel-parity checks with Playwright, accessibility and functional checks, and working in small PRs. Load it when asked to make a site, page, menu, footer or landing editable in Studio, to move hardcoded text into the CMS, to handle two languages in CMS content, or to build a Figma design as editable sections on a v8 site."
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Make a site editable in Studio
|
|
7
|
+
|
|
8
|
+
The goal is not "move strings into JSON". It is two things at once:
|
|
9
|
+
|
|
10
|
+
1. Someone who is not a developer opens Studio, changes a text, a link or the
|
|
11
|
+
order of sections, publishes, and the site changes.
|
|
12
|
+
2. The site renders exactly as it did before the conversion.
|
|
13
|
+
|
|
14
|
+
Every step serves one of those two halves. The same method works when the
|
|
15
|
+
starting point is a Figma file instead of a hardcoded site: build the sections
|
|
16
|
+
from the design, then seed them with the design's content.
|
|
17
|
+
|
|
18
|
+
This skill is about method. For the v8 mechanics it relies on, load the skill
|
|
19
|
+
that owns them:
|
|
20
|
+
|
|
21
|
+
- `deco-site-authoring`: writing sections, pages and loaders.
|
|
22
|
+
- `deco-cms-schema`: how a `Props` type becomes the Studio form (JSDoc tags,
|
|
23
|
+
widgets, shapes that break the form).
|
|
24
|
+
- `deco-site-workflow`: the `deco` CLI, where content lives, drafts and
|
|
25
|
+
publishing, and what to check when Studio cannot see the site.
|
|
26
|
+
- `deco-tanstack-site` or `deco-nextjs-site`: the routes and the worker.
|
|
27
|
+
|
|
28
|
+
## When to load what
|
|
29
|
+
|
|
30
|
+
| Reference | Load it when |
|
|
31
|
+
|---|---|
|
|
32
|
+
| [`references/inventory.md`](./references/inventory.md) | Starting: deciding what goes to the CMS, what stays in code, and the order of PRs |
|
|
33
|
+
| [`references/content-shapes.md`](./references/content-shapes.md) | Choosing between a global block, a composed page and a collection, and wiring each one |
|
|
34
|
+
| [`references/i18n-fields.md`](./references/i18n-fields.md) | The site has two languages and the content must be edited in both |
|
|
35
|
+
| [`references/seeding-content.md`](./references/seeding-content.md) | Writing the first `.deco/blocks` files from the current code, sending them as a draft, and the order of publish and deploy |
|
|
36
|
+
| [`references/from-figma.md`](./references/from-figma.md) | The starting point is a Figma file: mapping frames to sections, tokens, assets |
|
|
37
|
+
| [`references/pixel-parity.md`](./references/pixel-parity.md) | Proving a PR changes nothing visible: HTML diff, screenshot diff, Figma comparison, live edit |
|
|
38
|
+
| [`references/a11y-and-e2e.md`](./references/a11y-and-e2e.md) | Before calling a section or a page done: accessibility and functional checks |
|
|
39
|
+
|
|
40
|
+
## The loop, per content area
|
|
41
|
+
|
|
42
|
+
Work in small PRs, one content area at a time (menu, then home, then
|
|
43
|
+
landings). Each PR goes through the same loop:
|
|
44
|
+
|
|
45
|
+
1. **Inventory** the area: which texts, links and lists are content.
|
|
46
|
+
2. **Shape** each piece: global block, composed page or collection.
|
|
47
|
+
3. **Type** the props and add the block to the block map (`.deco/index.ts`, or
|
|
48
|
+
`.deco/index.tsx` when it holds JSX). Run `deco schema`.
|
|
49
|
+
4. **Seed** `.deco/blocks` from the current code, never by retyping.
|
|
50
|
+
5. **Check** with `deco check` (content in git, no `DECO_SITE`) or
|
|
51
|
+
`deco push --draft=<name>` then `deco check --draft=<name>` (a hosted site).
|
|
52
|
+
6. **Prove parity**: the page on the branch and on `main` render the same
|
|
53
|
+
HTML and the same pixels, at desktop and mobile widths, in every language.
|
|
54
|
+
7. **Live edit**: change the content and see the change land on the right
|
|
55
|
+
page and language only.
|
|
56
|
+
|
|
57
|
+
A PR that is not pixel-identical to `main` does not merge. That rule is what
|
|
58
|
+
lets a conversion run for weeks without anyone noticing it on the live site.
|
|
59
|
+
|
|
60
|
+
## v8 facts this skill relies on
|
|
61
|
+
|
|
62
|
+
These are true of the packages in this repo and change how the v7 version of
|
|
63
|
+
this method worked.
|
|
64
|
+
|
|
65
|
+
- **Studio lists only what the block map lists.** A block type exists because
|
|
66
|
+
`.deco/index.ts` exports a function under that key. Components that are not
|
|
67
|
+
in the map never show up in Studio's section picker, so there is no folder
|
|
68
|
+
to keep clean.
|
|
69
|
+
- **The form comes from the function's input type.** `deco schema` reads the
|
|
70
|
+
first parameter's type of each function in the map and writes
|
|
71
|
+
`.deco/schema.gen.json`. A function that returns JSX or a
|
|
72
|
+
`{ component, props }` descriptor is a section; one that returns its own
|
|
73
|
+
input is content (grouped with pages when the type extends `Route`).
|
|
74
|
+
- **Block functions get only their saved input.** `currentClient()` inside one
|
|
75
|
+
knows the visitor and the version, not the URL. Anything that depends on the
|
|
76
|
+
path (such as the language) is added by the site's code that renders the
|
|
77
|
+
result, not by the block function.
|
|
78
|
+
- **Results are read-only.** A client runs each block function once per
|
|
79
|
+
distinct input and hands the same object to every place that uses it. Copy
|
|
80
|
+
before you change a result (the `localize` helper in
|
|
81
|
+
[i18n-fields.md](./references/i18n-fields.md) builds a new object).
|
|
82
|
+
- **There is no locale in the CMS.** Two languages are a site convention (see
|
|
83
|
+
[i18n-fields.md](./references/i18n-fields.md)).
|
|
84
|
+
- **The CLI has no asset upload command.** How images get to the site is
|
|
85
|
+
covered in `deco-images-media`.
|
|
86
|
+
|
|
87
|
+
## Rules for this skill
|
|
88
|
+
|
|
89
|
+
- Never retype content. Extract it from the code with a script.
|
|
90
|
+
- No fallback copy of the content in code. A constant fallback becomes a
|
|
91
|
+
second source of truth that drifts from what editors see.
|
|
92
|
+
- Do not publish a draft (`deco publish`) without the site owner's explicit
|
|
93
|
+
OK for that publish.
|
|
94
|
+
- Anything specific to one store goes in that store's own notes, not here.
|