@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,152 @@
|
|
|
1
|
+
# Render location: server work that is slow, wasted, or in the wrong place
|
|
2
|
+
|
|
3
|
+
Load when: TTFB is seconds while the HTML is small; a page resolves data it never
|
|
4
|
+
renders; you do not know which block is slow; the site carries thousands of redirects.
|
|
5
|
+
|
|
6
|
+
Lighthouse cannot see any of this. It shows up as one TTFB number with no audit
|
|
7
|
+
pointing at it. The browser timeline is clean; the server did the work.
|
|
8
|
+
|
|
9
|
+
## 1. Attribute the wait before you change anything
|
|
10
|
+
|
|
11
|
+
Time every block function for one run. The block map is a plain object of functions,
|
|
12
|
+
so wrap it where you create the CMS (not in `.deco/index.ts`, which `deco schema` reads):
|
|
13
|
+
|
|
14
|
+
```ts
|
|
15
|
+
// src/cms.ts — temporary, for a local or preview run
|
|
16
|
+
import { createCMS, type Blocks } from "@decocms/blocks";
|
|
17
|
+
import blocks from "../.deco";
|
|
18
|
+
|
|
19
|
+
const timed = (map: Blocks): Blocks =>
|
|
20
|
+
Object.fromEntries(
|
|
21
|
+
Object.entries(map).map(([name, fn]) => [
|
|
22
|
+
name,
|
|
23
|
+
async (input: unknown) => {
|
|
24
|
+
const t0 = performance.now();
|
|
25
|
+
try {
|
|
26
|
+
return await fn(input);
|
|
27
|
+
} finally {
|
|
28
|
+
console.log(`[block] ${Math.round(performance.now() - t0)}ms ${name}`);
|
|
29
|
+
}
|
|
30
|
+
},
|
|
31
|
+
]),
|
|
32
|
+
);
|
|
33
|
+
|
|
34
|
+
export const cms = createCMS({ blocks: timed(blocks), site: "my-store" });
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
The wrapper times only the function's own run: the resolver resolves a block's inputs
|
|
38
|
+
before it calls the function, so a nested block logs its own line. A block the client
|
|
39
|
+
already ran for the same inputs in this request logs nothing (it is a memo hit; see
|
|
40
|
+
[`request-dedupe.md`](./request-dedupe.md)). Sort the lines by ms. The ranking matters,
|
|
41
|
+
not the absolute numbers.
|
|
42
|
+
|
|
43
|
+
In production, the same data exists as telemetry spans: when a trace is sampled, every
|
|
44
|
+
block run becomes a span named after its block type, with `deco.block.type`. Sampling
|
|
45
|
+
is off by default. It needs a telemetry destination (a `token` or a `telemetry.endpoint`
|
|
46
|
+
on `createCMS`), the cap `createCMS({ telemetry: { limits: { traceSampleRate } } })`
|
|
47
|
+
(default 0), and `telemetry.traceSampleRate` in the saved `CMS` block (default 0).
|
|
48
|
+
|
|
49
|
+
## 2. A prop resolved eagerly and then thrown away
|
|
50
|
+
|
|
51
|
+
The resolver resolves every `__resolveType` in a block's inputs before it calls the
|
|
52
|
+
function, including branches the section will not render: a 404 fallback, a tab that
|
|
53
|
+
is closed, a modal, the hidden side of a flag.
|
|
54
|
+
|
|
55
|
+
Measured on a v7 product page: the "not found" fallback held a shelf whose products came
|
|
56
|
+
from a full-text search. It cost **1.7 s on every product page**, and the result was
|
|
57
|
+
discarded. v8 resolves inputs the same way, so the same content shape costs the same.
|
|
58
|
+
|
|
59
|
+
The fix in v8 is the built-in `lazy` block. Type the prop as `Lazy<T>` and call it only
|
|
60
|
+
on the branch that renders it:
|
|
61
|
+
|
|
62
|
+
```ts
|
|
63
|
+
import type { Lazy } from "@decocms/blocks";
|
|
64
|
+
|
|
65
|
+
interface Props {
|
|
66
|
+
product: Product | null;
|
|
67
|
+
notFoundShelf: Lazy<Product[]>; // content: { "__resolveType": "lazy", "value": { …the loader… } }
|
|
68
|
+
}
|
|
69
|
+
|
|
70
|
+
export async function productPage({ product, notFoundShelf }: Props) {
|
|
71
|
+
if (product) return { component: "pdp", props: { product } };
|
|
72
|
+
return { component: "not-found", props: { shelf: await notFoundShelf() } };
|
|
73
|
+
}
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
A `Lazy<T>` value resolves when called, at most once, with the same client. `deco schema`
|
|
77
|
+
turns a `Lazy<T>` field into a `lazy` block whose `value` is a `T`. `deco check` then
|
|
78
|
+
rejects content that puts a plain value in that field, and a `lazy` block in a field that
|
|
79
|
+
is not `Lazy<T>`, so the content has to change with the type. See `deco-site-authoring`
|
|
80
|
+
for writing lazy props with Suspense and skeletons.
|
|
81
|
+
|
|
82
|
+
Two more shapes with the same cost:
|
|
83
|
+
|
|
84
|
+
- **Blocks that render nothing** (theme fonts, an SEO section's JSON-LD input) still run
|
|
85
|
+
their data blocks. Type that prop `Lazy<T>` and wrap it in `lazy` in content, so
|
|
86
|
+
nothing is fetched until the function calls it.
|
|
87
|
+
- **Variants.** The built-in `multivariate` resolves rules in order, stops at the first
|
|
88
|
+
true one, and runs only that variant's `value`, which is a `Lazy`. A variant saved
|
|
89
|
+
without the `lazy` wrapper (`deco check` flags it) resolves eagerly when it comes
|
|
90
|
+
before the winner. Run `deco check` on migrated content.
|
|
91
|
+
|
|
92
|
+
## 3. Streamed blocks vs awaited blocks
|
|
93
|
+
|
|
94
|
+
In the example page route, each section block is its own promise, and only the SEO
|
|
95
|
+
block is awaited. TTFB is then routing plus the SEO block, and the slow sections stream
|
|
96
|
+
in afterwards. Check what your site does:
|
|
97
|
+
|
|
98
|
+
| Your route | TTFB is | Use it when |
|
|
99
|
+
|---|---|---|
|
|
100
|
+
| Awaits only routing and SEO | routing plus the SEO block | the default |
|
|
101
|
+
| Awaits every block | the slowest block | blocks read only in-memory content, or response headers depend on how blocks resolved |
|
|
102
|
+
| Awaits one block before starting the others | that block plus the rest | never: start every block first, then await |
|
|
103
|
+
|
|
104
|
+
The SEO block often needs the same product the main section needs. If both name the same
|
|
105
|
+
loader with the same inputs, the client runs it once and both get the result. If they
|
|
106
|
+
differ in one prop (a `count`, an extra facet), it runs twice. See `request-dedupe.md`.
|
|
107
|
+
|
|
108
|
+
Streaming has one trap on TanStack Start: a block promise still pending when the
|
|
109
|
+
document streams can reach the browser without settling, so the section never hydrates.
|
|
110
|
+
The check and the fix are in [`hydration.md`](./hydration.md).
|
|
111
|
+
|
|
112
|
+
## 4. A large Redirects block is paid on every request
|
|
113
|
+
|
|
114
|
+
`createDecoWorker` checks the CMS redirects on every non-asset `GET` or `HEAD` that is not a
|
|
115
|
+
server-function call. The check runs before `routes` and before your `pageCache`, so a
|
|
116
|
+
cache hit pays it too. Each check builds a new client, reads the `redirects` block
|
|
117
|
+
(a fresh copy of its rules), and `matchRoute` compiles the rules into a trie. The trie is
|
|
118
|
+
cached per array, and the array is new for each client. The page route reads the redirects
|
|
119
|
+
again with its own client, so a rendered page pays it twice.
|
|
120
|
+
|
|
121
|
+
Measured on a laptop with Bun, against this repo's `createCMS` and `matchRoute`, per
|
|
122
|
+
client (`redirects()` plus one `matchRoute`):
|
|
123
|
+
|
|
124
|
+
| Rules in the block | Cost per client |
|
|
125
|
+
|---|---|
|
|
126
|
+
| 1,000 | ~3 ms |
|
|
127
|
+
| 5,000 | ~13 ms |
|
|
128
|
+
| 20,000 | ~45 ms |
|
|
129
|
+
| 50,000 | ~120 ms |
|
|
130
|
+
|
|
131
|
+
A Worker isolate is slower than a laptop. If a migration folded a large redirect CSV into
|
|
132
|
+
`Redirects`, keep the editor-managed rules there and move the long tail to a point lookup:
|
|
133
|
+
a Workers KV namespace read by key in your `routes` handler (one `get` per request, never
|
|
134
|
+
`list`). The memory side of this is in [`worker-memory.md`](./worker-memory.md).
|
|
135
|
+
|
|
136
|
+
## 5. Bots get the same HTML as people
|
|
137
|
+
|
|
138
|
+
v8 has no deferred sections, so crawlers and browsers get the same document. Check what
|
|
139
|
+
that document carries for crawlers. One listing page emitted JSON-LD of type `"Products"`,
|
|
140
|
+
which does not exist in schema.org, so no crawler read it. It was **2.75 MB per listing
|
|
141
|
+
page**. A listing's JSON-LD is an `ItemList` of `ListItem` with `url` and `position`; the
|
|
142
|
+
full `Product` belongs on the product page. That change took the block from 2,474,206 to
|
|
143
|
+
6,198 bytes. More in [`payload-trim.md`](./payload-trim.md).
|
|
144
|
+
|
|
145
|
+
## Rules
|
|
146
|
+
|
|
147
|
+
- Small wire plus long wait means server work. Large wire plus short wait means payload.
|
|
148
|
+
- Do not move rendering to the client to win a number. Above-the-fold content and
|
|
149
|
+
anything a crawler must read stays on the server. This file is about work that is
|
|
150
|
+
discarded or repeated.
|
|
151
|
+
- Check one URL two or three times. A swing from 0.2 s to 3.6 s is a cold isolate or a
|
|
152
|
+
cache miss, not the page.
|
|
@@ -0,0 +1,147 @@
|
|
|
1
|
+
# Duplicate upstream calls in one page
|
|
2
|
+
|
|
3
|
+
Load when: the same upstream operation runs several times for one page; two sections
|
|
4
|
+
fetch the same product; you need to count calls before and after a change.
|
|
5
|
+
|
|
6
|
+
On a v7 storefront, removing duplicates cut a product page from 40+ VTEX calls to about 8.
|
|
7
|
+
v8 already removes some duplicates for you. Know which ones before you write code.
|
|
8
|
+
|
|
9
|
+
## What the client dedupes for you
|
|
10
|
+
|
|
11
|
+
A client (`cms.client(...)`, or `contentClient(cms, request)` on TanStack) runs each
|
|
12
|
+
block function **once per distinct input**. The memo key is the function plus its inputs
|
|
13
|
+
in canonical form (key order does not matter). Every other occurrence in the same client
|
|
14
|
+
gets the same promise and the same result object. So a product loader named by the PDP
|
|
15
|
+
section and by the SEO block, with equal props, runs once.
|
|
16
|
+
|
|
17
|
+
It stops working when:
|
|
18
|
+
|
|
19
|
+
| Case | Why | Fix |
|
|
20
|
+
|---|---|---|
|
|
21
|
+
| Inputs differ by one prop (`count: 12` vs `count: 24`, an extra facet) | Different key | Make them equal, or have one block take the larger result and slice |
|
|
22
|
+
| Code calls a client or a helper directly instead of naming a block in content | The memo only sees blocks the resolver runs | Make the shared data a block, or memoize per request (below) |
|
|
23
|
+
| Two clients for one request (one in the page loader, one in another loader or server function) | The memo belongs to one client | Create one client per request and pass it down |
|
|
24
|
+
| Two requests (hover prefetch then click, the page then a server function) | Nothing is shared between requests | An upstream cache: `deco-storefront-caching` |
|
|
25
|
+
| An input holds a value with no canonical form (a function, a class instance) | No key, so no memo | Keep block inputs plain JSON |
|
|
26
|
+
|
|
27
|
+
Results are shared, so they are read-only. Copy before you change one: an in-place edit
|
|
28
|
+
changes every other place that got the same object.
|
|
29
|
+
|
|
30
|
+
## Make equal blocks equal: save the loader once
|
|
31
|
+
|
|
32
|
+
When several sections call the same loader with the same props, save that loader as one
|
|
33
|
+
named block and reference it from each section, instead of repeating the props inline:
|
|
34
|
+
|
|
35
|
+
```jsonc
|
|
36
|
+
// the saved block "Shelf - Best sellers"
|
|
37
|
+
{ "__resolveType": "product-list", "collection": "334", "count": 12 }
|
|
38
|
+
|
|
39
|
+
// in each section that needs it
|
|
40
|
+
"products": { "__resolveType": "Shelf - Best sellers" }
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
A reference resolves to `{ ...saved, ...overrides }`. With no overrides, every reference
|
|
44
|
+
reaches the loader with identical inputs, so the client runs it once. An override in one
|
|
45
|
+
place (a different `count`) makes a second call there, which is what you want.
|
|
46
|
+
|
|
47
|
+
This also stops the copies drifting apart when someone edits one of them in Studio.
|
|
48
|
+
|
|
49
|
+
## Memoize code that is not a block, per request
|
|
50
|
+
|
|
51
|
+
A helper called from several block functions (`getProductBySlug` used by the PDP section
|
|
52
|
+
and the breadcrumb) does not go through the memo. Key a memo on the current client, which
|
|
53
|
+
is one per request:
|
|
54
|
+
|
|
55
|
+
```ts
|
|
56
|
+
// src/perRequest.ts
|
|
57
|
+
import { currentClient, type Client } from "@decocms/blocks";
|
|
58
|
+
|
|
59
|
+
const memos = new WeakMap<Client, Map<string, Promise<unknown>>>();
|
|
60
|
+
|
|
61
|
+
/** Runs `load` once per request for `key`. Call it from inside a block function. */
|
|
62
|
+
export function oncePerRequest<T>(key: string, load: () => Promise<T>): Promise<T> {
|
|
63
|
+
const client = currentClient();
|
|
64
|
+
let memo = memos.get(client);
|
|
65
|
+
if (!memo) memos.set(client, (memo = new Map()));
|
|
66
|
+
let pending = memo.get(key) as Promise<T> | undefined;
|
|
67
|
+
if (!pending) {
|
|
68
|
+
pending = load();
|
|
69
|
+
memo.set(key, pending);
|
|
70
|
+
}
|
|
71
|
+
return pending;
|
|
72
|
+
}
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
`currentClient()` returns the client that is running the block function. It works before
|
|
76
|
+
the function's first `await` everywhere, and across `await` where the runtime has
|
|
77
|
+
`AsyncLocalStorage` (Workers with `nodejs_compat`). Outside a block function it throws.
|
|
78
|
+
The `WeakMap` lets the memo go with the client at the end of the request. Do not use a
|
|
79
|
+
module-level `Map` keyed by URL instead: it is shared by every request in the isolate,
|
|
80
|
+
never expires, and mixes shoppers.
|
|
81
|
+
|
|
82
|
+
Do not memoize shopper-scoped calls (cart, session, anything sent with the shopper's
|
|
83
|
+
cookie) under a key that leaves the cookie out.
|
|
84
|
+
|
|
85
|
+
## Count the calls
|
|
86
|
+
|
|
87
|
+
Do this before and after every change. Three ways, from quickest to most complete.
|
|
88
|
+
|
|
89
|
+
**Dev: log every upstream call.** The thin clients take a `fetch` option. Pass a wrapper:
|
|
90
|
+
|
|
91
|
+
```ts
|
|
92
|
+
// src/clients/vtex.ts
|
|
93
|
+
import { createVtexClient } from "@decocms/apps-vtex";
|
|
94
|
+
|
|
95
|
+
const logged: typeof fetch = async (input, init) => {
|
|
96
|
+
const t0 = performance.now();
|
|
97
|
+
const response = await fetch(input, init);
|
|
98
|
+
const url = new URL(input instanceof Request ? input.url : String(input));
|
|
99
|
+
console.log(`[upstream] ${init?.method ?? "GET"} ${url.pathname} ${response.status} ${Math.round(performance.now() - t0)}ms`);
|
|
100
|
+
return response;
|
|
101
|
+
};
|
|
102
|
+
|
|
103
|
+
export const vtex = createVtexClient({ account: "mystore", fetch: import.meta.env.DEV ? logged : undefined });
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
The option is documented as the fetch underneath, for tests. It sits below the client's
|
|
107
|
+
retry, so a retried call logs one line per attempt. Load one page and sort the lines:
|
|
108
|
+
`sort | uniq -c | sort -rn`. One line per operation is
|
|
109
|
+
the goal. Several lines with the same path is a duplicate; one line per product is an N+1
|
|
110
|
+
([`loaders-n-plus-1.md`](./loaders-n-plus-1.md)). Never log query strings or cookies to a
|
|
111
|
+
shared log.
|
|
112
|
+
|
|
113
|
+
**Production: the client metric.** Every `@decocms/apps-*` client measures each request
|
|
114
|
+
once as `http.client.request.duration`, labelled `provider`, `operation` (for VTEX, a
|
|
115
|
+
stable name such as `intelligent-search.product_search` or `catalog.crossselling.similars`),
|
|
116
|
+
`status_class`, `cached` and `retries`. The worker records `http.server.request.duration`
|
|
117
|
+
with `http.route`. Over the same window, calls of one operation divided by page requests
|
|
118
|
+
of one route is the calls-per-page ratio. It is an estimate when several routes use the
|
|
119
|
+
operation. Both metrics need a telemetry destination on `createCMS` (a `token`, or a
|
|
120
|
+
`telemetry.endpoint`).
|
|
121
|
+
|
|
122
|
+
**Browser: a HAR.** Upstream calls made on the server never appear in the browser. A HAR
|
|
123
|
+
shows the other half: `/_serverFn/` requests (one per client-side navigation or prefetch)
|
|
124
|
+
and calls client components make straight to the commerce API (cart, simulation).
|
|
125
|
+
|
|
126
|
+
```python
|
|
127
|
+
import json, collections, sys
|
|
128
|
+
entries = json.load(open(sys.argv[1]))["log"]["entries"]
|
|
129
|
+
count = collections.Counter(
|
|
130
|
+
e["request"]["url"].split("?")[0] for e in entries
|
|
131
|
+
if "/_serverFn/" in e["request"]["url"] or "/api/" in e["request"]["url"]
|
|
132
|
+
)
|
|
133
|
+
for url, n in count.most_common(20):
|
|
134
|
+
print(f"{n:4}x {url}")
|
|
135
|
+
```
|
|
136
|
+
|
|
137
|
+
Record the HAR with a script (Playwright's `recordHar`) rather than by hand, so the before
|
|
138
|
+
and after runs do the same clicks. Do not wait on `networkidle`; wait for a selector.
|
|
139
|
+
|
|
140
|
+
## Typical duplicates on a VTEX store
|
|
141
|
+
|
|
142
|
+
| Symptom | Usual cause | Fix |
|
|
143
|
+
|---|---|---|
|
|
144
|
+
| Same product search 2-4 times on a PDP | PDP section, related products and breadcrumb each resolve the product | One loader block, referenced by each (above), or `oncePerRequest` |
|
|
145
|
+
| Same cross-selling call twice | Two shelves for the same product and type | Same block, same inputs |
|
|
146
|
+
| Simulation once per card | Per-item call | Batch into one `items` array ([`loaders-n-plus-1.md`](./loaders-n-plus-1.md)) |
|
|
147
|
+
| `/_serverFn/` twice for one click | Hover prefetch with different search params than the click | [`navigation-ux.md`](./navigation-ux.md) |
|
|
@@ -0,0 +1,79 @@
|
|
|
1
|
+
# Reading a Chrome Performance trace, and measuring without fooling yourself
|
|
2
|
+
|
|
3
|
+
Load when: you need to know which element shifted, why the screen went blank for a moment,
|
|
4
|
+
or where a slow navigation spends its time; or your local numbers disagree with production.
|
|
5
|
+
|
|
6
|
+
A trace records which element moved, by how much, and what ran just before. It answers
|
|
7
|
+
questions the console and Lighthouse only hint at.
|
|
8
|
+
|
|
9
|
+
## Record one
|
|
10
|
+
|
|
11
|
+
1. DevTools, **Performance** panel.
|
|
12
|
+
2. Turn on **Screenshots** (to see flashes) and **Web Vitals** (to see layout shifts).
|
|
13
|
+
3. Set CPU and network throttling to match what you are debugging (mobile: 4x CPU, a
|
|
14
|
+
slow 4G profile).
|
|
15
|
+
4. Record, then reproduce: a hard reload for load problems, a click for navigation
|
|
16
|
+
problems. Wait until the page settles (3 to 5 s), then stop.
|
|
17
|
+
|
|
18
|
+
Save it (the export button, a `.json` file) so someone else can load it, or open it in
|
|
19
|
+
Perfetto. Record the same steps before and after a fix.
|
|
20
|
+
|
|
21
|
+
## Layout shifts (CLS)
|
|
22
|
+
|
|
23
|
+
1. In the **Layout shifts** (or Experience) track, each shift is a marker. Click one.
|
|
24
|
+
2. The summary shows its **score**, the **cumulative score**, and the **elements** that
|
|
25
|
+
moved. Click an element to jump to it in the Elements panel.
|
|
26
|
+
3. Look just to the left of the shift on the **Network** and **Main** tracks: a script
|
|
27
|
+
finished, a stylesheet arrived, a font swapped, an image decoded. That is the cause.
|
|
28
|
+
|
|
29
|
+
Fixes are in [`cls-third-party.md`](./cls-third-party.md).
|
|
30
|
+
|
|
31
|
+
## A flash or a blank frame
|
|
32
|
+
|
|
33
|
+
1. In the screenshot strip at the top, find the white or half-painted frame. Note its time.
|
|
34
|
+
2. On the **Main** track at that time, look for React work (`performConcurrentWorkOnRoot`,
|
|
35
|
+
hydration) and for a Suspense fallback commit.
|
|
36
|
+
3. Check the console for a hydration error at the same moment.
|
|
37
|
+
|
|
38
|
+
A fallback during hydration usually means a component loaded with `React.lazy` was not
|
|
39
|
+
ready, or a block promise was still pending. See [`hydration.md`](./hydration.md#3-flashes-and-blank-frames).
|
|
40
|
+
|
|
41
|
+
## A slow navigation
|
|
42
|
+
|
|
43
|
+
1. Record while clicking a card or a menu link.
|
|
44
|
+
2. On the **Network** track, find the `/_serverFn/` request. Its duration is the server's
|
|
45
|
+
share: routing, the page's blocks and the upstream.
|
|
46
|
+
3. After it ends, look on **Main** for long tasks: rendering the new page, effects, a large
|
|
47
|
+
list. That is the browser's share.
|
|
48
|
+
|
|
49
|
+
If the server share dominates, go to [`render-location.md`](./render-location.md) and
|
|
50
|
+
count upstream calls ([`request-dedupe.md`](./request-dedupe.md#count-the-calls)). If two
|
|
51
|
+
`/_serverFn/` requests appear for one click, see [`navigation-ux.md`](./navigation-ux.md).
|
|
52
|
+
|
|
53
|
+
## Measurement traps
|
|
54
|
+
|
|
55
|
+
These produced false conclusions on real storefronts.
|
|
56
|
+
|
|
57
|
+
- **A local preview without compression is for deltas, not absolutes.** One local FCP of
|
|
58
|
+
11.7 s was a dev server sending 573 KB of HTML instead of 62 KB, and 364 KB of CSS
|
|
59
|
+
instead of 57 KB. Compare local against local.
|
|
60
|
+
- **A local build of `main` is not the deployed build.** A stale generated file made a
|
|
61
|
+
local chunk 1,215 kB against the deployed 908 kB: 307 kB of difference that did not exist.
|
|
62
|
+
Run the repo's codegen (`deco schema`, and `deco content` if the site bundles its
|
|
63
|
+
content) before the control build,
|
|
64
|
+
and check that the local asset hashes match the deployed ones.
|
|
65
|
+
- **Warm the cache for the right segment.** When the page cache keys by device, the first
|
|
66
|
+
hit with a mismatched User-Agent measures a cold render for the wrong segment. That
|
|
67
|
+
produced two fake "TTFB regressions" on one site. Warm up with the same UA you measure with.
|
|
68
|
+
- **One run is noise.** Take the median of five runs per side. Lighthouse varies more than
|
|
69
|
+
most fixes move it.
|
|
70
|
+
- **A hydration change needs a control.** Count the nodes that survive hydration and the
|
|
71
|
+
console errors on representative pages, on the base branch and on yours. Without the
|
|
72
|
+
control, 99.7% surviving tells you nothing.
|
|
73
|
+
- **Assert what must be there, not only what you removed.** After a change to the `<head>`
|
|
74
|
+
or the client bundle, check that the served HTML still loads the client entry script.
|
|
75
|
+
One change removed it with zero errors and zero warnings: the page rendered and never
|
|
76
|
+
hydrated.
|
|
77
|
+
- **Escaping is not waste.** Removing `encodeURIComponent` from JSON in an HTML attribute
|
|
78
|
+
to "save bytes" cost 8% more: React escapes `"` as `"` (6 bytes) against `%22`
|
|
79
|
+
(3 bytes), and JSON is mostly quotes.
|
|
@@ -0,0 +1,176 @@
|
|
|
1
|
+
# Worker memory: measure per deploy, keep big data out of the isolate
|
|
2
|
+
|
|
3
|
+
Load when: the Worker logs "exceeded memory limit" (128 MB per isolate); memory P90 grew
|
|
4
|
+
after a deploy; a proxied sitemap, feed or export is large.
|
|
5
|
+
|
|
6
|
+
An isolate pays for everything reachable from module scope, for its whole life, in every
|
|
7
|
+
isolate. That is **resident** memory. A single request that holds a large body in JS is a
|
|
8
|
+
**peak**. They have different fixes, so find out which one you have first.
|
|
9
|
+
|
|
10
|
+
## 1. What v8 keeps in an isolate
|
|
11
|
+
|
|
12
|
+
| Holder | Size | Notes |
|
|
13
|
+
|---|---|---|
|
|
14
|
+
| Content, with `createCMS({ site })` | The release index (`latest.json`, at most 16 MiB) and the previous one; block bodies in an LRU bounded at 32 MiB of JSON text; up to three old revisions' indexes when Studio previews them | Not in the bundle: fetched from the delivery CDN at runtime. Parsed objects take more heap than their JSON text |
|
|
15
|
+
| Content without `site` (`content` from `.deco/blocks.gen`) | The whole content module | Bundled, so resident in every isolate |
|
|
16
|
+
| Your module scope | Anything you import or build at top level | Large JSON or CSV imports, generated tables, unbounded `Map` caches |
|
|
17
|
+
| One request | Whatever it buffers | `await response.text()` on a proxied sitemap is the classic peak |
|
|
18
|
+
|
|
19
|
+
On v7, the bundled decofile was the largest resident item. A v8 site with `site` set does
|
|
20
|
+
not have it. When memory is high on v8, look at your own module scope and your proxies.
|
|
21
|
+
|
|
22
|
+
## 2. Measure: Cloudflare GraphQL Analytics, per version
|
|
23
|
+
|
|
24
|
+
The dashboard rounds and hides the percentile you need. Query the same data.
|
|
25
|
+
|
|
26
|
+
- Endpoint: `https://api.cloudflare.com/client/v4/graphql`, with an API token that can
|
|
27
|
+
read account analytics.
|
|
28
|
+
- Dataset: `workersInvocationsAdaptive`. Quantiles `memoryUsageBytesP50…P999` (bytes),
|
|
29
|
+
`cpuTimeP50…P999` and `wallTimeP50…` (microseconds); sums `requests`, `errors`,
|
|
30
|
+
`subrequests`; dimensions `scriptName`, `scriptVersion`, `datetimeHour`,
|
|
31
|
+
`datetimeFiveMinutes`, `status`.
|
|
32
|
+
|
|
33
|
+
```graphql
|
|
34
|
+
query($a: String!, $n: String!, $s: Time!, $e: Time!) {
|
|
35
|
+
viewer { accounts(filter: { accountTag: $a }) {
|
|
36
|
+
workersInvocationsAdaptive(limit: 2000, orderBy: [datetimeHour_ASC],
|
|
37
|
+
filter: { datetime_geq: $s, datetime_leq: $e, scriptName: $n }) {
|
|
38
|
+
dimensions { datetimeHour scriptVersion }
|
|
39
|
+
sum { requests }
|
|
40
|
+
quantiles { memoryUsageBytesP50 memoryUsageBytesP90 memoryUsageBytesP99 cpuTimeP50 cpuTimeP99 wallTimeP50 }
|
|
41
|
+
}
|
|
42
|
+
} }
|
|
43
|
+
}
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
Group by `scriptVersion` to attribute memory to a deployed version directly. Narrow to
|
|
47
|
+
`datetimeFiveMinutes` once you know the hour. The versions list
|
|
48
|
+
(`GET /accounts/{account}/workers/scripts/{name}/versions`) has the deploy time under
|
|
49
|
+
`metadata.created_on`, not at the top level. A version's detail lists its bindings, which
|
|
50
|
+
answers "is that variable really set in production?".
|
|
51
|
+
|
|
52
|
+
### Compare two windows honestly
|
|
53
|
+
|
|
54
|
+
- **Report P90.** It is what sits against the limit. P50 flatters; P999 is noisy.
|
|
55
|
+
- **Read memory, CPU and wall time together.** High wall with low CPU is waiting on I/O.
|
|
56
|
+
High CPU with low wall is computing. A story that fits two of them often fails the third.
|
|
57
|
+
- **Exclude the rollout** (5 to 10 minutes after the deploy, when two versions mix).
|
|
58
|
+
- **Compare windows of similar traffic** (check `sum { requests }`), take the median across
|
|
59
|
+
5-minute buckets, and state how many buckets you used.
|
|
60
|
+
|
|
61
|
+
### Prove causation
|
|
62
|
+
|
|
63
|
+
A drop right after your deploy may be someone else's deploy. Any one of these upgrades a
|
|
64
|
+
correlation to a cause:
|
|
65
|
+
|
|
66
|
+
1. **A reversal.** Revert or switch off, and the metric moves back by the same amount.
|
|
67
|
+
2. **An independent magnitude match.** A local measurement (parse the same data with
|
|
68
|
+
`node --expose-gc` and compare heap) predicts the same order of change.
|
|
69
|
+
3. **A binding diff.** When no commit explains a regression, compare the bindings of the
|
|
70
|
+
last good version with the first bad one. On one store the only difference was one
|
|
71
|
+
added variable, which switched on a code path that had sat inert for weeks.
|
|
72
|
+
|
|
73
|
+
Without one of these, call the attribution tentative.
|
|
74
|
+
|
|
75
|
+
## 3. Keep large tables out of the isolate
|
|
76
|
+
|
|
77
|
+
Any dataset bundled or built at module scope (redirect lists, geo tables, fixtures, a
|
|
78
|
+
product feed) is resident in every isolate. Measured on a v7 storefront: moving ~18k
|
|
79
|
+
redirect rows out of the bundle cut memory P90 by about 31 MB (−19%).
|
|
80
|
+
|
|
81
|
+
Move the long tail to Workers KV and look it up per request by key:
|
|
82
|
+
|
|
83
|
+
```ts
|
|
84
|
+
// src/worker-entry.ts — normalize() and withDeadline() are your own helpers
|
|
85
|
+
export default createDecoWorker<Env>({
|
|
86
|
+
serverEntry, cms, dev: import.meta.env.DEV,
|
|
87
|
+
routes: async (request, env) => {
|
|
88
|
+
if (request.method !== "GET") return null;
|
|
89
|
+
const url = new URL(request.url);
|
|
90
|
+
if (url.pathname.startsWith("/assets/") || url.pathname.startsWith("/_serverFn/")) return null;
|
|
91
|
+
const key = `redir:${normalize(url.pathname)}`; // the same normalisation as the upload script
|
|
92
|
+
const hit = await withDeadline(env.REDIRECTS.get(key), 50); // fail open
|
|
93
|
+
if (!hit) return null;
|
|
94
|
+
const [status, to] = [Number(hit.slice(0, 3)), hit.slice(4)]; // value: "301:/new-path"
|
|
95
|
+
return new Response(null, { status, headers: { Location: url.search ? `${to}${url.search}` : to } });
|
|
96
|
+
},
|
|
97
|
+
});
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
- Store a small string (`"301:/new-path"`), not JSON: one read, no parse.
|
|
101
|
+
- Upload with the exact normalisation the lookup uses. A mismatch is a silent 100% miss.
|
|
102
|
+
Wire the upload into the deploy script so KV is never behind the code.
|
|
103
|
+
- Point reads only. Never `list()` on a request path.
|
|
104
|
+
- `routes` runs for every request that gets past the CMS redirects, assets and server
|
|
105
|
+
functions included. Return `null` early for paths that are never redirected, so they
|
|
106
|
+
pay no KV read.
|
|
107
|
+
- Fail open: race the read against a short deadline and treat a timeout as "no redirect".
|
|
108
|
+
- Keep the editor-managed redirects in the `Redirects` block. They are few, and Studio
|
|
109
|
+
edits them. The CMS redirects run before `routes`, so they win.
|
|
110
|
+
- A table of a few dozen entries is not worth a KV read per request. Leave it in code.
|
|
111
|
+
|
|
112
|
+
A large `Redirects` block costs CPU on every request as well as memory. Numbers in
|
|
113
|
+
[`render-location.md`](./render-location.md#4-a-large-redirects-block-is-paid-on-every-request).
|
|
114
|
+
|
|
115
|
+
Also check for module-level caches that never evict (`const cache = new Map()` filled per
|
|
116
|
+
request). They grow until the isolate dies. Bound them, or use an upstream cache
|
|
117
|
+
(`deco-storefront-caching`).
|
|
118
|
+
|
|
119
|
+
## 4. Stream large proxied bodies
|
|
120
|
+
|
|
121
|
+
KV fixes resident memory. A peak is one request materialising a big body: `await
|
|
122
|
+
response.text()` on a proxied sitemap, feed or CSV can push a lean isolate over the limit.
|
|
123
|
+
If you only rewrite a passthrough response, stream it:
|
|
124
|
+
|
|
125
|
+
```ts
|
|
126
|
+
function rewriteStream(body: ReadableStream<Uint8Array>, replacements: [string, string][]) {
|
|
127
|
+
const to = new Map(replacements);
|
|
128
|
+
const escape = (s: string) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
|
|
129
|
+
const pattern = new RegExp(replacements.map(([from]) => escape(from)).join("|"), "g");
|
|
130
|
+
const keep = Math.max(...replacements.map(([from]) => from.length)) - 1;
|
|
131
|
+
const decoder = new TextDecoder();
|
|
132
|
+
const encoder = new TextEncoder();
|
|
133
|
+
let tail = "";
|
|
134
|
+
return body.pipeThrough(new TransformStream<Uint8Array, Uint8Array>({
|
|
135
|
+
transform(chunk, out) {
|
|
136
|
+
const text = tail + decoder.decode(chunk, { stream: true });
|
|
137
|
+
const safe = text.length - keep; // a match starting here or later may be cut off
|
|
138
|
+
let done = "";
|
|
139
|
+
let last = 0;
|
|
140
|
+
for (const m of text.matchAll(pattern)) {
|
|
141
|
+
if (m.index >= safe) break;
|
|
142
|
+
done += text.slice(last, m.index) + to.get(m[0]);
|
|
143
|
+
last = m.index + m[0].length;
|
|
144
|
+
}
|
|
145
|
+
const cut = Math.max(last, safe);
|
|
146
|
+
done += text.slice(last, cut);
|
|
147
|
+
tail = text.slice(cut);
|
|
148
|
+
if (done) out.enqueue(encoder.encode(done));
|
|
149
|
+
},
|
|
150
|
+
flush(out) {
|
|
151
|
+
const rest = (tail + decoder.decode()).replace(pattern, (m) => to.get(m) ?? m);
|
|
152
|
+
if (rest) out.enqueue(encoder.encode(rest));
|
|
153
|
+
},
|
|
154
|
+
}));
|
|
155
|
+
}
|
|
156
|
+
|
|
157
|
+
// in routes: return new Response(rewriteStream(upstream.body!, [[ORIGIN, url.origin]]), { headers });
|
|
158
|
+
```
|
|
159
|
+
|
|
160
|
+
The usual mistakes: no `flush` (drops the end of the body); holding back a fixed tail and
|
|
161
|
+
replacing only the part before it, which misses every match that straddles the cut (the
|
|
162
|
+
version above never emits text where a match could still start); and `decode(chunk)`
|
|
163
|
+
without `{ stream: true }` (breaks multi-byte characters split across chunks). Test with
|
|
164
|
+
chunk sizes from 1 byte up. Drop `content-length` from the copied headers, since the
|
|
165
|
+
length changes.
|
|
166
|
+
|
|
167
|
+
Find candidates: `grep -rnE "await (res|response|upstream)\.(text|arrayBuffer|json)\(\)" src/`
|
|
168
|
+
on proxy paths.
|
|
169
|
+
|
|
170
|
+
## Checklist
|
|
171
|
+
|
|
172
|
+
- [ ] P90 memory per `scriptVersion`, before and after, with the rollout excluded
|
|
173
|
+
- [ ] No large JSON, CSV or generated table imported at module scope
|
|
174
|
+
- [ ] No unbounded module-level `Map`
|
|
175
|
+
- [ ] Proxied large bodies streamed, never buffered
|
|
176
|
+
- [ ] The win proved with a reversal or an independent measurement
|
|
@@ -0,0 +1,68 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: deco-tanstack-site
|
|
3
|
+
description: "Wiring a TanStack Start site to @decocms/tanstack 8 on Cloudflare Workers: createCMS and the block map (.deco/index.ts), the catch-all route with matchRoute, the page server function and its search params (loaderDeps, decoStringifySearch), createDecoWorker and the worker entry (routes, csp, preload, pageCache hook), createDecoRouter and decoServerFnFetch, DecoDocument (lang, head, Studio bridge) and DecoPreview, the security headers and Studio's CSP, and server functions in place of v7's /deco/invoke (top-level createServerFn().handler(), markPrivate, Set-Cookie). Load it when scaffolding a v8 TanStack site, wiring routes, the router or the worker, or debugging a page that renders, routes, redirects, previews or reloads wrong. Not for v7 sites (@decocms/blocks 7.x: the 7.x branch) or Next.js (deco-nextjs-site)."
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Deco TanStack Start site (v8)
|
|
7
|
+
|
|
8
|
+
A v8 TanStack site is TanStack Start with four pieces from `@decocms/tanstack` around it: the
|
|
9
|
+
worker (`/worker`), the router (`/router`), the server-function fetch (`/start`) and the root
|
|
10
|
+
document (`/react`). Content comes from `@decocms/blocks`: `createCMS` over the site's block map,
|
|
11
|
+
and `matchRoute` to find the page for a URL. Everything else (routes, server functions, the page
|
|
12
|
+
cache, commerce code) is the site's own code.
|
|
13
|
+
|
|
14
|
+
Load this skill when you build or debug that wiring. `examples/tanstack-worker-smoke` in this repo
|
|
15
|
+
is a complete app; its files are the shapes shown here. The package README
|
|
16
|
+
(`packages/tanstack/README.md`) is the full contract of the worker.
|
|
17
|
+
|
|
18
|
+
## When to load what
|
|
19
|
+
|
|
20
|
+
| Reference | Load it when |
|
|
21
|
+
|---|---|
|
|
22
|
+
| [`references/setup.md`](./references/setup.md) | Starting a site, or checking its files: packages, `vite.config.ts`, `wrangler.jsonc`, `.deco/index.ts`, `src/cms.ts`, scripts |
|
|
23
|
+
| [`references/routes-and-pages.md`](./references/routes-and-pages.md) | The catch-all route, `openPage`, redirects and 404s, rendering blocks, the head, search params and filters that don't reach the loader |
|
|
24
|
+
| [`references/worker-entry.md`](./references/worker-entry.md) | `src/worker-entry.ts`: what `createDecoWorker` always does, its options, the `routes` escape hatch, drafts and the headers it hands the app |
|
|
25
|
+
| [`references/server-functions.md`](./references/server-functions.md) | Replacing `/deco/invoke`, a server function whose code ships to the browser, cookies lost on the way to the browser, per-visitor responses |
|
|
26
|
+
| [`references/router-and-navigation.md`](./references/router-and-navigation.md) | `createDecoRouter` options, `Link` and preload, a navigation that fetches twice or not at all, variant switching on a product page |
|
|
27
|
+
| [`references/document-and-security.md`](./references/document-and-security.md) | `<html lang>`, the head, `DecoDocument` vs your own document, Studio framing, CSP and security headers |
|
|
28
|
+
|
|
29
|
+
## The files of a site
|
|
30
|
+
|
|
31
|
+
| File | What it holds | Import from |
|
|
32
|
+
|---|---|---|
|
|
33
|
+
| `.deco/index.ts` | The block map: one function per block type | `@decocms/blocks` (`Blocks`) |
|
|
34
|
+
| `src/cms.ts` | `createCMS(...)` and the per-request client | `@decocms/blocks`, `@decocms/tanstack/server` |
|
|
35
|
+
| `src/open-page.server.ts` | `openPage(href, request)`: route, redirect, resolve | `@decocms/blocks` (`matchRoute`) |
|
|
36
|
+
| `src/page.functions.ts` | `loadPage`, the page's server function | `@tanstack/react-start` |
|
|
37
|
+
| `src/routes/$.tsx` | The catch-all route that calls `loadPage` | `@tanstack/react-router` |
|
|
38
|
+
| `src/routes/__root.tsx` | `DecoDocument` as the root component | `@decocms/tanstack/react` |
|
|
39
|
+
| `src/router.tsx` | `getRouter()` with `createDecoRouter` | `@decocms/tanstack/router` |
|
|
40
|
+
| `src/start.ts` | `createStart` with `decoServerFnFetch` | `@decocms/tanstack/start` |
|
|
41
|
+
| `src/worker-entry.ts` | `createDecoWorker(...)`, `wrangler.jsonc` `main` | `@decocms/tanstack/worker` |
|
|
42
|
+
|
|
43
|
+
## Rules that hold everywhere
|
|
44
|
+
|
|
45
|
+
- **Never import `@decocms/tanstack/server` or `/worker` from a component.** They are server-only.
|
|
46
|
+
`/react`, `/router`, `/start` and the root export are safe in the browser.
|
|
47
|
+
- **The worker decides the draft, the visitor and the tests once per request.** Read them with
|
|
48
|
+
`contentClient(cms, request)`. Don't add a second draft check.
|
|
49
|
+
- **The page server function reads the page's URL, never the request's.** On a client-side
|
|
50
|
+
navigation the request is the `/_serverFn/…` call.
|
|
51
|
+
- **Each `createServerFn(...).handler(...)` is a top-level `const`.** Inside a function, TanStack's
|
|
52
|
+
compiler skips it and the handler ships to the browser.
|
|
53
|
+
- **Build query strings with `decoStringifySearch`**, not `new URLSearchParams(search)`, which turns
|
|
54
|
+
a repeated key (`filter.size=M&filter.size=L`) into one value (`M,L`).
|
|
55
|
+
- **Responsive layout is CSS** (`md:hidden`, `<picture>` with `<source media>`), not a JS device
|
|
56
|
+
branch: a branch must render the same on server and client, and the example page cache keys on
|
|
57
|
+
device, so a branch splits the cache.
|
|
58
|
+
|
|
59
|
+
## Other skills
|
|
60
|
+
|
|
61
|
+
- `deco-site-workflow`: the `deco` CLI (`schema`, `check`, `pull`, `push --draft`, `publish`) and
|
|
62
|
+
where content lives.
|
|
63
|
+
- `deco-site-authoring`: writing sections, pages and loaders.
|
|
64
|
+
- `deco-storefront-caching`: the site's `pageCache` and the CDN.
|
|
65
|
+
- `deco-storefront-performance`: slow loaders, payload size, hydration.
|
|
66
|
+
- `deco-images-media`: `Image`, `Picture` and `ImageUrlProvider`.
|
|
67
|
+
- `deco-apps`: the `@decocms/apps-*` clients (VTEX cart cookies included).
|
|
68
|
+
- `deco-v7-to-v8-migration`: moving a v7 site here; its script writes the files above.
|