@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,93 @@
|
|
|
1
|
+
# Where content lives
|
|
2
|
+
|
|
3
|
+
## The `.deco/` folder
|
|
4
|
+
|
|
5
|
+
Every `deco` command finds the folder that contains `.deco/` by walking up from the current folder,
|
|
6
|
+
or takes `--root <dir>`. That folder is the **root**: the CLI also reads `.env`, `.dev.vars` and
|
|
7
|
+
`wrangler.*` there.
|
|
8
|
+
|
|
9
|
+
| Path | Written by | In git? | What it is |
|
|
10
|
+
|---|---|---|---|
|
|
11
|
+
| `.deco/index.ts` (or `.tsx`) | you | yes | The block map: `export default { hero, … } satisfies Blocks`. Each key is a block type. |
|
|
12
|
+
| `.deco/schema.gen.json` | `deco schema` | yes | Forms and validation, from the block map's types. Declares `"blocksMajor": 8`. |
|
|
13
|
+
| `.deco/blocks/*.json` | `deco pull`, you | hosted site: no. Bundled site: yes | Saved blocks, one file per block. |
|
|
14
|
+
| `.deco/pull.json` | `deco pull`, `deco push` | no | What was pulled: per block, its hash and the draft precondition. The base of `deco diff` and `deco push`. |
|
|
15
|
+
| `.deco/blocks.gen.ts` | `deco content` | no (generate it in `predev`/`prebuild`) | The content module, only for content without a site. |
|
|
16
|
+
|
|
17
|
+
A **hosted** site (`createCMS({ blocks, site })`) reads content from the CDN, so `.deco/blocks` is a
|
|
18
|
+
working copy that `deco pull` fills. A **bundled** site (`createCMS({ blocks, content })`, as in the
|
|
19
|
+
repo's examples and in a site still moving off v7) commits `.deco/blocks`, turns it into
|
|
20
|
+
`.deco/blocks.gen.ts` with `deco content`, and needs a deploy for every content change. Moving from
|
|
21
|
+
bundled to hosted: [serve-and-studio.md](./serve-and-studio.md), Steps 1 and 3.
|
|
22
|
+
|
|
23
|
+
## Block names and files
|
|
24
|
+
|
|
25
|
+
A saved block's **name** is its file name, decoded: `encodeURIComponent(name) + ".json"`, directly in
|
|
26
|
+
`.deco/blocks/`. Studio, the CLI and the runtime share this one rule (`@decocms/blocks/protocol/keys`).
|
|
27
|
+
|
|
28
|
+
- No subfolders. A file in a subfolder is reported: `subfolders of .deco/blocks aren't read`.
|
|
29
|
+
- The file holds one JSON object, written as `JSON.stringify(block, null, 2)` plus a newline.
|
|
30
|
+
- A name can't be empty, contain `..`, a backslash or NUL, start with `.`, be `__proto__`, be a
|
|
31
|
+
Windows device name (`con`, `nul`, `com1`…), end in a source extension (`.ts`, `.tsx`, `.js`…), or
|
|
32
|
+
encode to more than 250 bytes.
|
|
33
|
+
- Two files that decode to the same name: one wins (the one with a `path`, then the one that took
|
|
34
|
+
more decoding, then the lowest file name). The others are reported as
|
|
35
|
+
`another spelling of "<name>"; <file> wins`. Delete the losers.
|
|
36
|
+
- A name of a built-in block (below) can't be a saved block.
|
|
37
|
+
|
|
38
|
+
## Inside a block
|
|
39
|
+
|
|
40
|
+
Every block is an object with `__resolveType`. The rest are its props.
|
|
41
|
+
|
|
42
|
+
```json
|
|
43
|
+
{
|
|
44
|
+
"__resolveType": "page",
|
|
45
|
+
"name": "About",
|
|
46
|
+
"path": "/about",
|
|
47
|
+
"sections": [
|
|
48
|
+
{ "__resolveType": "Header" },
|
|
49
|
+
{ "__resolveType": "hero", "title": "Who we are" },
|
|
50
|
+
{ "__resolveType": "Footer" }
|
|
51
|
+
]
|
|
52
|
+
}
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
`__resolveType` is one of:
|
|
56
|
+
|
|
57
|
+
- **a block type**: a key of the block map (`hero`);
|
|
58
|
+
- **a built-in**: `lazy`, `multivariate`, `always`, `never`, `experiment`, `campaign`, `page`,
|
|
59
|
+
`redirect`, `redirects`, `cms-settings`, `split-traffic`, `calendar`;
|
|
60
|
+
- **a legacy alias**: a v7 type name the runtime maps to a v8 one (see `deco-v7-to-v8-migration`);
|
|
61
|
+
- **a saved block's name**: a **reference**. `{ "__resolveType": "Header" }` uses the saved block
|
|
62
|
+
`Header`. Other keys next to it override the saved props for this use only. This is how a header or
|
|
63
|
+
footer is shared by every page: change the saved block once.
|
|
64
|
+
|
|
65
|
+
`deco check` reports a `__resolveType` that is none of these as `no saved block or block type "<name>"`.
|
|
66
|
+
This is usually a deleted block that something still references.
|
|
67
|
+
|
|
68
|
+
## Blocks with a fixed role
|
|
69
|
+
|
|
70
|
+
| Saved block | Type | Role |
|
|
71
|
+
|---|---|---|
|
|
72
|
+
| any name, with `path` | `page` | A routed page: `name`, `path`, `sections`, optional `seo` |
|
|
73
|
+
| `Redirects` (by convention) | `redirects` | The site's one list of redirect rules. Only one `redirects` block is routed: the first by name |
|
|
74
|
+
| `CMS` | `cms-settings` | CMS settings (telemetry, analytics). Studio edits it. Its body is inline in the release index |
|
|
75
|
+
| `experiments` | `split-traffic` | A/B tests. Every `experiment` rule reads it |
|
|
76
|
+
| `campaigns` | `calendar` | Scheduled campaigns. Every `campaign` rule reads it |
|
|
77
|
+
|
|
78
|
+
Variants (`multivariate`), rules, tests and campaigns are the `deco-variants` skill. `lazy` and
|
|
79
|
+
`Lazy<T>` fields are in `deco-site-authoring`. Two page paths, or two redirect `from`s, that match the
|
|
80
|
+
same URLs are a `deco check` error.
|
|
81
|
+
|
|
82
|
+
## On the CDN
|
|
83
|
+
|
|
84
|
+
What `deco publish` creates, under `https://delivery.decocms.com/sites/<site>/`:
|
|
85
|
+
|
|
86
|
+
- `blocks/<hash>.json`: a block body, stored once by content hash and never changed.
|
|
87
|
+
- `revisions/<id>/index.json`: a release. It maps each name to its hash, plus `type`, `path` and
|
|
88
|
+
`refs` (the names it references), so routing and the reference walk need no body.
|
|
89
|
+
- `latest.json`: a copy of the current release's index, plus `previewHosts`.
|
|
90
|
+
- `drafts/<slug>/…`: a draft's `index.json` (the names it holds) and one file per changed block.
|
|
91
|
+
|
|
92
|
+
Revision ids look like `<12 hex>-<uuidv7>`. `deco releases` lists them. How the site reads all this:
|
|
93
|
+
[delivery.md](./delivery.md).
|
|
@@ -0,0 +1,146 @@
|
|
|
1
|
+
# Edit content from the terminal
|
|
2
|
+
|
|
3
|
+
The remote commands move content between `.deco/blocks` and Studio's hosted CMS for the site named by
|
|
4
|
+
`DECO_SITE`. Reads of published content and drafts go to the public CDN. Writes go through the Studio
|
|
5
|
+
API with your token. Nothing retries on its own, and nothing goes live except `deco publish`.
|
|
6
|
+
|
|
7
|
+
Token and site setup: [schema.md](./schema.md), Steps 2 and 3.
|
|
8
|
+
|
|
9
|
+
## The edit loop
|
|
10
|
+
|
|
11
|
+
```bash
|
|
12
|
+
deco pull # or: deco pull --draft=summer-sale
|
|
13
|
+
# edit .deco/blocks/*.json (or add files)
|
|
14
|
+
deco diff # what you changed since the pull
|
|
15
|
+
deco push --draft=summer-sale # one save; prints "preview: <link>"
|
|
16
|
+
deco check --draft=summer-sale # the whole draft against the code
|
|
17
|
+
# open the preview link and look at the pages
|
|
18
|
+
deco publish --draft=summer-sale --message="Summer sale banners"
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
Adding a page, as an example: pull, copy an existing page's file (it already references the shared
|
|
22
|
+
`Header` and `Footer` blocks), give the copy a new file name, `name` and `path`, change its
|
|
23
|
+
`sections`, then diff, push, check and preview. Use a block type that is in the deployed code, or
|
|
24
|
+
`deco check` fails and Studio has no form for it. What a page's props mean is `deco-site-authoring`.
|
|
25
|
+
|
|
26
|
+
## pull
|
|
27
|
+
|
|
28
|
+
`deco pull [--draft=<name>] [--force]`
|
|
29
|
+
|
|
30
|
+
- Without `--draft`: writes production (the live release) into `.deco/blocks`. With it: production
|
|
31
|
+
with that draft's changes on top.
|
|
32
|
+
- Makes the folder hold exactly that content: it writes each block and **removes every other block
|
|
33
|
+
file**.
|
|
34
|
+
- Writes `.deco/pull.json`: per block, its hash and its version in the draft.
|
|
35
|
+
- Refuses when the folder has changes not pushed:
|
|
36
|
+
`.deco/blocks has 3 changes not pushed (A, B, C); push them, or pull with --force to overwrite them`
|
|
37
|
+
(exit 1). `--force` overwrites them.
|
|
38
|
+
- Prints `pulled 42 blocks from production (revision <id>)` or `… from draft <name> (over revision <id>)`.
|
|
39
|
+
|
|
40
|
+
## diff
|
|
41
|
+
|
|
42
|
+
`deco diff [--draft=<name>]`
|
|
43
|
+
|
|
44
|
+
- Without `--draft`: what `.deco/blocks` changes against `.deco/pull.json`, shown against what was
|
|
45
|
+
pulled (or, after a draft pull, against that draft **as it is now**, which the label says).
|
|
46
|
+
`nothing pulled yet: run deco pull` (exit 1) when there is no `pull.json`.
|
|
47
|
+
- With `--draft`: the folder against that draft as it is now, ignoring `pull.json`.
|
|
48
|
+
- One line per block: `M` changed, `A` new, `D` deleted, each with a field diff. Then
|
|
49
|
+
`3 changes against …` or `no changes against …`.
|
|
50
|
+
|
|
51
|
+
## push
|
|
52
|
+
|
|
53
|
+
`deco push --draft=<name> [--ours | --theirs] [--prune]`
|
|
54
|
+
|
|
55
|
+
- Creates the draft if it doesn't exist (`created draft <name>`).
|
|
56
|
+
- Sends only blocks changed since the pull. A block that already equals what the draft shows is
|
|
57
|
+
skipped. With no `pull.json`, every file is new.
|
|
58
|
+
- **Deletes are sent only with `--prune`.** Without it the push names what it skipped:
|
|
59
|
+
`not sent: 1 deleted block (Old); push with --prune to send deletes`.
|
|
60
|
+
- Each block carries a precondition: its version in the draft when you pulled. If someone changed
|
|
61
|
+
it since, nothing of the save is written and the push **exits 2**:
|
|
62
|
+
|
|
63
|
+
```text
|
|
64
|
+
conflict: Home: changed by <user> at <time>; theirs (-) against yours (+)
|
|
65
|
+
1 block changed in draft summer-sale while you pushed; nothing of this save was written. Pull again, or push with --ours (keep yours) or --theirs (take theirs)
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
- `--ours`: send yours again over theirs.
|
|
69
|
+
- `--theirs`: write their version into `.deco/blocks` for the conflicting blocks and send the rest.
|
|
70
|
+
- `--ours` and `--theirs` together is a usage error (64).
|
|
71
|
+
- Pushing to a draft other than the one you pulled drops the preconditions: a name that draft already
|
|
72
|
+
changed comes back as a conflict.
|
|
73
|
+
- One push is one save. It must fit **500 blocks and 8 MiB**, and each block **1 MiB**. Otherwise
|
|
74
|
+
nothing is sent: `the 812 changed blocks don't fit one save (…); push fewer at a time`, or
|
|
75
|
+
`block "<name>" is larger than a save can carry (1048576 bytes a block)`. To push a large folder,
|
|
76
|
+
move part of the files out, push, move them back, push again: blocks already pushed are recorded in
|
|
77
|
+
`pull.json` and skipped.
|
|
78
|
+
- Busy Studio (exit 5): `Studio is busy (…); 120 blocks saved, the rest not, run deco push again`.
|
|
79
|
+
Run it again; what landed is recorded.
|
|
80
|
+
- A file that isn't a valid block stops the push before anything is sent (exit 1), for example
|
|
81
|
+
`.deco/blocks/Home.json: invalid JSON: …`.
|
|
82
|
+
- Prints `pushed 3 blocks to draft summer-sale` and `preview: <link>`.
|
|
83
|
+
|
|
84
|
+
`deco push` does not run `deco check`. Run `deco check --draft=<name>` after it.
|
|
85
|
+
|
|
86
|
+
## drafts
|
|
87
|
+
|
|
88
|
+
| Command | Does |
|
|
89
|
+
|---|---|
|
|
90
|
+
| `deco drafts list` | Each draft: name, who created it, via what, when (`no drafts` when none) |
|
|
91
|
+
| `deco drafts new <name>` | Creates it (`draft <name> already exists` if it does) and prints its preview link, when Studio has one |
|
|
92
|
+
| `deco drafts discard <name>` | Deletes the draft and its changes |
|
|
93
|
+
| `deco drafts url <name>` | Prints the preview URL; or the pointer, to open as `?__draft=<pointer>` on the site; or `draft <name> has no object yet: push to it first` |
|
|
94
|
+
|
|
95
|
+
Draft names: letters, digits and `/ . _ -` after the first character, at most 255. Anything else is
|
|
96
|
+
exit 64: `"<value>" isn't a draft name: …`.
|
|
97
|
+
|
|
98
|
+
## publish
|
|
99
|
+
|
|
100
|
+
`deco publish --draft=<name> [--message=<text>]`
|
|
101
|
+
|
|
102
|
+
- Prints what the draft changes against production (same `M`/`A`/`D` view), then publishes.
|
|
103
|
+
- `published revision <id>; it is live`. The site follows within about a minute
|
|
104
|
+
([delivery.md](./delivery.md)). No deploy.
|
|
105
|
+
- `nothing to publish: production already has every block of draft <name>` when there is nothing.
|
|
106
|
+
- A draft saved during the publish is not emptied, and the CLI warns:
|
|
107
|
+
`draft <name> was saved during the publish, so it wasn't emptied: it still holds its blocks`.
|
|
108
|
+
- Exit 5 when production moved during the publish (Studio's `production_moved`): run it again.
|
|
109
|
+
- It does not run `deco check`. Run `deco check --draft=<name>` first.
|
|
110
|
+
|
|
111
|
+
## releases and rollback
|
|
112
|
+
|
|
113
|
+
`deco releases [--cursor=<cursor>]` lists published revisions, newest first, 50 a page:
|
|
114
|
+
|
|
115
|
+
```text
|
|
116
|
+
<id> current 2026-11-06T21:10:38Z <author> via <via> draft summer-sale "Summer sale banners"
|
|
117
|
+
<id> 2026-11-05T… <author> via <via> rollback to <id>
|
|
118
|
+
<id> unreadable (its meta.json couldn't be read)
|
|
119
|
+
more: deco releases --cursor=<cursor>
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
`current` marks the revision `latest.json` names.
|
|
123
|
+
|
|
124
|
+
There is no rollback command in the CLI; rollbacks are made in Studio. A rollback publishes a new
|
|
125
|
+
revision that re-applies an old one, and `deco releases` shows it as `rollback to <id>`. Before you roll back,
|
|
126
|
+
check that the old content still fits the code that is deployed now:
|
|
127
|
+
|
|
128
|
+
```bash
|
|
129
|
+
deco check --revision=<id>
|
|
130
|
+
```
|
|
131
|
+
|
|
132
|
+
A rollback to content that uses a block type the code no longer has breaks those pages. Fix forward
|
|
133
|
+
with a draft instead in that case.
|
|
134
|
+
|
|
135
|
+
## Errors worth recognizing
|
|
136
|
+
|
|
137
|
+
| Message | Exit | Meaning |
|
|
138
|
+
|---|---|---|
|
|
139
|
+
| `no Studio site: set DECO_SITE …` | 64 | No `DECO_SITE` anywhere ([schema.md](./schema.md)) |
|
|
140
|
+
| `no .deco/ found from <dir>; run inside your app or pass --root` | 64 | Wrong folder |
|
|
141
|
+
| `deco push needs --draft=<name>` | 64 | `push` and `publish` always need a draft |
|
|
142
|
+
| `not logged in to …; run: npx decocms auth login --target=…` | 3 | No token |
|
|
143
|
+
| `Studio answered <status>: <message>` | 1, 3, 4 or 5 | Studio's own error, mapped to an exit code ([cli-reference.md](./cli-reference.md)) |
|
|
144
|
+
| `the CDN has no revision <id>` | 1 | `pull.json` names a revision the CDN doesn't have: pull again |
|
|
145
|
+
| `.deco/pull.json isn't one deco pull wrote; run deco pull` | 1 | Corrupt or hand-edited `pull.json` |
|
|
146
|
+
| `Studio refused the save: …` | 1 or 3 | Studio rejected the content or the token |
|
|
@@ -0,0 +1,51 @@
|
|
|
1
|
+
# How published content reaches the site
|
|
2
|
+
|
|
3
|
+
With `createCMS({ blocks, site })`, content is never in the bundle. The site reads it at runtime from
|
|
4
|
+
`https://delivery.decocms.com/sites/<site>/`, over plain HTTP with no credential. The CDN layout is in
|
|
5
|
+
[content-layout.md](./content-layout.md#on-the-cdn).
|
|
6
|
+
|
|
7
|
+
## The release index
|
|
8
|
+
|
|
9
|
+
- The first request loads `latest.json`, the current release's index. Requests that arrive meanwhile
|
|
10
|
+
share that one load. Each fetch has 10 s.
|
|
11
|
+
- If that first load fails, a 404 included (the site was never published), clients answer
|
|
12
|
+
`LOADER_FAILED` with a `ContentUnavailableError` cause. There is no bundled fallback and never an
|
|
13
|
+
empty site. A failed load isn't kept: the next request tries again.
|
|
14
|
+
- After that, the CMS checks for a new release in the background every `interval` (default and
|
|
15
|
+
minimum 60 000 ms, plus or minus up to 10 s). A request starts the check and never waits for it. The
|
|
16
|
+
check sends `If-None-Match`, so an unchanged index is a 304.
|
|
17
|
+
- A read is adopted only if its `sequence` is higher than the one held, so a stale CDN answer never
|
|
18
|
+
moves the site backwards. A failed check keeps the last good index.
|
|
19
|
+
|
|
20
|
+
So a publish shows on a given isolate within about 70 s, without a deploy.
|
|
21
|
+
|
|
22
|
+
## Blocks
|
|
23
|
+
|
|
24
|
+
- A request walks the routes and references in the index, then fetches the bodies it needs by hash
|
|
25
|
+
(`blocks/<hash>.json`) in one parallel wave. A body never changes, so it is cached per isolate in an
|
|
26
|
+
LRU of 32 MiB of JSON. Concurrent requests share one fetch per hash.
|
|
27
|
+
- Each request pins the index it started with.
|
|
28
|
+
- Right after a publish, a page whose new blocks aren't cached yet is served from the previous index
|
|
29
|
+
while they load in the background. The next request gets the new content.
|
|
30
|
+
- An index or a body over 16 MiB is refused.
|
|
31
|
+
|
|
32
|
+
## Drafts and old releases
|
|
33
|
+
|
|
34
|
+
- A draft request (`?__draft=…` or the draft cookie) always revalidates at the CDN and never shares the
|
|
35
|
+
isolate's cached copy. It checks for the latest release once, so a preview shows a release published
|
|
36
|
+
a moment ago.
|
|
37
|
+
- A link with a release id in place of a draft (Studio's "Preview this version") reads
|
|
38
|
+
`revisions/<id>/index.json`. The last three such indexes are kept in memory.
|
|
39
|
+
- Previews only open on allowed hosts: see [serve-and-studio.md](./serve-and-studio.md#step-5-previews-in-studio-and-on-your-machine).
|
|
40
|
+
- The TanStack worker never hands a preview to the site's page cache and answers it with
|
|
41
|
+
`Cache-Control: max-age=0, no-cache, must-revalidate`, `Vary: Cookie` and `noindex`.
|
|
42
|
+
|
|
43
|
+
## When a publish doesn't show
|
|
44
|
+
|
|
45
|
+
| Check | Meaning |
|
|
46
|
+
|---|---|
|
|
47
|
+
| `deco releases`: is your revision `current`? | If not, the publish didn't happen or someone published after you |
|
|
48
|
+
| `curl -s https://delivery.decocms.com/sites/<site>/latest.json` and compare `revision` | The CDN has it; the site may not have polled yet. Wait about a minute |
|
|
49
|
+
| The page comes from your page cache | Key the cache on the content revision (`cacheVersion(cms, buildHash, url)` from `@decocms/tanstack/worker`). See `deco-storefront-caching` |
|
|
50
|
+
| The content is read outside the CMS client | Code that imports `.deco/blocks/*.json` directly, or a build script that reads `.deco/blocks`, stays on the last deploy. Read it through the client |
|
|
51
|
+
| The site runs without `site` | A bundled site (`content`) changes only with a deploy |
|
|
@@ -0,0 +1,87 @@
|
|
|
1
|
+
# Deploy: order, CI and secrets
|
|
2
|
+
|
|
3
|
+
Code ships with a deploy. Content ships with a publish. The schema is how Studio learns about the
|
|
4
|
+
code. Each of the three can break the others if they go out in the wrong order.
|
|
5
|
+
|
|
6
|
+
## Variables and secrets
|
|
7
|
+
|
|
8
|
+
| Name | Read by | Secret? | Where it lives |
|
|
9
|
+
|---|---|---|---|
|
|
10
|
+
| `DECO_SITE` | the CLI; your code, to pass `createCMS({ site })` | no | `wrangler.jsonc` `vars` (Workers), `.env`, or CI env. The CLI also reads `.dev.vars` |
|
|
11
|
+
| `DECO_TOKEN` | the CLI only | **yes** | CI secrets, or your shell. Never in the site's runtime env or in git |
|
|
12
|
+
| `DECO_STUDIO_URL` | the CLI only | no | Unset, except for a local or staging Studio |
|
|
13
|
+
| `DECO_STUDIO_ORIGIN` | the bindings, at runtime | no | Unset, except to trust a local Studio's origin |
|
|
14
|
+
| the site token passed as `createCMS({ token })` | your code | **yes** | A runtime secret (for example a Worker secret). Only for hosted telemetry |
|
|
15
|
+
|
|
16
|
+
Commerce keys and other upstream credentials are runtime secrets of the deploy platform, read by code
|
|
17
|
+
and passed as params. Content never holds secrets: `deco check` rejects the old `secret` blocks. On
|
|
18
|
+
deco's own hosting, how env vars and secrets are set is `deco-control-plane-ops` (decocms/skills).
|
|
19
|
+
|
|
20
|
+
`DECO_TOKEN` is a Studio API key. Without it, the CLI runs `npx decocms auth token`, which works on a
|
|
21
|
+
laptop after `npx decocms auth login` but not in CI.
|
|
22
|
+
|
|
23
|
+
## Which commands need what
|
|
24
|
+
|
|
25
|
+
| Command | `DECO_SITE` | Token |
|
|
26
|
+
|---|---|---|
|
|
27
|
+
| `deco schema`, `deco schema --check`, `deco content` | no | no |
|
|
28
|
+
| `deco check` (production) | yes (else it checks local `.deco/blocks`) | no |
|
|
29
|
+
| `deco check --revision` | yes | no |
|
|
30
|
+
| `deco pull`, `deco diff` (production) | yes | no |
|
|
31
|
+
| `deco pull --draft`, `deco diff --draft`, `deco check --draft`, `deco push`, `deco publish`, `deco drafts`, `deco releases`, `deco schema push` | yes | yes |
|
|
32
|
+
|
|
33
|
+
## The production pipeline
|
|
34
|
+
|
|
35
|
+
```text
|
|
36
|
+
pull request: deco schema --check
|
|
37
|
+
production: install -> deco schema --check -> deco check -> deploy -> deco schema push
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
- `deco schema --check` fails when the committed schema doesn't match the code.
|
|
41
|
+
- `deco check` checks the **live content** against the **new code**, before the deploy. It catches a
|
|
42
|
+
removed block type, a renamed field or a newly required field while production still runs the old
|
|
43
|
+
code.
|
|
44
|
+
- `deco schema push` runs **after** the deploy succeeds, so Studio's forms never describe code that
|
|
45
|
+
isn't live, and only on production. A preview deploy that pushes would let editors save content the
|
|
46
|
+
live code can't render.
|
|
47
|
+
|
|
48
|
+
GitHub Actions and other platforms: [schema.md](./schema.md#step-5-push-it-on-every-production-deploy).
|
|
49
|
+
|
|
50
|
+
A content publish from Studio can also break the next deploy's `deco check` (an editor saves something
|
|
51
|
+
the next code rejects). That is the gate working: fix the content in a draft, or the code.
|
|
52
|
+
|
|
53
|
+
## Changes that touch both code and content
|
|
54
|
+
|
|
55
|
+
**Content needs new code** (a new section, a new field):
|
|
56
|
+
|
|
57
|
+
1. Merge and deploy the code. The pipeline pushes the schema.
|
|
58
|
+
2. Edit in Studio, or `deco push --draft=<name>`.
|
|
59
|
+
3. `deco check --draft=<name>`, preview, `deco publish --draft=<name>`.
|
|
60
|
+
|
|
61
|
+
Publishing first would put content in production that the live code can't resolve.
|
|
62
|
+
|
|
63
|
+
**Code removes or narrows something content uses** (delete a block type, rename a field, make a field
|
|
64
|
+
required):
|
|
65
|
+
|
|
66
|
+
1. Publish content that no longer uses it, or that fills the new field.
|
|
67
|
+
2. Deploy the code. The pipeline's `deco check` passes only after step 1.
|
|
68
|
+
|
|
69
|
+
To find what uses a block type, `deco pull` and grep `.deco/blocks` for `"__resolveType": "<type>"`
|
|
70
|
+
and for references to the saved blocks of that type.
|
|
71
|
+
|
|
72
|
+
**First deploy of a hosted site:** publish a first release before the deploy that sets `site`, or
|
|
73
|
+
every page fails with `LOADER_FAILED`. See [serve-and-studio.md](./serve-and-studio.md#step-3-publish-a-first-release-before-you-deploy-with-site).
|
|
74
|
+
|
|
75
|
+
## Rollback
|
|
76
|
+
|
|
77
|
+
- Code: redeploy the previous build. Then run `deco schema && deco schema push` from that commit so
|
|
78
|
+
Studio's forms match it again.
|
|
79
|
+
- Content: the CLI has no rollback command; roll back in Studio. First run `deco check --revision=<id>`
|
|
80
|
+
against the code that is live.
|
|
81
|
+
See [content-sync.md](./content-sync.md#releases-and-rollback).
|
|
82
|
+
|
|
83
|
+
## Page caches
|
|
84
|
+
|
|
85
|
+
A page cache must key on the content revision, or a publish doesn't show until entries expire. The
|
|
86
|
+
TanStack helper `cacheVersion(cms, buildHash, page.url)` gives `<build>.<revision>`. Cache design is
|
|
87
|
+
`deco-storefront-caching`.
|
|
@@ -0,0 +1,173 @@
|
|
|
1
|
+
# Send the schema to Studio
|
|
2
|
+
|
|
3
|
+
Studio draws its editor forms from a schema the site sends. Studio never runs your code. If it has
|
|
4
|
+
no schema for the site, or an old one, its forms are missing or wrong. This page takes a site from
|
|
5
|
+
"Studio asks for the schema" to "every production deploy sends it", with nothing else to read.
|
|
6
|
+
|
|
7
|
+
## What the schema is
|
|
8
|
+
|
|
9
|
+
- `.deco/index.ts` (or `.deco/index.tsx`) default-exports the **block map**: an object of named
|
|
10
|
+
functions. Each function's first parameter type becomes a form.
|
|
11
|
+
- `deco schema` reads that file with the site's own TypeScript and writes `.deco/schema.gen.json`.
|
|
12
|
+
The file declares `"blocksMajor": 8`. Studio treats a site as v8 only from that field.
|
|
13
|
+
- `deco schema push` uploads that file to Studio for the site named by `DECO_SITE`.
|
|
14
|
+
|
|
15
|
+
How a Props type maps to fields (JSDoc tags, widgets, shapes that break a form) is the
|
|
16
|
+
`deco-cms-schema` skill.
|
|
17
|
+
|
|
18
|
+
## Step 1: generate it
|
|
19
|
+
|
|
20
|
+
Requirements: `@decocms/blocks` 8 and `typescript` (a peer dependency) installed in the site.
|
|
21
|
+
|
|
22
|
+
```bash
|
|
23
|
+
npx deco schema
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
On success it prints one line:
|
|
27
|
+
|
|
28
|
+
```text
|
|
29
|
+
wrote .deco/schema.gen.json from index.ts (12 sections, 3 loaders, 0 matchers, 2 pages, 1 content types)
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
(`unchanged` instead of `wrote` when the file was already up to date.) Commit
|
|
33
|
+
`.deco/schema.gen.json`.
|
|
34
|
+
|
|
35
|
+
If the schema has errors, the file is **not written**, so the committed file never holds a half-right
|
|
36
|
+
form. Fix the errors it prints and run it again. Common lines:
|
|
37
|
+
|
|
38
|
+
| Message | Fix |
|
|
39
|
+
|---|---|
|
|
40
|
+
| `no .deco/ found from <dir>; run inside your app or pass --root` | Run from the app folder, or `--root <dir>` |
|
|
41
|
+
| `no .deco/index.ts (or .deco/index.tsx) in <root>; it holds your block map` | Create the block map |
|
|
42
|
+
| `.deco/index.ts: no default export; export your block map as the default` | `export default { … } satisfies Blocks` |
|
|
43
|
+
| `.deco/index.ts: "<key>" isn't a function` | Every value in the map must be a function |
|
|
44
|
+
| `deco schema reads your types with TypeScript, which isn't installed: …` | Add `typescript` to devDependencies |
|
|
45
|
+
| warning `"<key>": its props are typed any, so its form is empty` | Type the first parameter |
|
|
46
|
+
| warning `"<key>": returns any, so it isn't offered for any field` | Type the return value |
|
|
47
|
+
| warning `"<key>": its first parameter isn't an object of props, so its form is empty` | Take one props object |
|
|
48
|
+
| `"<key>": has a "path" field but its type doesn't extend Route (name: string; path: string)` | A `path` field makes a block routable: give its type `name` and `path`, or rename the field |
|
|
49
|
+
|
|
50
|
+
Run `deco schema` before `dev` and `build`, so the file follows the code:
|
|
51
|
+
|
|
52
|
+
```json
|
|
53
|
+
{
|
|
54
|
+
"scripts": {
|
|
55
|
+
"predev": "deco schema",
|
|
56
|
+
"prebuild": "deco schema"
|
|
57
|
+
}
|
|
58
|
+
}
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
`deco schema --watch` regenerates on every `.ts`/`.tsx` change (it skips `node_modules`, `dist`,
|
|
62
|
+
`.git*` and `*.gen.ts`, and also watches files outside the root that the block map imports, such as
|
|
63
|
+
monorepo packages). Stop it with ctrl-c.
|
|
64
|
+
|
|
65
|
+
## Step 2: tell the CLI which site
|
|
66
|
+
|
|
67
|
+
The CLI reads `DECO_SITE`, first match wins:
|
|
68
|
+
|
|
69
|
+
1. the environment;
|
|
70
|
+
2. `.env`, then `.dev.vars`, in the folder that contains `.deco/`;
|
|
71
|
+
3. `vars.DECO_SITE` in `wrangler.jsonc`, `wrangler.json`, then `wrangler.toml` (the `[vars]` table or
|
|
72
|
+
a top-level inline `vars = { … }`), same folder.
|
|
73
|
+
|
|
74
|
+
The value is Studio's site name: letters, digits, `.`, `_`, `-`, starting with a letter or digit.
|
|
75
|
+
Studio finds the organization from the site; the CLI never takes one. A `DECO_SITE` committed in
|
|
76
|
+
`wrangler.jsonc` `vars` (or another file in the list) is found in CI too, with no extra setup.
|
|
77
|
+
|
|
78
|
+
Missing everywhere: exit 64 with
|
|
79
|
+
`no Studio site: set DECO_SITE in the environment, or in <root>'s .env, .dev.vars, or vars.DECO_SITE of wrangler.jsonc, wrangler.json or wrangler.toml (looked in that order)`.
|
|
80
|
+
|
|
81
|
+
## Step 3: a token
|
|
82
|
+
|
|
83
|
+
The CLI sends `Authorization: Bearer <token>` to Studio. It takes the token from:
|
|
84
|
+
|
|
85
|
+
1. `DECO_TOKEN`, when set (use a Studio API key; this is the CI path);
|
|
86
|
+
2. else the output of `npx decocms auth token --target=<DECO_STUDIO_URL>` (Studio CLI's session; the
|
|
87
|
+
CLI has no login of its own). Log in once with `npx decocms auth login --target=https://studio.decocms.com`.
|
|
88
|
+
`deco login` prints that command.
|
|
89
|
+
|
|
90
|
+
No token: exit 3, `not logged in to https://studio.decocms.com; run: npx decocms auth login --target=https://studio.decocms.com`.
|
|
91
|
+
A token Studio rejects: exit 3, `Studio answered 401: … (check DECO_TOKEN, or log in again with npx decocms auth login)`.
|
|
92
|
+
A 403 is also exit 3: Studio refused the token for this site.
|
|
93
|
+
|
|
94
|
+
`DECO_STUDIO_URL` changes the Studio API base (default `https://studio.decocms.com`). Leave it unset
|
|
95
|
+
unless you run a local or staging Studio.
|
|
96
|
+
|
|
97
|
+
## Step 4: push it
|
|
98
|
+
|
|
99
|
+
```bash
|
|
100
|
+
npx deco schema push
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
It reads `.deco/schema.gen.json` as it is on disk (it does not regenerate it) and sends it to Studio.
|
|
104
|
+
Success:
|
|
105
|
+
|
|
106
|
+
```text
|
|
107
|
+
pushed .deco/schema.gen.json (a v8 schema)
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
`(not a v8 schema)` means the file has no `"blocksMajor": 8`: an older generator wrote it. Run
|
|
111
|
+
`deco schema` again, commit, push again.
|
|
112
|
+
|
|
113
|
+
| Message | Exit | Fix |
|
|
114
|
+
|---|---|---|
|
|
115
|
+
| `no .deco/schema.gen.json; run deco schema first` | 1 | Run `deco schema` |
|
|
116
|
+
| `.deco/schema.gen.json: invalid JSON: …` | 1 | Regenerate it |
|
|
117
|
+
| `deco schema push takes no --watch or --check` | 64 | Drop the flag |
|
|
118
|
+
| `Studio (…) unreachable (…)` / `timed out` | 4 | Network; retry |
|
|
119
|
+
|
|
120
|
+
Reload Studio. The forms now follow the pushed schema.
|
|
121
|
+
|
|
122
|
+
## Step 5: push it on every production deploy
|
|
123
|
+
|
|
124
|
+
Studio should describe the code that is live. So push from the job that deploys production, after
|
|
125
|
+
the deploy succeeds, and never from preview branches. In pull requests, check that the committed file
|
|
126
|
+
is current instead.
|
|
127
|
+
|
|
128
|
+
GitHub Actions, as a sketch (adapt the install and deploy steps to the site):
|
|
129
|
+
|
|
130
|
+
```yaml
|
|
131
|
+
# .github/workflows/deploy.yml
|
|
132
|
+
on:
|
|
133
|
+
push:
|
|
134
|
+
branches: [main]
|
|
135
|
+
jobs:
|
|
136
|
+
deploy:
|
|
137
|
+
runs-on: ubuntu-latest
|
|
138
|
+
env:
|
|
139
|
+
DECO_TOKEN: ${{ secrets.DECO_TOKEN }} # a Studio API key
|
|
140
|
+
# DECO_SITE: my-store # only if it isn't in wrangler.* vars or .env
|
|
141
|
+
steps:
|
|
142
|
+
- uses: actions/checkout@v4
|
|
143
|
+
- run: npm ci
|
|
144
|
+
- run: npx deco schema --check # committed file matches the code
|
|
145
|
+
- run: npx deco check # live content fits this code
|
|
146
|
+
- run: npm run deploy # your deploy
|
|
147
|
+
- run: npx deco schema push # Studio's forms follow what just went live
|
|
148
|
+
```
|
|
149
|
+
|
|
150
|
+
```yaml
|
|
151
|
+
# pull requests
|
|
152
|
+
- run: npx deco schema --check
|
|
153
|
+
```
|
|
154
|
+
|
|
155
|
+
`deco schema --check` writes nothing. It exits 1 when the file is missing or stale and prints what
|
|
156
|
+
moved, for example `sections: new in code: hero` or `2 schema definitions changed (fields or
|
|
157
|
+
choices)`, then `Run \`deco schema\` and commit .deco/schema.gen.json.` It exits 0 with
|
|
158
|
+
`.deco/schema.gen.json is up to date with index.ts`.
|
|
159
|
+
|
|
160
|
+
If the deploy runs somewhere else (Cloudflare Workers Builds, a hosting control plane), run
|
|
161
|
+
`deco schema push` in that platform's production deploy command after the deploy, with `DECO_TOKEN`
|
|
162
|
+
as a secret build variable. Where deco's hosting keeps env vars and secrets is in
|
|
163
|
+
`deco-control-plane-ops` (decocms/skills). The ordering with `deco check` and `deco publish` is in
|
|
164
|
+
[deploy.md](./deploy.md).
|
|
165
|
+
|
|
166
|
+
## Checklist
|
|
167
|
+
|
|
168
|
+
- [ ] `typescript` installed; `deco schema` prints `wrote` or `unchanged`
|
|
169
|
+
- [ ] `.deco/schema.gen.json` committed, with `"blocksMajor": 8`
|
|
170
|
+
- [ ] `DECO_SITE` resolvable from the app folder
|
|
171
|
+
- [ ] `deco schema push` prints `(a v8 schema)`
|
|
172
|
+
- [ ] Production deploy job runs `deco schema push` with `DECO_TOKEN` from secrets
|
|
173
|
+
- [ ] Pull requests run `deco schema --check`
|