Deco CMS is the next major version of Deco's framework, which ships today as the @decocms 7.x packages. The API in these docs is proposed and hasn't shipped yet; this page is the to-do list for releasing it (a release of the framework, not to be confused with content releases). To build it, we checked the proposed API feature by feature against three real sites that will move to it: a TanStack storefront on the current packages, a TanStack blog on an older package, and a Next.js storefront on another CMS.
No site can move using only what these docs describe. Each first needs something missing: site editor support, a way for blocks to read the current request, or SDK functions beyond the CMS. The ten release blockers gate the release; the status of every feature the three sites use is under Release readiness.
", "readiness_lead": "None of the 111 features those sites use is done yet: 11 are still to build, 66 are to finish, 28 are left to site code, and 6 go away with the migration.", "fix_docs": "Fix the docs A few statements in these docs are still loose or wrong. The fixes are the first two docs work items: {{item:roadmap-docs--resolve-contradictions-in-these-docs}} and {{item:roadmap-docs--correct-studio-compatibility}}." }, "blockers": [ { "id": "roadmap-blockers--let-studio-talk-to-a-next-major-site", "title": "Let the site editor talk to a next-major site", "today": "The site editor reads the schema and content from the running site (/live/_meta, /.decofile) and calls it for previews, /deco/invoke and the secrets encrypt action. A next-major site serves none of these.",
"plan": "The site editor talks to stored content through the content protocol instead, which needs only the committed schema and .deco/blocks: the site editor's GitHub backend in production, deco serve on a developer's machine. Features that need the site's code degrade in this version (see What works without your code).",
"features": [
"admin-protocol-endpoints",
"invoke-and-actions",
"section-catalog",
"global-layout-sections",
"dev-studio-content-loop",
"site-bootstrap"
],
"delivered_by": [
"roadmap-api--publish-the-content-protocol-and-its-package",
"roadmap-platform--build-studio-s-github-content-backend",
"roadmap-platform--move-studio-s-editor-onto-the-protocol-client",
"roadmap-cli--ship-deco-serve-a-local-server-for-studio",
"roadmap-docs--correct-studio-compatibility",
"roadmap-platform--synchronize-editor-drafts"
]
},
{
"id": "roadmap-blockers--make-the-cli-write-a-schema-studio-can-read",
"title": "Make the CLI write a schema the site editor can read",
"today": "The CLI writes .deco/schema.gen.json with top-level definitions; the site editor reads .deco/meta.gen.json in LiveMeta shape (btoa keys, schema.root). There are no apps or actions groups, no per-type variant definitions, and the widget vocabulary is undocumented, so 22 image pickers would become text inputs and HTML fields plain strings.",
"plan": "Emit the site editor's exact format as .deco/schema.gen.json, one multivariate definition per field type a variant can fill, write static option lists into the schema, publish the JSDoc/@format table, and keep widget-alias detection and return-type loader unions.",
"features": [
"studio-schema-generation",
"codegen-pipeline",
"ci-and-release-workflows",
"editor-widgets-and-image-fields",
"rich-text-html-props",
"app-domain-types",
"inline-loader-props"
],
"delivered_by": [
"roadmap-cli--write-a-studio-compatible-schema-file",
"roadmap-cli--publish-the-tag-and-widget-vocabulary",
"roadmap-cli--define-the-loader-picker-rule",
"roadmap-cli--write-static-option-lists-into-the-schema"
]
},
{
"id": "roadmap-blockers--give-blocks-the-page-url-and-route-params",
"title": "Give blocks the page URL and route params",
"today": "On SPA navigation getRequest() returns the /_serverFn URL, Next's headers() has no URL, app packages' loaders have no standard way to receive the URL or match.params, and apps-vtex's RequestContext is never populated.",
"plan": "Add one request scope (url, params, request, client, response headers) that the templates' openPage populates and that block functions and site code can read, passing what a client needs as arguments.",
"features": [
"section-loaders",
"plp-filters-sort-pagination",
"request-context-cookies",
"commerce-platform-binding",
"code-composed-pdp"
],
"delivered_by": [
"roadmap-api--add-a-request-scope"
]
},
{
"id": "roadmap-blockers--make-draft-preview-work-inside-studio-s-iframe",
"title": "Make draft preview work inside the site editor's iframe",
"today": "The SameSite=Lax cookie is rejected cross-site, the TanStack guide never sets it, and ?__draft=off is ignored. There's no no-store rule, and no StudioBridge or data-manifest-key, so click-to-select is lost.",
"plan": "Give the templates withDeco()/decoProxy() recipes, which set the cookie as Secure; SameSite=None; Partitioned, treat ?__draft=off as exit and mark drafts private/no-store. Add <StudioBridge/>, and have the templates wrap each rendered block in the site editor's section[data-manifest-key] marker.",
"features": [
"studio-preview",
"worker-server-entry",
"root-document-layout",
"router-and-client-navigation"
],
"delivered_by": [
"roadmap-api--ship-the-withdeco-and-decoproxy-entry-wrappers",
"roadmap-api--add-a-studio-bridge"
]
},
{
"id": "roadmap-blockers--define-the-non-cms-sdk-surface",
"title": "Define the non-CMS SDK surface",
"today": "apps-* and the ClickHouse telemetry depend on sdk/requestContext, instrumentedFetch, fetchCache and cachedLoader, and sites' widgets on sdk/useDevice and the Image and JsonLd hooks. These docs only list 'loaders, client, resolution, router'.",
"plan": "The framework doesn't fetch data: the apps become thin, instrumented API clients over the framework's instrumented fetch, the core drops /deco/invoke and cachedLoader, and caching moves to template recipes. Ship @decocms/blocks/image.",
"features": [
"framework-import-surface",
"in-isolate-caches",
"upstream-fetch-instrumentation",
"image-optimization",
"json-ld-structured-data",
"interactive-ui-widgets"
],
"delivered_by": [
"roadmap-api--turn-the-apps-into-thin-instrumented-clients",
"roadmap-api--remove-deco-invoke-and-cachedloader",
"roadmap-api--cache-upstream-requests-in-the-bindings",
"roadmap-api--add-an-image-module"
]
},
{
"id": "roadmap-blockers--add-a-revision-handle-an-edge-cache-kit-and-an-isr-recipe",
"title": "Add a revision handle, an edge cache recipe and an ISR recipe",
"today": "Clients expose no revision and there's no forRevision. Degraded pages get cached. The planned check for a new release runs once a minute, at an idle moment (inside ctx.waitUntil on Workers), so propagation depends on the check interval and manifest cache lifetime; a cold isolate serves the content module it was deployed with until its first check.",
"plan": "Add a revision handle, a way to read and pin the revision a client serves (client.revision(), cms.forRevision(), onUpdate), and markDegraded(). Add an edge cache recipe for Workers templates, withEdgeCache(), for caching rendered pages at the edge, and an ISR (Incremental Static Regeneration: re-rendering cached pages in the background) recipe for Next.js.",
"features": [
"edge-html-cache-profiles",
"fast-deploy-kv",
"lazy-deferred-sections",
"otel-observability"
],
"delivered_by": [
"roadmap-api--add-a-revision-handle",
"roadmap-api--add-an-edge-cache-kit",
"roadmap-api--add-remoteloader-options",
"roadmap-docs--fix-the-next-guide"
]
},
{
"id": "roadmap-blockers--stop-resolving-everything-eagerly",
"title": "Stop resolving everything eagerly",
"today": "The one registry rule resolves inputs bottom-up. Lazy defers nothing (43 wrappers on the storefront), hidden variants still run their loaders, and Resolved<T> can't be expressed.",
"plan": "Add the built-in lazy block, so multivariate runs only the chosen variant. The alias bridge unwraps the legacy Lazy/SingleDeferred/Deferred block wrappers: the wrapped block renders normally, with no client-side deferral.",
"features": [
"lazy-deferred-sections",
"matchers-and-variants",
"site-search-and-autocomplete"
],
"delivered_by": [
"roadmap-api--add-the-lazy-block",
"roadmap-cli--widen-the-legacy-alias-bridge"
]
},
{
"id": "roadmap-blockers--make-the-next-major-load-and-resolve-legacy-content",
"title": "Make the next major load and resolve legacy content",
"today": "Filename decoding is unspecified, and the alias bridge covers only pages, matchers and multivariate, while the site editor writes Lazy, SeoV2, site/apps/site.ts, redirect, secret and the multi matcher. UNKNOWN_BLOCK now fails the parent block.",
"plan": "Use the protocol's one filename rule (decode exactly once), widen the alias bridge, ship deco content (with deco schema reporting collisions), and have the CLI emit a runtime alias table.",
"features": [
"block-type-discriminator",
"orphan-and-dangling-blocks",
"content-schema-drift",
"content-storage-and-delivery"
],
"delivered_by": [
"roadmap-cli--specify-the-filename-rule-and-ship-a-content-bundle",
"roadmap-cli--widen-the-legacy-alias-bridge",
"roadmap-cli--add-validation-commands-to-the-cli",
"roadmap-cli--emit-a-runtime-alias-table"
]
},
{
"id": "roadmap-blockers--make-routing-accept-the-content-sites-already-store",
"title": "Make routing accept the content sites already store",
"today": "There's no splat, so /* PLPs never match. matchRoute throws per request on an ambiguity a single site editor commit can introduce. Page.seo is required but content stores null, and with no 404 gate unknown URLs return soft 200s.",
"plan": "Add a trailing splat and make matchRoute non-throwing, with a deterministic tie-break. A hosted publish isn't validated: the tie-break keeps the site up and deco check catches ambiguous routes in CI. Make seo optional and add a critical-block notFound/redirect sentinel.",
"features": [
"cms-page-routing",
"not-found-and-error-pages",
"redirects",
"page-template-targeting"
],
"delivered_by": [
"roadmap-api--add-a-splat-to-matchroute-and-stop-request-time-throws",
"roadmap-api--add-a-not-found-and-redirect-gate-before-streaming",
"roadmap-platform--build-the-deco-api-release-service",
"roadmap-docs--resolve-contradictions-in-these-docs"
]
},
{
"id": "roadmap-blockers--define-a-model-for-apps-config-and-secrets",
"title": "Define a model for apps, config and secrets",
"today": "App loaders get no config, there's no apps manifest group, website/loaders/secret.ts can't decrypt, and the site editor encrypts Secret fields through an action the site serves.",
"plan": "Define the client contract (a factory that takes its config from site code), and vendored loaders keep their old type names as aliases. No apps group in this version. Ship a built-in secret block: content holds only ciphertext, encrypted with a public key committed in .deco/ and decrypted on the server, and the site editor gets a write-only Secret field.",
"features": [
"app-installation-and-store-config",
"env-vars-and-secrets",
"commerce-platform-binding"
],
"delivered_by": [
"roadmap-api--define-an-app-contract",
"roadmap-api--ship-decocms-blocks-secrets",
"roadmap-platform--encrypt-secret-fields-in-the-site-editor",
"roadmap-cli--write-a-studio-compatible-schema-file"
]
}
],
"studio_new": [
{
"id": "roadmap-studio-new--give-studio-a-schema-it-can-read-so-the-editor-loads",
"title": "Give the site editor a schema it can read, so the editor loads",
"today": "The site editor reads .deco/meta.gen.json or /live/_meta in LiveMeta shape, so a next-major site shows 'live meta unavailable'. On protocol projects it reads the committed .deco/schema.gen.json, which must be in that shape.",
"features": [
"studio-schema-generation",
"ci-and-release-workflows",
"codegen-pipeline"
],
"delivered_by": [
"roadmap-cli--write-a-studio-compatible-schema-file",
"roadmap-platform--build-studio-s-github-content-backend"
]
},
{
"id": "roadmap-studio-new--keep-gallery-theme-and-in-place-previews-working",
"title": "Replace gallery, theme and in-place previews",
"today": "The site editor's section thumbnails (its legacy name for block previews), global and theme previews, and Fast Preview in-place render all go through /live/previews, which runs site code. The protocol never does: these become name cards, or open the real page.",
"features": [
"section-catalog",
"theming-and-styling",
"global-layout-sections"
],
"delivered_by": [
"roadmap-platform--move-studio-s-editor-onto-the-protocol-client",
"roadmap-platform--fix-the-add-section-gate",
"roadmap-platform--align-the-preview-protocol"
]
},
{
"id": "roadmap-studio-new--let-editors-save-secret-fields-on-next-major-sites",
"title": "Let editors set Secret fields on next-major sites",
"today": "The site editor encrypts Secret fields through an encrypt action the site serves, with a symmetric key (DECO_CRYPTO_KEY). Protocol projects have no such action, so nothing can encrypt a new secret.",
"features": [
"env-vars-and-secrets",
"app-installation-and-store-config",
"invoke-and-actions"
],
"delivered_by": [
"roadmap-api--ship-decocms-blocks-secrets",
"roadmap-platform--encrypt-secret-fields-in-the-site-editor",
"roadmap-platform--move-studio-s-editor-onto-the-protocol-client"
]
},
{
"id": "roadmap-studio-new--keep-options-run-and-pickers-working",
"title": "Fall back for @options, Run and pickers",
"today": "These need /deco/invoke and /live/invoke, which the protocol replaces. The blog ProductShelf picker even calls production's /deco/invoke with legacy VTEX keys. Pickers fall back to the schema's options, else free text; Run is hidden.",
"features": [
"invoke-and-actions",
"app-installation-and-store-config",
"icon-by-name-enums"
],
"delivered_by": [
"roadmap-cli--write-static-option-lists-into-the-schema",
"roadmap-platform--move-studio-s-editor-onto-the-protocol-client"
]
},
{
"id": "roadmap-studio-new--restore-click-to-select",
"title": "Restore click-to-select",
"today": "There's no editor::inject listener, and the guides' renderers emit no site editor section[data-manifest-key] marker.",
"features": [
"root-document-layout",
"interactive-ui-widgets"
],
"delivered_by": [
"roadmap-api--add-a-studio-bridge"
]
},
{
"id": "roadmap-studio-new--keep-the-draft-past-the-first-in-frame-click",
"title": "Keep the draft past the first in-frame click",
"today": "The Lax cookie isn't stored cross-site and the TanStack guide never sets it. ?__draft=off can leave a stale draft behind.",
"features": [
"studio-preview",
"worker-server-entry"
],
"delivered_by": [
"roadmap-api--ship-the-withdeco-and-decoproxy-entry-wrappers",
"roadmap-docs--fix-the-tanstack-guides",
"roadmap-platform--align-the-preview-protocol"
]
},
{
"id": "roadmap-studio-new--give-field-level-variants-a-schema-contract",
"title": "Give field-level variants a schema contract",
"today": "The site editor's field variant UI needs a single-option block-ref whose definition has variants, and takes the inner field from variants.items.properties.value, else a plain string (schema-form.tsx:76-87, 254-280). The proposed API's one generic multivariate<T> gives the CLI no concrete T, so it has to take T from the field the variant fills. Legacy schemas had one flag per kind, e.g. website/flags/multivariate/image.ts.",
"features": [
"matchers-and-variants",
"editor-widgets-and-image-fields",
"studio-schema-generation"
],
"delivered_by": [
"roadmap-cli--write-a-studio-compatible-schema-file",
"roadmap-docs--fill-in-the-schema-reference-details"
]
},
{
"id": "roadmap-studio-new--keep-variant-tabs-and-the-device-toggle-working",
"title": "Keep variant tabs and the device toggle working",
"today": "x-deco-matchers-override and ?deviceHint have no reader in the built-in multivariate.",
"features": [
"device-detection-and-targeting",
"matchers-and-variants"
],
"delivered_by": [
"roadmap-api--add-a-request-scope",
"roadmap-platform--align-the-preview-protocol"
]
},
{
"id": "roadmap-studio-new--stop-studio-reading-short-type-names-as-saved-entries",
"title": "Stop the site editor reading short type names as saved entries",
"today": "The site editor classifies keys by file extension, so a site's UI blocks must keep legacy site/sections/X.tsx keys until it does a manifest lookup.",
"features": [
"block-type-discriminator",
"section-registration-conventions"
],
"delivered_by": [
"roadmap-platform--use-manifest-lookup-instead-of-path-heuristics",
"roadmap-cli--emit-a-runtime-alias-table"
]
},
{
"id": "roadmap-studio-new--prevent-entry-names-from-colliding-with-types",
"title": "Prevent entry names from colliding with types",
"today": "The site editor's only write guard rejects keys with a source-file extension (block-key.ts:48-50). An editor can save an entry named hero, seo or page; under the proposed API's { ...savedEntries, ...blocks } the function wins and the entry is silently ignored. Only deco schema in CI catches it, after the commit is on the production branch.",
"features": [
"block-type-discriminator",
"orphan-and-dangling-blocks"
],
"delivered_by": [
"roadmap-platform--use-manifest-lookup-instead-of-path-heuristics"
]
},
{
"id": "roadmap-studio-new--let-studio-see-and-edit-flat-redirect-entries",
"title": "Let the site editor see and edit flat redirect entries",
"today": "The Redirects collection lists only blocks typed exactly website/loaders/redirect.ts and writes { redirect: { from, to, type, discardQueryParameters } }, with temporary = 307 (redirect-data.ts:14,29-32,77). Flat redirect entries written by developers or agents never appear there and can't be edited.",
"features": [
"redirects"
],
"delivered_by": [
"roadmap-platform--read-manifest-groups-for-pages-redirects-content-and-apps",
"roadmap-api--add-a-splat-to-matchroute-and-stop-request-time-throws",
"roadmap-cli--widen-the-legacy-alias-bridge"
]
},
{
"id": "roadmap-studio-new--fix-local-and-tunnel-modes-show-local-edits-in-dev",
"title": "Edit local files from the site editor; show local edits in dev",
"today": "The dev server serves neither endpoint the site editor's local and tunnel modes use. With a site and token in .dev.vars, remoteLoader swaps in the production release over local edits.",
"features": [
"dev-studio-content-loop",
"bundler-config"
],
"delivered_by": [
"roadmap-cli--ship-deco-serve-a-local-server-for-studio",
"roadmap-api--add-remoteloader-options"
]
},
{
"id": "roadmap-studio-new--speed-up-publishes-and-make-failures-visible",
"title": "Speed up publishes and make failures visible",
"today": "The planned once-a-minute check delays propagation, and nothing tells the editor which release is prepared, promoted or served. A failed forDraft silently shows published content.",
"features": [
"fast-deploy-kv",
"otel-observability"
],
"delivered_by": [
"roadmap-platform--add-a-content-live-signal",
"roadmap-api--add-remoteloader-options"
]
},
{
"id": "roadmap-studio-new--keep-experiments-working-on-next-major-sites",
"title": "Keep experiments working on next-major sites",
"today": "Results are keyed on the random matcher's saved-entry name, which a pure block function never sees.",
"features": [
"analytics-trackers"
],
"delivered_by": [
"roadmap-platform--drop-legacy-names-from-the-blog-tab-and-experiments",
"roadmap-api--add-an-analytics-bootstrap-and-experiment-support",
"roadmap-cli--widen-the-legacy-alias-bridge"
]
}
],
"studio_legacy": [
{
"id": "roadmap-studio-legacy--handle-the-legacy-types-studio-keeps-writing",
"title": "Handle the legacy types the site editor keeps writing",
"today": "website/pages/Page.tsx, SeoV2 on every new page, Rendering/Lazy.tsx (the ⚡ toggle), flags/multivariate/section.ts (hide), nested website/loaders/redirect.ts, website/loaders/secret.ts, site/apps/site.ts, the multi matcher, Theme. The bridge only aliases pages, matchers and multivariate, so these site editor actions produce UNKNOWN_BLOCK unless each site registers them.",
"features": [
"lazy-deferred-sections",
"page-seo-blocks",
"site-config-block",
"redirects",
"theming-and-styling",
"matchers-and-variants"
],
"delivered_by": [
"roadmap-cli--widen-the-legacy-alias-bridge"
]
},
{
"id": "roadmap-studio-legacy--stop-hidden-sections-from-running",
"title": "Stop hidden blocks from running",
"today": "'Every variant resolves': a block hidden with a never-rule still runs its loaders, and its undefined renders 'temporarily unavailable'.",
"features": [
"matchers-and-variants"
],
"delivered_by": [
"roadmap-api--add-the-lazy-block",
"roadmap-docs--resolve-contradictions-in-these-docs"
]
},
{
"id": "roadmap-studio-legacy--drop-hidden-array-items-instead-of-leaving-holes",
"title": "Drop hidden array items instead of leaving holes",
"today": "The site editor hides a banner or link by wrapping it in website/flags/multivariate.ts with a never rule (array-item-hidden.ts:35-40). Today's resolver drops undefined array items (resolve.ts:849-860). The proposed API's rule and resolve(page.sections) ('An array of results, one per block in the list') keep them, so components receive undefined entries.",
"features": [
"matchers-and-variants"
],
"delivered_by": [
"roadmap-docs--resolve-contradictions-in-these-docs"
]
},
{
"id": "roadmap-studio-legacy--fix-the-default-variant-rule-that-makes-other-variants-unreachable",
"title": "Flag variants that an always rule makes unreachable",
"today": "The site editor seeds every new variant with an always rule (section-types.ts:26; a new field variant starts as two) and keeps the first always, else the last variant (section-variants.ts:158-168). These docs say 'put the always() variant first as the default' and 'first match wins', which makes every other variant unreachable; their own HomeHero puts always last.",
"features": [
"matchers-and-variants"
],
"delivered_by": [
"roadmap-cli--add-validation-commands-to-the-cli",
"roadmap-docs--resolve-contradictions-in-these-docs"
]
},
{
"id": "roadmap-studio-legacy--decode-filenames-exactly-once",
"title": "Decode filenames exactly once",
"today": "The site editor writes encodeURIComponent(key). Real stems include pages-Category%2520Page-* and collections%2Fblog%2F*.",
"features": [
"block-type-discriminator",
"content-storage-and-delivery"
],
"delivered_by": [
"roadmap-cli--specify-the-filename-rule-and-ship-a-content-bundle",
"roadmap-api--publish-the-content-protocol-and-its-package"
]
},
{
"id": "roadmap-studio-legacy--handle-short-form-pages-in-the-page-list-and-seo",
"title": "Handle short-form pages in the page list and SEO",
"today": "page entries are missing from the page list and can be mistaken for the site-SEO owner.",
"features": [
"cms-page-routing",
"site-seo-defaults"
],
"delivered_by": []
},
{
"id": "roadmap-studio-legacy--stop-keying-the-blog-tab-on-legacy-names",
"title": "Stop keying the Blog tab on legacy names",
"today": "It looks for blog/loaders/*.ts and @decocms/apps-blog ≥ 7.53.0. The TanStack blog reads as unsupported-runtime today.",
"features": [
"key-prefix-content-collections",
"studio-workspace-spaces"
],
"delivered_by": [
"roadmap-platform--drop-legacy-names-from-the-blog-tab-and-experiments"
]
},
{
"id": "roadmap-studio-legacy--upgrade-both-tanstack-sites-so-studio-can-frame-them",
"title": "Upgrade both TanStack sites so the site editor can frame them",
"today": "Both TanStack sites send X-Frame-Options: SAMEORIGIN and lack ?__draft, so both plans start with an upgrade to the latest 7.x, past #390 (7.20.10) and #442 (7.34.0).",
"features": [
"csp-security-headers",
"worker-server-entry"
],
"delivered_by": [
"roadmap-storefront--upgrade-7-20-7-to-the-latest-7-x",
"roadmap-blog--upgrade-6-12-to-the-latest-7-x-first"
]
},
{
"id": "roadmap-studio-legacy--make-content-drift-visible-to-editors",
"title": "Catch content drift in CI",
"today": "Fields missing from the schema are hidden in the editor and dropped on save, and that stays as it is. Defaults apply only on save. The storefront's Header children are typed string[] today.",
"features": [
"content-schema-drift",
"cms-navigation-menus"
],
"delivered_by": [
"roadmap-cli--add-validation-commands-to-the-cli"
]
}
],
"work_items": [
{
"id": "roadmap-api--add-a-request-scope",
"group": "api",
"title": "Add a request scope",
"plan": "One scope in @decocms/blocks, behind conditional exports: requestScope() returns { url, params, request, client, device, forcedRules }, plus appendResponseHeader(). The templates' openPage populates it with the real page href (port derivePageUrl), match.params and the per-request client. It replaces sdk/requestContext, the page-scope helpers and currentClient(), so apps import one framework-neutral port and content-reading loaders stay revision-pinned. device honors ?deviceHint and forcedRules exposes x-deco-matchers-override, both on drafts only.
@decocms/blocks",
"plan": "Write down the protocol between the site editor and stored content: JSON-RPC 2.0 over one HTTP endpoint (POST /rpc, batches allowed) with four methods, describe, schema.get, blocks.list and blocks.apply, plus its errors, limits and conditional reads for polling. Ship it as a subpath of @decocms/blocks (@decocms/blocks/protocol), not a separate package. It holds the types and method definitions, a client, a server core over a ContentStorage interface, a filesystem storage and a black-box conformance suite any implementation runs over HTTP. Its key module holds the one filename rule (decode exactly once) that the site editor, deco serve and deco content all import. See Site editor compatibility.
Add advertised durable idempotency receipts and optional schema preconditions, bound uncompressed reads and batch responses, and recheck guards after synchronization and storage retries. Preserve atomic apply semantics through autosave coalescing. Extend conformance for lost responses, restart recovery, racing writes, oversized payloads and tenant isolation. Hosted draft lifecycle, publishing and rollback stay outside the four-method protocol.
Use the Studio implementation handoff for module ownership, durable state and APIs, operation sequencing, proposed defaults and acceptance scenarios; completion includes the documented failure and concurrency cases.
", "features": [ "admin-protocol-endpoints", "dev-studio-content-loop", "block-type-discriminator", "content-storage-and-delivery", "studio-schema-generation", "section-catalog", "site-bootstrap" ], "docs": [ "studio-compatibility", "content-protocol", "studio-implementation" ] }, { "id": "roadmap-api--let-studio-follow-the-deployed-schema", "group": "api", "title": "Read the schema from where the site editor points", "plan": "The site editor builds its forms from the schema of the site it targets. Targeting localhost, it reads the schema from deco serve, so new block types show up as soon as deco schema writes them. Targeting a draft on any other server, it reads the committed .deco/schema.gen.json. There's no option to follow the production deployment's schema: deco check in prebuild already stops content that uses undeployed types from shipping. Update Schema generation once it ships.
lazy block and Lazy<T>",
"plan": "The resolver's one special case: { \"__resolveType\": \"lazy\", \"value\": … } resolves to () => Promise<T>, which resolves value on the first call and returns the same result after that. Export type Lazy<T> = () => Promise<T>. The built-in multivariate takes { rule: boolean; value: Lazy<T> }[] and calls only the first value whose rule is true. deco schema turns a Lazy<T> field into a lazy block whose value is T; the site editor shows the T form and writes the wrapper; deco check flags a Lazy<T> field without a lazy block and a lazy block in a field that isn't Lazy<T>. The alias bridge wraps the values of legacy website/flags/multivariate.ts content.
withDeco() and decoProxy() entry wrappers to the templates",
"plan": "Template code, not a package: withDeco(handler, { cms }) in the TanStack templates and decoProxy() in the Next templates own the per-request plumbing. They set the draft cookie as Secure; SameSite=None; Partitioned; HttpOnly and treat __draft=off as exit. Drafted responses are private/no-store/noindex, and security headers carry frame-ancestors from an exported STUDIO_FRAME_ANCESTORS, never X-Frame-Options. Site editor routes are optional. The CMS keys draft caches on the API ETag, bounded by an LRU.
client.revision(), cms.forRevision(rev) / forRelease({ revision }), CMS.onUpdate(cb) and update({ force }).
The framework doesn't fetch data. Each companion app (VTEX, Shopify, Wake, Magento, Algolia, Resend, …) becomes a thin API client for its platform: typed request functions over the framework's instrumented fetch, keeping the platform's API and generated types. Latency is measured to the response headers, retries count as one data point with a retries attribute, and error logs are structured and never contain upstream bodies, tokens or cookies. The VTEX client keeps retry and circuit breaking on by default. Converters to commerce types, the cart, user and wishlist hooks, cart, session and auth flows, and website features beyond the built-in matchers and multivariate (SEO helpers, sitemaps, redirect logic, analytics scripts) move to platform templates and site code. Upstream API clients has the recipe for writing a client.
/deco/invoke and cachedLoader",
"plan": "The core drops the /deco/invoke endpoint and cachedLoader. Per-shopper reads and actions become the framework's own server functions or route handlers, which call the clients directly. A block function may still fetch data when a site wants it to; it calls a client like any other code.
Caching depends on the platform, so it lives in the templates, not in a package or the clients: a short recipe per platform, a fetch over the Cloudflare Cache API on Workers and over Next's data cache on Next.js, passed as a client's fetch option. The instrumented fetch reports whether each response came from the cache (the cached label), and drafts bypass the cache.
remoteLoader options",
"plan": "{ interval, coldStartTimeoutMs, channel, onUpdate, onError }, also accepted by createCMS. interval is in milliseconds, defaults to DECO_CONTENT_INTERVAL or 60 000, and has a 60 000 minimum (lower values are raised to one minute with a warning). Each check runs one interval ± 10 s after the previous one and fetches only the revision hash. The SDK schedules due checks itself at an idle moment: requestIdleCallback, then scheduler.postTask, then setTimeout; an unref'd timer on Node; and after the response inside ctx.waitUntil on Workers. Instances are process-wide singletons keyed by configuration, with a resetForTests() helper. In dev, the local .deco/blocks wins over the published release even with a site token set, while ?__draft= links still fetch the draft from the API. A draft that fails to load is the app's call, not the framework's: cms.forDraft(pointer).resolve() returns [null, error] and never falls back to published content silently.
With content plus site and token, the bundled content module stays in memory as the fallback next to the live release, against a Worker isolate's 128 MB limit, and it also counts toward the script size limit. Document passing a KV-backed Loader as content for large sites, so no copy is bundled and the fallback is read from KV only when needed. Document a few-line KV loader as template code (no new API: any object with load()), and a deploy step that writes the content to the key before the new Worker takes traffic, since with a missing key every new isolate fails its first reads until its first release check.
apps-vtex",
"plan": "Typed requests for delivery promise in Intelligent Search, tax-inclusive prices, full installments with InterestRate, Intelligent Search events, and createVtexIoClient for persisted IO queries. The session module (resolveRegion, setSegment), the session and cart hooks move to the VTEX platform template, which sites copy.
A client-safe <StudioBridge /> that accepts editor::inject only from an explicit list of site editor origins, configurable for a self-hosted or native site editor. Also resolve(t, { withType: true }) to recover the block type.
SEO helpers are website features, so they live in the platform templates, as code a site owns: PageSeo and SEO functions pre-aliased to SeoV2/Seo/SeoPDPV2/SeoPLPV2, mergeSiteSeo(siteSeo, pageSeo) as the one site-SEO merge (sharing a test suite with the site editor), seoToNextMetadata / seoToTanStackHead, JSON-LD builders and a <JsonLd> renderer.
Each client package exports a factory that takes its configuration as arguments (for example createVtexClient({ account, appKey, appToken }), read from environment variables in site code) and typed request functions. No block map, no framework package dependency, no dynamic module import. Installing an app from the site editor's store is unavailable on next-major sites: a client is added in code.
A Workers template recipe, withEdgeCache(entry, { segment, profiles }), keyed by URL, build, revision and segment. It skips drafts, cold-start fallback and degraded pages. Plus cacheHeaders(profile) and markDegraded().
A saved entry, or an identical inline block, resolves once per client (keyed by type plus canonical inputs), and concurrent calls share in-flight promises.
", "features": [ "saved-loader-blocks", "inline-loader-props", "native-section-overrides", "commerce-seo-sections-in-sections", "implicit-page-data-context" ], "docs": [], "pinned": false }, { "id": "roadmap-api--add-a-splat-to-matchroute-and-stop-request-time-throws", "group": "api", "title": "Add a splat tomatchRoute and stop request-time throws",
"plan": "A trailing /* that matches one or more segments, at lowest precedence (also for Redirect.from, with substitution that keeps segments percent-encoded), and a deterministic tie-break (the entry earlier in the array wins, so matchRoute never throws). The built-in redirect also takes an optional status (301, 302, 307 or 308) and discardQueryParameters, so legacy redirects keep their exact behaviour.
secret block",
"plan": "A built-in secret block, { \"__resolveType\": \"secret\", \"ciphertext\": \"…\" }, resolves to the decrypted string on the server. Fields typed Secret (a branded string) get a write-only password widget in the schema. Encryption is asymmetric: the public key is committed in .deco/ (for example .deco/secrets.pub), so the site editor, deco serve and agents can encrypt, and the private key lives only on the server, passed as createCMS({ secrets: { key: process.env.DECO_SECRETS_KEY } }). Only ciphertext is committed.
Guardrails: a secret resolves only on the server (it throws in the browser and when passed to a client component), { run: false } returns the ciphertext, telemetry redacts it, and deco check validates the ciphertext's format only. Open-source users create the key pair by hand with one standard command the docs show; there's no new CLI command. Migrating a v7 site re-encrypts its secrets once: decrypt with DECO_CRYPTO_KEY, encrypt with the new public key.
mergeGlobals(site, page), with layout blocks resolved on the page's client. Site SEO defaults go through the SEO kit's mergeSiteSeo.
Drop createDecoRouter. Export its pieces instead, decoParseSearch/decoStringifySearch, the CSP-nonce wiring and the scroll and intent defaults, so sites pass them to TanStack's own createRouter.
@decocms/blocks/image (optimized URLs, srcset, site editor quality params), a Next loaderFile, and TanStack <Image>/<Picture>. Export the widget aliases.
Analytics scripts are a website feature: the DECO.events bootstrap and a typed useSendEvent/dispatch move to the platform templates. Template ecommerce events call track() alongside their GTM push; the core stays out of ecommerce. The framework keeps what experiments need: an assignExperiments() middleware helper and an explicit experiment id prop that keys results, which the site editor fills (the legacy alias bridge copies the old saved entry name into it, so existing results carry over). Variant exposure events for real-user monitoring come after the first release (see {{item:roadmap-later--add-real-user-monitoring}}).
A critical block (or seo) may return { notFound } or { redirect }, which the app maps to notFound()/redirect(). Framework control-flow errors are rethrown.
The SDK reports what it sees: resolution, upstream fetches through createInstrumentedFetch, and errors. Inbound requests and page caches come from the framework's own OpenTelemetry setup, not from Deco CMS. Where the SDK's measurements go is the telemetry option of createCMS: { endpoint, headers? } sends OpenTelemetry over OTLP/HTTP to any collector, { site, token } sends to the hosted Deco CMS collector, and false turns it off; when the option is omitted, OTEL_EXPORTER_OTLP_ENDPOINT is used if set, otherwise nothing is sent. Sending happens in the background (ctx.waitUntil on Workers), so a slow collector never delays a response.
With several CMS instances in one process (several sites in one app, for example), each instrumented-fetch measurement goes to the CMS whose client is handling the current request, so every site reports only its own upstream traffic.
", "features": [ "otel-observability", "upstream-fetch-instrumentation" ], "docs": [ "telemetry-internals", "telemetry" ], "pinned": false }, { "id": "roadmap-api--add-the-telemetry-block-sampling-and-aggregation", "group": "api", "title": "Add the Telemetry block, sampling and aggregation", "plan": "createCMS({ blocks, content, telemetry }): telemetry is { endpoint, headers? } for your own OpenTelemetry (OTLP/HTTP) collector, { site, token } for the hosted Deco CMS collector, or false. The top-level site and token load hosted releases and drafts only; they never turn telemetry on by themselves. Telemetry settings (enabled, metrics, errorSampleRate, traceSampleRate) live in an optional well-known saved block, Telemetry, of the built-in telemetry type; deco content doesn't scaffold it, and without it the defaults apply. Editors change it in the site editor or by hand like any content edit; it travels with every release. Code caps what content can raise with telemetry.limits (errorSampleRate, traceSampleRate), so an editor can't increase what leaves for a third party. Error logs are sampled; metrics are aggregated in memory before they're sent; credentials, cookies and bodies are scrubbed in the SDK.
Ship a built-in analytics block, separate from telemetry (it doesn't read the telemetry option or the Telemetry block). It's a settings function, (props?: Analytics) => Required<Analytics>: it returns { enabled: true, collector: <hosted Deco CMS collector>, ...props }, so { \"__resolveType\": \"analytics\" } with no arguments uses the hosted collector, collector points it at your own endpoint and enabled: false turns it off. A site saves an Analytics block, resolves it in its root layout and renders <AnalyticsScript {...analytics} /> (nothing when enabled is false), the same on every framework, and editors change or switch it off in the site editor. There's no site ID: the collector tells sites apart by the page's hostname, as One Dollar Stats does. The script sends page views (path without query string, referrer, hostname) from the browser with no cookies; track(name, props?) from @decocms/blocks/analytics sends custom events through it. Events use the One Dollar Stats tracker's wire format (base64 JSON in GET ?data= when short, otherwise POST/sendBeacon), tested against a pinned tracker version, so collector can be One Dollar Stats' own collector or any endpoint that accepts that format; by default, the hosted Deco CMS collector receives them.
apps-salesforce to apps-sfmc-personalization",
"plan": "The package is a client for Salesforce Marketing Cloud Personalization (formerly Evergage), so it becomes apps-sfmc-personalization, on the same thin-client model as the other apps.
apps-shopify",
"plan": "A predictive-search suggestions loader and a shipping-rates helper.
", "features": [ "site-search-and-autocomplete", "shipping-simulation" ], "docs": [], "pinned": false }, { "id": "roadmap-api--generate-the-sitemap-from-a-client", "group": "api", "title": "Put sitemap generation in the platform templates", "plan": "Sitemaps are a website feature, so the templates ship them as site code: sitemapEntries(client, { types, expand, exclude }), toSitemapXml/toSitemapIndex, plus a Shopify sitemap merge.
Move withABTesting into the TanStack templates as a recipe and bypass drafts by default.
Write .deco/schema.gen.json in the site editor's format (deco-meta@1, byte-compatible with today's meta.gen.json, which the protocol still reads as a fallback): manifest.blocks, schema.definitions keyed by padded, path-independent btoa, and schema.root unions. Add apps and actions groups. For every field a variant can fill (a field of type T), emit a monomorphized multivariate definition per T (value typed as T) under the site editor's legacy per-kind keys (website/flags/multivariate/section.ts, …/image.ts, …), so the field variant UI renders the right input.
The site editor no longer calls the site for picker options, so deco schema writes every static list into the schema as an enum: string-literal unions, TypeScript enums and @options literal lists, with labels where the code gives them. A picker whose options come from a function falls back to free text in this version.
Unwrap Lazy/SingleDeferred/Deferred (the site editor's legacy Lazy section wrapper: the wrapped block renders normally, with no client-side deferral; it is unrelated to the new lazy block), Seo*, site/apps/site.ts, resolved, requestToParam, secret (after the one-time re-encryption by the migration), redirect (nested shape flattened, temporary kept as status 307 and discardQueryParameters kept), the device and random matchers (a random variant's saved entry name is copied into its experiment id), the multi matcher (website/matchers/multi.ts and $live/matchers/MatchMulti.ts, whose and/or combinators keep the { op, matchers } shape that the site editor's variant calendar and rule labels read) and Theme, and list exactly which paths. Legacy Analytics (GTM/GA) isn't aliased to the built-in analytics block, which stays One Dollar Stats only: the migration moves it into a site-owned tag-manager block from the template.
deco check, which validates saved content against the code",
"plan": "deco check [--root <dir>] reads .deco/schema.gen.json and .deco/blocks as they are (it writes nothing, generates no schema, not even in memory, loads no TypeScript and doesn't check whether schema.gen.json is stale; run deco schema first), validates every saved block against that schema, lists the problems per file and exits 1 if there is any. Saved content is valid when every block's props match its block type's schema (required fields, allowed values, limits); every __resolveType names a block type (built-ins and aliases included) or an existing saved block; a reference in a typed field points to a block that returns that type; no saved block is named like a block type, built-in or alias; no two entries match the same URL; and every secret holds well-formed ciphertext (its format only). It also warns, without failing, about a variant after an always rule, which can never be chosen. It catches both directions, code that breaks saved content and content that uses types or fields the code lacks, and runs on content-only changes too, the same locally and in CI. It also runs in prebuild (deco schema && deco content && deco check; predev skips it), so a broken mix of code and content fails the build and never deploys. The docs ship a CI example: npx @decocms/blocks schema && npx @decocms/blocks check, then git diff --exit-code -- .deco/schema.gen.json so a stale committed schema (the file the site editor reads) fails, plus an optional “Require branches to be up to date before merging” (or a merge queue), to catch two changes that pass alone but break together at pull-request time instead of at build time. The Deco API and remoteLoader don't validate content at runtime. Ships with the first release.
Implementation: validate with a JSON Schema validator (such as Ajv) against .deco/schema.gen.json as it is on disk, not by type-checking generated TypeScript with tsc: it takes milliseconds, its errors name the file and field, and it enforces JSDoc constraints and exactly what the site editor allows. Dispatch on __resolveType instead of reporting every anyOf branch, check references against the return type of the function behind them, and rewrite validator errors into short plain lines.
A full JSDoc/@format table (image-uri, video-uri, html, rich-text, rich-text-inline, textarea, markdown, color-input, icon-select, @titleBy, @hide, @options, @label, @minItems…), with widget-alias detection kept, labelled literals, and a golden test against generate-schema.ts.
deco migrate block-map from 7.x manifests, one 7 → next import codemod (6.x sites upgrade to 7.x first), an SEO-hoist rule, APP_REGISTRY → block maps, a requestToParam scaffold, a rule that moves legacy Analytics (GTM/GA) content into the template's tag-manager block, and a one-time re-encryption of v7 secrets for the secret block.
The companion apps stop shipping loaders and actions, so the migration copies the ones a site actually uses (found from its saved content and imports) into the site's own code, rewritten over the thin clients, with their legacy type names kept as aliases so saved content still resolves.
", "features": [ "site-local-loaders", "saved-loader-blocks", "commerce-platform-binding", "app-loader-overrides", "inline-loader-props" ], "docs": [ "renames-and-migrations", "upstream-clients" ] }, { "id": "roadmap-cli--define-the-loader-picker-rule", "group": "cli", "title": "Match fields to block functions by return type", "plan": "A field's type is the value the function receives. deco schema reads each block function's awaited return type, so an object field of type T accepts a plain T or any block whose function returns T or Promise<T> (anyOf $refs), and the site editor's block picker offers those functions plus the saved blocks that resolve through them. ReactNode and ReactNode[] fields take only functions that return JSX (a React element, or a promise of one; the site editor's legacy __SECTION_REF__): ReactNode also includes strings, numbers and booleans, but functions returning those are left out, so matchers never fit sections. Simple types (string, number, boolean, literal unions) stay plain inputs. The generic multivariate<T> fits any field, with T taken from the field and its undefined (no rule matched) allowed, and functions that return boolean fill each rule in variants. The CLI follows imported app maps with last-key-wins and warns on any.
Use the protocol module's one filename rule: a file name is decoded exactly once, and the site editor, deco serve and deco content import the same module, with a collision report. deco content writes .deco/blocks.gen.ts, one import per JSON file, exporting the snapshot { revision, blocks } with the revision computed the same way the Deco API computes it, and computeRevision is exported.
The CLI emits an alias table, a list of second names for types. deco content writes it into the content module (the snapshot's aliases field) and createCMS reads it from there, so list() and resolve() work through aliases. The schema carries it too, mapping the short names (page, redirect, always, never, multivariate, secret) to the well-known types the site editor's special screens look for, so those screens keep working for renamed types.
deco serve, a local server for the site editor",
"plan": "A command of the deco CLI in @decocms/blocks, deco serve, that serves the content protocol on localhost:<port> for the developer's working tree (the app root from --root, or the nearest folder with a .deco/, which it reports to the site editor in describe), so the site editor can edit the files on the developer's machine: the saved content in .deco/blocks, the schema in .deco/schema.gen.json (read-only) and the upload URLs for assets. It listens on the loopback address by default, prints a connect link at start (no token), answers CORS for any origin and answers Chrome's local-network permission preflight. Writes land in .deco/blocks and the app hot-reloads; the server regenerates the content module when a write adds or removes a file. It never commits. deco schema --watch and deco content --watch stay as they are.
deco serve",
"plan": "Without the hosted Deco CMS, files uploaded in the site editor are written into the repository: deco serve accepts them at PUT /assets/<name> beside /rpc, with the same origin and Host checks, writes them to public/assets/ (or the folder --assets <dir> names), never overwrites an existing file, and answers with the path the site editor stores in the field, always /assets/<name>, such as /assets/summer-banner.jpg. The folder is relative to the folder that contains .deco. describe reports the folder and the largest file accepted in its assets field, which is null with --read-only, and uploads are then refused. Vite, TanStack Start and Next already serve public/assets at /assets/ with no setup; a site that picks another folder serves it there itself.
deco command",
"plan": "These docs run npx @decocms/blocks schema, but @decocms/blocks doesn't declare a deco bin yet. Ship the CLI inside @decocms/blocks, so Quickstart installs one package and the CLI always matches the runtime version. Declare deco as the package's single bin, so npx @decocms/blocks <command> runs it with nothing installed and package.json scripts call deco <command>; the bin is a small JavaScript file that loads the TypeScript sources, so it runs under plain Node as well as Bun. Export the commands from the @decocms/blocks/cli subpath, make typescript a required peer dependency (so npm and Bun install it) that the CLI loads only when a command runs, and keep the runtime from ever importing the cli subpath, so app bundles never include the CLI. It has four commands, deco schema [--root <dir>] [--watch], deco check [--root <dir>], deco content [--root <dir>] [--watch] and deco serve [--root <dir>] [--port <n>] [--host <addr>] [--app-url <url>] [--assets <dir>] [--read-only]. Every command works on one folder, .deco/, in the app root (the folder with the app's package.json). --root is the folder that contains it; by default, every command walks up from the current folder to the first folder with a .deco/. There are no input or output paths: deco schema reads .deco/index.ts (or .deco/index.tsx) and writes .deco/schema.gen.json; deco content reads .deco/blocks and writes .deco/blocks.gen.ts, and never reads the block map. The .gen. infix marks the two generated files. The flags of each command are in the CLI reference.
A ContentStorage inside the site editor's API that reads and writes .deco/blocks through the GitHub API, in the folder the project's \"app root\" setting names (a monorepo subfolder included). Every write is a commit, and all files of one blocks.apply go in one tree and one commit, with file contents inlined in the tree request. Clients poll on window focus and about every 30 seconds with one batched conditional request. Publishing, the draft pointer and ?__draft= links stay site editor routes outside the protocol. Drop the requirement for a deployed preview URL, so a project with no deployment can still be edited.
Reuse the existing Fast Preview Git-provider and autosave machinery behind this adapter. Bind the editor endpoint to an automatically managed draft, normalize set precedence, preserve conditional guards and durable request receipts, and coordinate saves with synchronization and publication.
Use the Studio implementation handoff for module ownership, durable state and APIs, operation sequencing, proposed defaults and acceptance scenarios; completion includes the documented failure and concurrency cases.
", "features": [ "admin-protocol-endpoints", "content-storage-and-delivery", "studio-schema-generation", "site-bootstrap", "workspace-packages" ], "docs": [ "content-protocol", "studio-compatibility", "hosted-site-editor", "draft-synchronization", "studio-implementation" ] }, { "id": "roadmap-platform--move-studio-s-editor-onto-the-protocol-client", "group": "studio", "title": "Move the site editor onto the protocol client", "plan": "Projects with a committed .deco/schema.gen.json or .deco/meta.gen.json under their folder use the protocol client, so v7 projects that commit meta.gen.json move to it automatically, with no per-project switch. Fresh and Deno sites, whose schema exists only at runtime, stay on the legacy path. Features that need the site's code degrade: block previews become name cards or open the real page (the local dev app, or the deployed site with a ?__draft= link), dynamic pickers fall back to the schema's options, else free text, and Run and installing apps from the store are hidden. Secret fields keep working: the site editor encrypts them itself with the site's committed public key (see {{item:roadmap-platform--encrypt-secret-fields-in-the-site-editor}}). Autosave stays last-writer-wins. Add the connect flow for a local deco serve endpoint, with a one-line explainer before Chrome's local-network prompt.
Secret fields in the site editor and manage keys in Deco CMS",
"plan": "The site editor shows a Secret field as a write-only password input: it encrypts the value in the browser with the public key committed in .deco/ and saves only the ciphertext as a secret block, never showing a saved value again. It needs no action from the site, so it works on protocol projects and with deco serve. The hosted Deco CMS adds key management: creating the key pair, storing the private key for the site's deployments and rotating it (re-encrypting every saved secret in one commit). Without the hosted Deco CMS, developers create the key pair by hand.
Let anyone edit the files on their machine in the site editor without a Deco account: a connect link from deco serve opens a play workspace in the site editor that talks only to that local server, with no site, team or sign-in. Hosted features (the site editor's GitHub backend, releases, drafts on your site, hosted asset storage and telemetry) stay with a connected site.
With the hosted Deco CMS, the site editor's GitHub backend sends uploads to Deco's asset storage (backed by Amazon S3) instead of the repository, and saves each file's CDN address in the field, so images are served from a CDN and the repository doesn't grow. A field can hold either a CDN address or a path to a file in the repository, so sites that started with local uploads keep working.
", "features": [ "editor-widgets-and-image-fields", "image-optimization" ], "docs": [ "hosted-site-editor", "hosted", "content-protocol" ], "pinned": false }, { "id": "roadmap-platform--fix-the-add-section-gate", "group": "studio", "title": "Fix the Add Section gate", "plan": "The site editor shows Add Section only when a preview server is configured. Gate it on having the schema and the blocks instead; otherwise adding blocks to a page disappears on protocol projects.
", "features": [ "section-catalog", "per-page-section-whitelists" ], "docs": [ "how-it-works" ] }, { "id": "roadmap-platform--read-manifest-groups-for-pages-redirects-content-and-apps", "group": "studio", "title": "Read manifest groups for pages, redirects, content and apps", "plan": "Support several page types and a content collection screen. Read flat redirect entries alongside the nested legacy shape, mapping temporary to status 307 and keeping discardQueryParameters.
Replace the file-extension module-or-entry check and the site editor's legacy \"/sections/\" path heuristics, and refuse to save an entry whose name is a manifest key.
Separate GitHub ingestion and publication from a stable storage/CDN data plane: production reads, including misses and cold reads, never call GitHub. Materialize immutable, canonically hashed JSON snapshots before promoting small per-environment channel manifests. Keep authorization in a minimal independently deployed gateway when needed. Reconcile missed or out-of-order webhooks in the control plane, bound materialization memory and retain last-good releases. Publishing doesn't validate content: the runtime's route tie-break and CI's deco check are the safety net.
Use a durable per-channel promotion coordinator and monotonic generations. Fast rollback selects a retained compatible snapshot without builds, deploys or GitHub reads, records an audit event and pauses automatic promotion until explicitly resumed. Prevent stale jobs from undoing it, define asset retention and garbage collection, notify rendered-page caches, and document actual propagation delays. Site token lifecycle and CI code/content compatibility remain required.
Use the Studio implementation handoff for module ownership, durable state and APIs, operation sequencing, proposed defaults and acceptance scenarios; completion includes the documented failure and concurrency cases.
Production assets stay self-contained; draft previews use versioned overlays over local production, without a base-revision fetch. See Draft overlays.
", "features": [ "content-storage-and-delivery", "cms-page-routing", "orphan-and-dangling-blocks", "codegen-pipeline", "env-vars-and-secrets", "hosting-and-deploy-config", "fast-deploy-kv" ], "docs": [ "hosted", "hosted-publishing", "hosted-drafts", "content-delivery", "hosted-releases-internals", "studio-implementation" ], "pinned": false }, { "id": "roadmap-platform--synchronize-editor-drafts", "group": "studio", "title": "Keep editor drafts current automatically", "plan": "Manage internal draft branches automatically; editors never create branches or rebase. Extend GitHub push intake and existing Studio event delivery: synchronize open drafts in the background, inactive drafts on reopen, and reconcile before saves and publishing. Coalesce updates and retain a slow reconciliation fallback. Use file-level draft wins: compare the draft with its incorporated production tree by blob identity; untouched files adopt production, edited or deleted files keep the entire draft version. Do not merge JSON properties or download conflict bodies. Reuse existing blobs for all file sizes.
Serialize operations per draft, retry external head races without unconditional force updates, retain append-only history and recoverable incorporated-base metadata, and preserve persistence guards. Bound tree-metadata work and concurrency; schema checks remain in CI. Expose synchronization status and audited resolution summaries without overwriting unsaved form state. Publishing produces only the saved-content diff against current production.
Use the Studio implementation handoff for module ownership, durable state and APIs, operation sequencing, proposed defaults and acceptance scenarios; completion includes the documented failure and concurrency cases.
", "features": [ "content-storage-and-delivery", "dev-studio-content-loop", "workspace-packages" ], "docs": [ "draft-synchronization", "hosted-site-editor", "content-protocol", "studio-implementation" ] }, { "id": "roadmap-platform--materialize-exact-draft-previews", "group": "studio", "title": "Serve draft overlays over local production", "plan": "Materialize saved draft changes as private immutable overlay manifests referencing changed-block blobs, with explicit deletion tombstones. Each manifest represents the cumulative draft overrides, not an incremental replay chain. The preview client captures whatever production snapshot it already has; no baseRevision or matching-production download. Fetch only missing changed blobs, share unchanged objects, and key composed views by local production revision plus overlay version. Old pointers fix old overrides but intentionally inherit current local content on later requests.
Use saved write bodies and cached tree/blob identities; read only changed files during recovery, and handle truncated Git comparisons. Preserve exact overlay authorization, bounded memory, preview readiness and garbage collection of referenced blobs. Missing overlays fail the draft client. Production releases remain complete immutable snapshots.
Use the Studio implementation handoff for module ownership, sequencing and acceptance scenarios.
", "features": [ "studio-preview", "content-storage-and-delivery", "env-vars-and-secrets" ], "docs": [ "content-delivery", "hosted-drafts", "content-protocol", "studio-implementation" ] }, { "id": "roadmap-platform--align-the-preview-protocol", "group": "studio", "title": "Align the preview protocol", "plan": "Keep ?__draft=off as the one documented way to end a draft preview, and force variants in the draft content. On protocol projects the canvas opens the real page with the draft pointer, and gallery thumbnails and in-place renders are replaced by name cards, since the protocol never runs site code.
Detect the blog from the manifest, and key experiments on their explicit experiment id instead of the random matcher's entry name.
", "features": [ "studio-workspace-spaces", "key-prefix-content-collections", "analytics-trackers" ], "docs": [], "pinned": false }, { "id": "roadmap-platform--label-matchers-from-their-schema-and-keep-enum-titles", "group": "studio", "title": "Label matchers from their schema and keep enum titles", "plan": "Label short-key matchers from their schema, dedupe aliased matchers, and keep oneOf const titles.
", "features": [ "device-detection-and-targeting", "matchers-and-variants", "icon-by-name-enums" ], "docs": [], "pinned": false }, { "id": "roadmap-platform--add-a-per-page-type-catalog-and-a-page-settings-form", "group": "studio", "title": "Add a per-page-type catalog and a page settings form", "plan": "Use the anyOf on a page type's sections list as the site editor's catalog, and render the remaining page props as a form.
Run the site editor's mergeSeo (seo-editor.tsx) against the kit's mergeSiteSeo test suite. The site-wide template applies to titles only: descriptions are used as written, so descriptionTemplate never wraps them.
Every response carries the served revision in x-deco-revision, and the CMS reports each revision it swaps in to the Deco API with the site token. The site editor polls the API and shows a publish as pending until a report for its revision arrives, then live.
An endpoint that accepts aggregated metrics and sampled error logs, authenticated by site ID and site token, for sites that set telemetry: { site, token }. Separately, it receives page views in the One Dollar Stats format from analytics blocks left on the default collector, telling sites apart by hostname and counting only sites connected to the hosted Deco CMS. Switching a site's telemetry off needs no special channel: it's a commit to the site's Telemetry saved block, from the site editor or by hand, like any content edit.
Replace the two wrong rules for next-major sites. Content edits go only in .deco/blocks/<encodeURIComponent(key)>.json. .deco/index.ts and .deco/blocks are the site's; two files are generated and never edited by hand: .deco/schema.gen.json, which deco schema rewrites after any change to a block's types, and .deco/blocks.gen.ts, which deco content writes and git ignores. A new type needs a block-map entry. remoteLoader picks up prepared releases on its next background check, not on save, and with DECO_SITE and DECO_SITE_TOKEN set the dev server serves the API release, not local edits.
Make Page.seo optional (the site's SEO defaults fill in), drop array elements that resolve to undefined everywhere (the site editor's hidden array items), say that a hidden block resolves to undefined and what to render is the app's job (the core has no fallback rule), put the always() variant last, and fix the credential sentence in Drafts on your site.
Site editor compatibility now describes the content protocol, with the old site endpoints (/live/_meta, /.decofile, /live/previews, /deco/invoke, /live/invoke) as the legacy path. Keep it in step with the protocol as the site editor's implementation lands, and state that sites allow framing through frame-ancestors, never X-Frame-Options, as the entry wrappers do.
Mount withDeco() instead of hand-wiring the draft cookie. Add validateSearch/loaderDeps and staleTime, and state that getRequest() is the RPC request on SPA navigation, so the page URL comes from the request scope.
Write these before the first site migrates: site-wide content and layout (header, footer, theme), site settings, 404/500, route params in blocks, per-shopper reads and actions as server functions (invoke → server fn), and regionalization cache keys.
", "features": [ "site-config-block", "global-layout-sections", "theming-and-styling", "not-found-and-error-pages", "route-params-request-to-param", "site-local-loaders", "newsletter-subscription", "client-commerce-state-hooks", "session-regionalization" ], "docs": [], "pinned": false }, { "id": "roadmap-docs--write-the-post-cutover-recipes", "group": "docs", "title": "Write the post-cutover recipes", "plan": "Page-level data shared by a page's blocks, client data fetching, server-only upstream proxies, overriding an app's block, tabs over pre-resolved data, head tags from blocks, locale, and robots/static SEO files.
", "features": [ "implicit-page-data-context", "product-comparison", "bff-custom-endpoints", "app-loader-overrides", "tabbed-shelf-partial", "head-tags-from-sections", "i18n-and-currency", "robots-and-static-seo-files" ], "docs": [], "pinned": false }, { "id": "roadmap-docs--write-a-faststore-to-blocks-guide", "group": "docs", "title": "Write a FastStore-to-Blocks guide", "plan": "Decision: port @faststore/core's UI components (FastStore calls them sections) into the site as vendored code, with no separate storefront UI kit; the commerce hooks they need come from apps-vtex. The guide covers the choice of App Router or TanStack Start (there's no Pages Router path), a core-internals → apps-vtex map, a fragment → loader map and the override → composition recipe.
", "features": [ "faststore-cli-overlay", "design-system-library", "graphql-fragments-codegen", "native-section-overrides", "native-platform-sections", "framework-import-surface", "workspace-packages", "site-config-block" ], "docs": [], "pinned": false }, { "id": "roadmap-docs--fix-the-next-guide", "group": "docs", "title": "Fix the Next guide", "plan": "Mount decoProxy() instead of wiring the draft cookie by hand. Wrap client() in cache(), map the full PageSeo and degrade SEO errors instead of throwing, make release routes ISR/static, and cover transpilePackages and outputFileTracingIncludes.
Telemetry now covers what's sent and sampling, and The hosted Deco CMS covers connecting a site. Still to add: (1) the DECO_SITE and DECO_SITE_TOKEN lifecycle (issue, rotate, scope) and a one-time warning when createCMS runs in production without them; (2) a per-host table of how the SDK schedules its once-a-minute check on Workers, Node and Vercel; (3) default bounds for every in-isolate cache and how to change them; (4) the 7.x → next env and binding table. Plus a CI job that resolves one block per app package in a Workers production build, to catch dynamic-import failures.
", "features": [ "env-vars-and-secrets", "hosting-and-deploy-config", "in-isolate-caches", "upstream-fetch-instrumentation", "otel-observability", "legacy-runtime-leftovers", "shopify-autoconfig-workaround" ], "docs": [ "telemetry", "hosted", "hosted-telemetry" ], "pinned": false }, { "id": "roadmap-docs--add-notes-to-the-rendering-section", "group": "docs", "title": "Add notes to the Rendering page", "plan": "Add four statements to Rendering. Inline <script> in a streamed boundary runs on parse, before the boundary is revealed, so use effects. A legacy Lazy wrapper is unwrapped, so its block renders normally, with no client-side deferral. UI stores (drawers, minicart) are app code, created per request. Request-scope values are read during resolve and passed as props, because AsyncLocalStorage is gone by the time a streamed boundary renders.
Unions to anyOf with const discriminators, intersections and recursion, type resolution through packages, filename-to-entry encoding, and how a variant on a field of type T becomes one multivariate definition per T.
", "features": [ "conditional-schema-fields", "cms-navigation-menus", "app-domain-types", "block-type-discriminator", "matchers-and-variants" ], "docs": [ "schema" ], "pinned": false }, { "id": "roadmap-later--add-real-user-monitoring", "group": "later", "title": "Add real-user monitoring", "plan": "Real-user monitoring (RUM): what visitors experience in the browser, as a customer-facing alternative to Google Analytics, linked to A/B testing through variant exposure events. It's planned as a follow-up after the first release, not a release blocker, and it's being worked on. Its API isn't designed yet.
", "features": [ "analytics-trackers", "ab-traffic-split", "ecommerce-analytics-events" ], "docs": [ "matchers-and-variants", "analytics" ] }, { "id": "roadmap-later--detect-conflicting-edits-in-studio", "group": "later", "title": "Detect conflicting edits in the site editor", "plan": "The site editor's autosave is last-writer-wins in the first version of the protocol. Send each save with ifMatch, the version the form opened with, and show 'changed elsewhere: reload or overwrite' when it conflicts.
Add a few-line Vite plugin recipe to the templates that mounts the content protocol's handler in the app's own dev server, so editing the files on your machine from the site editor needs one process instead of two. deco serve stays for other setups.
An optional wait on the protocol's conditional reads, announced in describe, so a hand edit in the working tree shows in the site editor in a fraction of a second instead of on the next 2-second poll. One tab per endpoint would hold the request, so autosaves never queue behind it.
@decocms 7.x packages.",
"headline": "Closest to the next major. Before it can move, the proposed API needs successors for the pieces it relies on today: the worker entry (the Workers request handler that wraps the app), the edge cache, the page-URL plumbing and the endpoints the site editor calls.",
"steps": [
{
"id": "roadmap-storefront--fix-dark-metrics-and-deco-invoke-404s",
"kind": "now",
"title": "Fix dark metrics and /deco/invoke 404s",
"text": "createInstrumentedFetch(\"shopify\") has no onComplete, so upstream metrics are dark. Site loaders called through /deco/invoke 404.",
"features": [
"upstream-fetch-instrumentation",
"site-local-loaders"
],
"no_action": false
},
{
"id": "roadmap-storefront--upgrade-7-20-7-to-the-latest-7-x",
"kind": "pre",
"title": "Upgrade 7.20.7 to the latest 7.x",
"text": "The lockfile pins 7.20.7, which still sends X-Frame-Options: SAMEORIGIN and has no ?__draft binding. Moving past #390 (7.20.10) and #442 (7.34.0) lets the site editor frame and preview the site today, and leaves one 7 → next step.",
"features": [
"csp-security-headers",
"worker-server-entry",
"studio-preview"
],
"no_action": false
},
{
"id": "roadmap-storefront--keep-studio-s-forms-previews-and-options-working-after-the-move",
"kind": "blocker",
"title": "Keep the site editor's forms, previews and @options working after the move",
"text": "Next-major serves none of /live/_meta, /live/previews or /deco/invoke, and its schema file isn't what the site editor reads. Forms, previews, @options fields and the Loaders tab all stop.",
"features": [
"admin-protocol-endpoints",
"studio-schema-generation",
"codegen-pipeline"
],
"no_action": false
},
{
"id": "roadmap-storefront--drop-apps-shopify-s-decocms-tanstack-dependency-and-document-its-sdk-imports",
"kind": "blocker",
"title": "Drop apps-shopify's @decocms/tanstack dependency and document its SDK imports",
"text": "It imports @decocms/blocks/sdk/{fetchTimeout,instrumentedFetch} and depends on @decocms/tanstack.",
"features": [
"framework-import-surface",
"commerce-platform-binding"
],
"no_action": false
},
{
"id": "roadmap-storefront--keep-the-edge-cache-and-a-b-split-without-createdecoworkerentry",
"kind": "blocker",
"title": "Keep the edge cache and A/B split without createDecoWorkerEntry",
"text": "Workers Cache is on, with segment keys and degraded-page protection. The SITES_KV traffic split has no home.",
"features": [
"edge-html-cache-profiles",
"ab-traffic-split"
],
"no_action": false
},
{
"id": "roadmap-storefront--keep-the-page-url-on-spa-navigation-plp-search-pdp",
"kind": "blocker",
"title": "Keep the page URL on SPA navigation (PLP, search, PDP)",
"text": "Today's x-deco-page-url and derivePageUrl workarounds have no successor.",
"features": [
"section-loaders",
"plp-filters-sort-pagination"
],
"no_action": false
},
{
"id": "roadmap-storefront--do-the-mechanical-port",
"kind": "work",
"title": "Do the mechanical port",
"text": "Hand-write the block map (27 UI blocks, 12 loaders) with the path-shaped keys the site editor needs, add the ~8-line requestToParam shim (app code), and replace Image/Picture (~20 files). The content fixes below register types into this map.",
"features": [
"site-bootstrap",
"section-registration-conventions",
"image-optimization",
"route-params-request-to-param"
],
"no_action": false
},
{
"id": "roadmap-storefront--fix-the-content-before-cutover",
"kind": "content",
"title": "Fix the content before cutover",
"text": "Rewrite the Category page path /* to /:collection, guard the PDP's seo: null and hoist SEO blocks out of sections[]. Register in the block map, or remove, ~20 unknown types, including the resolved built-in that Header.json's searchbar uses. Fix the Newsletter and Header drift, and hold MIGRATION_NEXT_STEPS' *Config Props regrouping until a content validator exists.",
"features": [
"cms-page-routing",
"commerce-seo-sections-in-sections",
"orphan-and-dangling-blocks",
"content-schema-drift"
],
"no_action": false
},
{
"id": "roadmap-storefront--unwrap-lazy-wrappers-and-stop-duplicate-loads",
"kind": "content",
"title": "Unwrap Lazy wrappers and stop duplicate loads",
"text": "The alias bridge unwraps its 43 Lazy wrappers (21 with inline loaders): each wrapped block renders normally, with no client-side deferral. 'PLP Loader' is referenced twice per page and needs the per-client memo.",
"features": [
"lazy-deferred-sections",
"inline-loader-props",
"saved-loader-blocks"
],
"no_action": false
}
]
},
{
"id": "blog-tanstack",
"name": "TanStack blog",
"short": "blog",
"section": "roadmap-blog",
"description": "A blog on TanStack Start and Cloudflare Workers, on an older single-package version of the framework.",
"headline": "Simple content and a clean route tree, but it's on an older package: it upgrades to 7.x first (until then, the site editor can't open it in its preview frame), and its site editor blog workflow depends on old loader names and apps-blog.",
"steps": [
{
"id": "roadmap-blog--upgrade-6-12-to-the-latest-7-x-first",
"kind": "pre",
"title": "Upgrade 6.12 to the latest 7.x first",
"text": "Fix upgrade-6-to-7 for the blog's specifiers (~45 symbols across 13 subpaths), then run it. That also drops X-Frame-Options: SAMEORIGIN and adds ?__draft, so the site editor can frame the site. The move to next is then the same 7 → next step as the storefront's.",
"features": [
"framework-import-surface",
"codegen-pipeline",
"csp-security-headers",
"worker-server-entry"
],
"no_action": false
},
{
"id": "roadmap-blog--untie-the-blog-tab-from-legacy-names-and-apps-blog",
"kind": "blocker",
"title": "Untie the Blog tab from legacy names and apps-blog",
"text": "It keys off blog/loaders/*.ts and @decocms/apps-blog ≥ 7.53.0, but the site is on @decocms/apps 5.2.0. Its meta sits at src/server/admin/meta.gen.json with Windows-path keys, and setInvokeLoaders exists only for the site editor.",
"features": [
"key-prefix-content-collections",
"studio-schema-generation",
"admin-protocol-endpoints",
"app-domain-types"
],
"no_action": false
},
{
"id": "roadmap-blog--stop-blog-loaders-reading-the-global-decofile",
"kind": "blocker",
"title": "Stop blog loaders reading the global decofile",
"text": "apps-blog's getRecordsByPath uses loadBlocks(), so under a pure CMS drafts read the wrong revision. It needs the request scope's client, or the lookups move to route code.",
"features": [
"key-prefix-content-collections",
"inline-loader-props",
"page-seo-blocks"
],
"no_action": false
},
{
"id": "roadmap-blog--keep-the-live-publish-path",
"kind": "blocker",
"title": "Keep the live publish path",
"text": "regen-blocks.yml (site editor publish, then a regen commit, then a Workers Build) is how content ships today. Keep it until the release service and remoteLoader exist.",
"features": [
"ci-and-release-workflows",
"content-storage-and-delivery"
],
"no_action": false
},
{
"id": "roadmap-blog--return-real-404s-for-unknown-urls-and-stop-routing-404-publicly",
"kind": "content",
"title": "Return real 404s for unknown URLs and stop routing /404 publicly",
"text": "The 7 pages form a valid trie, but unknown URLs are soft 200s via /:slug and /404 is publicly routable.",
"features": [
"not-found-and-error-pages",
"cms-page-routing"
],
"no_action": false
},
{
"id": "roadmap-blog--alias-legacy-types-and-render-body-blocks",
"kind": "content",
"title": "Alias legacy types and render body blocks",
"text": "25 legacy types (210 occurrences) need aliases, and body blocks become a data-only block with a renderer.",
"features": [
"block-type-discriminator",
"post-body-block-renderer"
],
"no_action": false
},
{
"id": "roadmap-blog--handle-images-the-edge-profile-and-app-config",
"kind": "work",
"title": "Handle images, the edge profile and app config",
"text": "The blog uses plain <img>, no edge profile fits posts, and app config goes through apps-blog.",
"features": [
"image-optimization",
"edge-html-cache-profiles",
"app-installation-and-store-config"
],
"no_action": false
},
{
"id": "roadmap-blog--two-current-bugs-go-away-with-the-migration",
"kind": "fix",
"title": "Two current bugs go away with the migration",
"text": "One is in the layout cache, the other in the build-time site-globals snapshot, which never reaches draft preview. The migration replaces both.",
"features": [
"in-isolate-caches",
"build-time-site-globals-snapshot"
],
"no_action": true
}
]
},
{
"id": "faststore",
"name": "Next.js storefront",
"short": "Next.js store",
"section": "roadmap-faststore",
"description": "A Next.js storefront on another CMS. Not on Deco today, so this is a re-platform, not an upgrade.",
"headline": "A re-platform, not an upgrade. The target framework, the content, FastStore's native sections and the session model all come before the missing pieces in the proposed API even come into play.",
"steps": [
{
"id": "roadmap-faststore--pick-the-target-framework-and-move-to-it",
"kind": "blocker",
"title": "Pick the target framework and move to it",
"text": "Pick the target first: the App Router (the only guide; the Pages Router has none) or TanStack Start. It decides how FastStore's native sections get rebuilt. Its code imports @faststore/core internals, and most of its hook files, and the files that use its translation hook, lack \"use client\".",
"features": [
"faststore-cli-overlay",
"framework-import-surface",
"design-system-library",
"i18n-and-currency"
],
"no_action": false
},
{
"id": "roadmap-faststore--bring-the-content-in-from-vtex-headless-cms",
"kind": "blocker",
"title": "Bring the content in from VTEX Headless CMS",
"text": "The content lives in VTEX Headless CMS. The Headless CMS-to-.deco/blocks importer is handled outside this roadmap, the JSONC schemas must become TS types, and per-page-type whitelists of allowed blocks and singletons have no TS or site editor expression.",
"features": [
"faststore-cli-overlay",
"content-storage-and-delivery",
"block-type-discriminator",
"per-page-section-whitelists",
"page-template-targeting"
],
"no_action": false
},
{
"id": "roadmap-faststore--rebuild-what-faststore-core-renders",
"kind": "blocker",
"title": "Rebuild what @faststore/core renders",
"text": "Its native sections (FastStore's UI components), including the stateful cart, search and session ones, the global ones (header, footer) and the 404/500 pages. No UI kit exists.",
"features": [
"native-platform-sections",
"native-section-overrides",
"global-layout-sections"
],
"no_action": false
},
{
"id": "roadmap-faststore--give-apps-vtex-session-region-and-delivery-promise",
"kind": "blocker",
"title": "Give apps-vtex session, region and delivery promise",
"text": "Without a populated request scope, regionalized Intelligent Search queries also silently fall back to the default region.",
"features": [
"session-regionalization",
"delivery-promise",
"commerce-platform-binding"
],
"no_action": false
},
{
"id": "roadmap-faststore--rewrite-the-data-shapes-to-schema-org",
"kind": "content",
"title": "Rewrite the data shapes to schema.org",
"text": "FastStore GraphQL moves to apps-commerce schema.org: the PDP view model, the product card, the BFF fields, tax prices and installments.",
"features": [
"code-composed-pdp",
"product-card",
"graphql-schema-extensions",
"bff-custom-endpoints"
],
"no_action": false
},
{
"id": "roadmap-faststore--port-client-state-and-the-core-patches",
"kind": "work",
"title": "Port client state and the core patches",
"text": "The useSearch state machine and the client fetches become server functions. The behaviours the core patches add are re-created as app code.",
"features": [
"plp-filters-sort-pagination",
"graphql-fragments-codegen",
"core-patches"
],
"no_action": false
},
{
"id": "roadmap-faststore--rename-componentkey-values-to-path-shaped-keys-and-avoid-type-name-collisions",
"kind": "fix",
"title": "Rename $componentKey values to path-shaped keys and avoid type-name collisions",
"text": "There's no legacy Deco content, so no legacy-type aliases. The content import (handled outside this roadmap) must still rename $componentKey values (Navbar, Footer, Alert…) to path-shaped keys until the site editor does manifest lookups, and avoid entry names that collide with type names. The content protocol and schema fixes ({{item:roadmap-api--publish-the-content-protocol-and-its-package}}, {{item:roadmap-cli--write-a-studio-compatible-schema-file}}) gate editing.",
"features": [
"studio-schema-generation",
"studio-preview",
"block-type-discriminator"
],
"no_action": false
}
]
}
],
"categories": [
{
"id": "routing",
"title": "Routing",
"description": "URL routing, page matching, route params, not-found handling, non-CMS routes, redirects and client navigation."
},
{
"id": "content-model",
"title": "Content model",
"description": "How content is shaped: block types, saved entries (named or global), collections, props, rich text, editor widgets, drift and targeting rules."
},
{
"id": "sections",
"title": "UI blocks",
"description": "Registering blocks that render UI, the site editor's block catalog, overrides of platform-native components, and lazy, deferred or viewport-gated rendering."
},
{
"id": "data",
"title": "Data",
"description": "Loaders, query props, legacy section loaders (server-side prop enrichment), invoke/actions/BFF endpoints and search, plus site overrides of app loaders."
},
{
"id": "commerce",
"title": "Commerce",
"description": "Commerce platform bindings (Shopify, VTEX), cart, session, regionalization, product merchandising and commerce-specific GraphQL."
},
{
"id": "seo",
"title": "SEO",
"description": "Page and site SEO, head tags, JSON-LD, sitemap and robots."
},
{
"id": "interactivity",
"title": "Interactivity",
"description": "Client-side UI behaviour and client state: widgets, tabs, PLP navigation, client commerce hooks and UI stores."
},
{
"id": "caching",
"title": "Caching",
"description": "Edge/HTML cache profiles, in-isolate and client caches, and request context (cookies, headers, device)."
},
{
"id": "studio",
"title": "Site editor",
"description": "Admin/site editor protocol, preview, schema generation or upload, and the local dev-to-site-editor content loop."
},
{
"id": "config",
"title": "Config",
"description": "Site bootstrap, site and app config blocks, app autoconfig, environment variables and secrets."
},
{
"id": "runtime-deploy",
"title": "Runtime & deploy",
"description": "Worker/server entry, security headers, traffic splitting, hosting, content storage and delivery, and CI/release."
},
{
"id": "build",
"title": "Build",
"description": "Codegen, bundler config, framework import surface, patches, dev tooling, tests and repo hygiene."
},
{
"id": "design",
"title": "Design",
"description": "Theming, fonts, icons, images, design-system libraries and i18n."
},
{
"id": "observability-analytics",
"title": "Observability & analytics",
"description": "OTel and logging, upstream fetch instrumentation, analytics trackers and e-commerce events."
}
],
"features": {
"cms-page-routing": {
"name": "CMS pages matched by URL pattern",
"category": "routing",
"status": "to-finish",
"effort": "M",
"sites": [
"storefront-tanstack",
"blog-tanstack",
"faststore"
],
"summary": "Paths take only literal segments and single-segment params, so the storefront's `/*` Category page never matches. One site editor commit can make `matchRoute` throw on every request, and `Page.seo` is required while stored content holds `seo: null`.",
"docs": [
"routing",
"router-internals",
"renames-and-migrations",
"api-reference",
"nextjs",
"tanstack-start-descriptors",
"studio-compatibility",
"releases-and-deployment"
],
"confidence": "high",
"first_rated": null,
"rated_before_review": null,
"unconfirmed_sub_claim": false
},
"home-route-override": {
"name": "Home route override (search params, page-URL header, client preload)",
"category": "routing",
"status": "to-finish",
"effort": "S",
"sites": [
"storefront-tanstack"
],
"summary": "The guide's `/$` route has no validateSearch or loaderDeps, and on `` navigation `getRequest()` returns the `/_serverFn/...` RPC URL, so search params and the page URL never reach blocks.",
"docs": [
"tanstack-start-descriptors",
"router-internals",
"blocks",
"nextjs"
],
"confidence": "high",
"first_rated": null,
"rated_before_review": null,
"unconfirmed_sub_claim": false
},
"route-params-request-to-param": {
"name": "Route params bound via requestToParam",
"category": "routing",
"status": "site-code",
"effort": "S",
"sites": [
"storefront-tanstack",
"blog-tanstack"
],
"summary": "The CMS never injects `match.params`, so every migrated site repeats the same ~8-line AsyncLocalStorage shim, and every `resolve()` must start inside it. The guides don't show it.",
"docs": [
"routing",
"blocks",
"design-decisions",
"renames-and-migrations"
],
"confidence": "high",
"first_rated": null,
"rated_before_review": null,
"unconfirmed_sub_claim": false
},
"not-found-and-error-pages": {
"name": "Not-found and error pages",
"category": "routing",
"status": "to-finish",
"effort": "M",
"sites": [
"storefront-tanstack",
"blog-tanstack",
"faststore"
],
"summary": "Only URL-level not-found works as documented. Unknown single-segment URLs match a template and stream as cacheable soft 200s, and there's no story for CMS-authored 404 and 500 pages.",
"docs": [
"routing",
"nextjs",
"tanstack-start-descriptors",
"rendering"
],
"confidence": "high",
"first_rated": null,
"rated_before_review": null,
"unconfirmed_sub_claim": false
},
"non-cms-routes-and-account-pages": {
"name": "Code-only routes, account/login pages and external checkout",
"category": "routing",
"status": "site-code",
"effort": "S",
"sites": [
"storefront-tanstack",
"faststore"
],
"summary": "Code routes stay in the framework's router, so account and login pages are app code. After FastStore, `/pvt/account` falls into the CMS catch-all and 404s unless the account link points at the VTEX-hosted account.",
"docs": [
"design-decisions",
"routing"
],
"confidence": "high",
"first_rated": null,
"rated_before_review": null,
"unconfirmed_sub_claim": false
},
"router-and-client-navigation": {
"name": "Router setup, Link and client navigation",
"category": "routing",
"status": "to-finish",
"effort": "M",
"sites": [
"storefront-tanstack",
"blog-tanstack",
"faststore"
],
"summary": "`createDecoRouter` carries three behaviours these docs never mention: URLSearchParams search serializers, the CSP nonce, and scroll and intent defaults. The TanStack guide never appends the draft cookie, so preview is lost on the first in-frame `` click.",
"docs": [
"tanstack-start-descriptors",
"nextjs",
"releases-and-drafts",
"renames-and-migrations"
],
"confidence": "high",
"first_rated": null,
"rated_before_review": null,
"unconfirmed_sub_claim": false
},
"pwa-offline-static-assets": {
"name": "Offline page, service worker and public static assets",
"category": "routing",
"status": "site-code",
"effort": "S",
"sites": [
"storefront-tanstack"
],
"summary": "Static assets are served before the CMS catch-all and `/offline` is an ordinary Route entry; registering `sw.js` and the web manifest takes about 3 lines. Any CSP must allow the Workbox import, and `/offline` must never be a draft render.",
"docs": [
"routing"
],
"confidence": "high",
"first_rated": null,
"rated_before_review": null,
"unconfirmed_sub_claim": false
},
"redirects": {
"name": "Redirects and route handlers",
"category": "routing",
"status": "to-finish",
"effort": "S",
"sites": [
"storefront-tanstack",
"faststore"
],
"summary": "`/old/*` globs are impossible with single-segment params, the site editor's 307 has no counterpart (only 301 or 302), and query, case and duplicate-`from` handling are unspecified. A naive legacy alias doesn't match the nested shape the site editor stores.",
"docs": [
"routing",
"router-internals",
"nextjs",
"tanstack-start-descriptors",
"studio-compatibility",
"renames-and-migrations"
],
"confidence": "high",
"first_rated": null,
"rated_before_review": null,
"unconfirmed_sub_claim": false
},
"page-template-targeting": {
"name": "PDP/PLP templates targeted by product slug or category path",
"category": "routing",
"status": "to-finish",
"effort": "L",
"sites": [
"faststore"
],
"summary": "The entries live in VTEX Headless CMS, so converting them to `.deco/blocks` comes first. There's no multi-segment catch-all, so category trees need one entry per depth, and [Routing](#routing) and [Router internals](#router-internals) disagree on when two templates are ambiguous.",
"docs": [
"routing",
"router-internals",
"api-reference"
],
"confidence": "medium",
"first_rated": null,
"rated_before_review": null,
"unconfirmed_sub_claim": false
},
"block-type-discriminator": {
"name": "Block type naming (__resolveType / $componentKey)",
"category": "content-model",
"status": "to-finish",
"effort": "M",
"sites": [
"storefront-tanstack",
"blog-tanstack",
"faststore"
],
"summary": "Aliases are documented, but the filename-to-entry-name rule isn't (the site editor writes every key through `encodeURIComponent`), the site editor still classifies keys by their path shape, and an unregistered legacy type now fails its parent block with UNKNOWN_BLOCK.",
"docs": [
"quickstart",
"blocks",
"renames-and-migrations",
"tanstack-start-descriptors",
"studio-compatibility",
"design-decisions"
],
"confidence": "high",
"first_rated": "done",
"rated_before_review": null,
"unconfirmed_sub_claim": false
},
"global-layout-sections": {
"name": "Global/shared layout blocks (header, footer)",
"category": "content-model",
"status": "to-finish",
"effort": "M",
"sites": [
"storefront-tanstack",
"blog-tanstack",
"faststore"
],
"summary": "Saved entries with references cover the two TanStack sites, but FastStore's global singletons have no equivalent. A layout and its page can get two clients on different revisions, and Lazy-wrapped headers and footers are unwrapped and render with no client-side deferral.",
"docs": [
"blocks",
"caching",
"nextjs",
"releases-and-deployment",
"rendering",
"design-decisions"
],
"confidence": "medium",
"first_rated": "done",
"rated_before_review": null,
"unconfirmed_sub_claim": false
},
"saved-loader-blocks": {
"name": "Saved loader blocks and commerce extension wrappers",
"category": "content-model",
"status": "to-finish",
"effort": "M",
"sites": [
"storefront-tanstack"
],
"summary": "Per-request dedupe is only implied: no cache key, and nothing on shared in-flight promises. Pages that reference 'PLP Loader' or 'PDP Loader' twice would double their Shopify calls, and a failing loader now fails its whole block.",
"docs": [
"blocks",
"routing",
"api-reference",
"troubleshooting",
"studio-compatibility"
],
"confidence": "medium",
"first_rated": null,
"rated_before_review": null,
"unconfirmed_sub_claim": false
},
"orphan-and-dangling-blocks": {
"name": "Unreferenced blocks and dangling references",
"category": "content-model",
"status": "to-finish",
"effort": "S",
"sites": [
"storefront-tanstack",
"blog-tanstack"
],
"summary": "A dangling reference used to return null; now it fails the parent block, and one in `seo` throws. There's no validation tool, and one reading of the release rule would skip every storefront release because of ~20 unregistered types.",
"docs": [
"blocks",
"api-reference",
"renames-and-migrations",
"releases-and-deployment",
"rendering"
],
"confidence": "high",
"first_rated": null,
"rated_before_review": null,
"unconfirmed_sub_claim": false
},
"content-schema-drift": {
"name": "Content drift from current props / schemas",
"category": "content-model",
"status": "to-finish",
"effort": "M",
"sites": [
"storefront-tanstack",
"blog-tanstack",
"faststore"
],
"summary": "Stored inputs pass through unvalidated, and no documented tool does the 'validate saved content' step. Drift is already live: the storefront's Newsletter content stores a flat shape its Props no longer read.",
"docs": [
"schema",
"api-reference",
"renames-and-migrations",
"releases-and-deployment"
],
"confidence": "high",
"first_rated": null,
"rated_before_review": null,
"unconfirmed_sub_claim": false
},
"rich-text-html-props": {
"name": "Rich text / raw HTML props",
"category": "content-model",
"status": "to-finish",
"effort": "S",
"sites": [
"storefront-tanstack",
"blog-tanstack",
"faststore"
],
"summary": "Only `@format rich-text` is documented; `html`, `rich-text-inline`, `textarea`, `markdown`, alias-name detection and sanitization aren't, and FastStore's Lexical fields need converting.",
"docs": [
"routing",
"schema",
"rendering"
],
"confidence": "medium",
"first_rated": null,
"rated_before_review": "done",
"unconfirmed_sub_claim": false
},
"nested-section-props": {
"name": "Block-typed props (nested blocks)",
"category": "content-model",
"status": "to-finish",
"effort": "S",
"sites": [
"storefront-tanstack"
],
"summary": "The rule is documented: a field typed as the resolved value (`product: Product`, `sections: ReactNode[]`) takes any block whose function returns that type (`T` or `Promisedeco content computes it the same way), and there's no lenient mode or site-editor-shaped schema.",
"docs": [
"quickstart",
"blocks",
"api-reference",
"tanstack-start-descriptors",
"hosted-releases-internals",
"schema",
"releases-and-drafts",
"studio-compatibility",
"renames-and-migrations"
],
"confidence": "medium",
"first_rated": null,
"rated_before_review": null,
"unconfirmed_sub_claim": false
},
"site-config-block": {
"name": "Site config block / global settings",
"category": "config",
"status": "to-finish",
"effort": "M",
"sites": [
"storefront-tanstack",
"blog-tanstack",
"faststore"
],
"summary": "Today the binding resolves the site's theme, globals and page blocks into every page. In the next major, SEO-default merging and global-block injection move to app code, there's no singleton concept, and `site/apps/site.ts` isn't in the alias bridge.",
"docs": [
"routing",
"schema",
"blocks",
"api-reference",
"renames-and-migrations",
"studio-compatibility"
],
"confidence": "medium",
"first_rated": null,
"rated_before_review": null,
"unconfirmed_sub_claim": false
},
"app-installation-and-store-config": {
"name": "App installation blocks, autoconfig and store config",
"category": "config",
"status": "to-build",
"effort": "L",
"sites": [
"storefront-tanstack",
"blog-tanstack",
"faststore"
],
"summary": "There's no concept of an app: no config for app loaders, no autoconfig, no secret resolution, no `apps` manifest group and no encrypt endpoint, so the site editor can't save secret fields.",
"docs": [
"blocks",
"design-decisions",
"studio-compatibility",
"schema",
"releases-and-drafts",
"api-reference",
"tanstack-start-descriptors"
],
"confidence": "high",
"first_rated": null,
"rated_before_review": null,
"unconfirmed_sub_claim": false
},
"env-vars-and-secrets": {
"name": "Environment variables and secrets",
"category": "config",
"status": "to-finish",
"effort": "M",
"sites": [
"storefront-tanstack",
"blog-tanstack",
"faststore"
],
"summary": "DECO_SITE_TOKEN's lifecycle is undocumented, there's no channel option, and a production deploy that forgets the token silently serves bundled content. There's no secret story either: the decryptor for secrets stored in content is off the documented surface.",
"docs": [
"api-reference",
"tanstack-start-descriptors",
"nextjs",
"releases-and-drafts",
"releases-and-deployment",
"caching"
],
"confidence": "medium",
"first_rated": null,
"rated_before_review": null,
"unconfirmed_sub_claim": false
},
"build-time-site-globals-snapshot": {
"name": "Build-time site-globals snapshot workaround",
"category": "config",
"status": "goes-away",
"effort": "S",
"sites": [
"blog-tanstack"
],
"summary": "A workaround for a current-framework bug, with nothing to port. Half its call sites are server-side, so the site needs a small AsyncLocalStorage hand-off, and the snapshot's defect (edits never reach draft preview) goes away.",
"docs": [
"blocks",
"routing",
"tanstack-start-descriptors",
"releases-and-deployment",
"releases-and-drafts"
],
"confidence": "high",
"first_rated": null,
"rated_before_review": null,
"unconfirmed_sub_claim": false
},
"app-domain-types": {
"name": "App domain types driving the site editor's schema",
"category": "config",
"status": "to-finish",
"effort": "M",
"sites": [
"blog-tanstack"
],
"summary": "The mechanism is documented but not the conventions apps-blog relies on: type-alias formats like `ImageWidget`, and `@titleBy`, `@hide` and `@widget`. Without them the blog's forms degrade to plain text inputs.",
"docs": [
"schema",
"quickstart",
"routing",
"studio-compatibility"
],
"confidence": "medium",
"first_rated": "done",
"rated_before_review": null,
"unconfirmed_sub_claim": false
},
"worker-server-entry": {
"name": "Worker/server entry composition",
"category": "runtime-deploy",
"status": "to-finish",
"effort": "M",
"sites": [
"storefront-tanstack",
"blog-tanstack",
"faststore"
],
"summary": "Only the CMS and draft slice of the entry is documented. Site editor routes, the edge cache, purge, security headers and OTel have no home, the draft cookie is SameSite=Lax, and `?__draft=off` never exits preview.",
"docs": [
"tanstack-start-descriptors",
"api-reference",
"releases-and-drafts",
"nextjs",
"caching",
"studio-compatibility",
"internals"
],
"confidence": "high",
"first_rated": null,
"rated_before_review": null,
"unconfirmed_sub_claim": false
},
"csp-security-headers": {
"name": "CSP and security headers",
"category": "runtime-deploy",
"status": "site-code",
"effort": "S",
"sites": [
"storefront-tanstack",
"blog-tanstack"
],
"summary": "Headers are a few lines of app code, but after migration nothing sets HSTS, nosniff, Referrer-Policy or a framing policy, and the origins the site editor needs in frame-ancestors are undocumented.",
"docs": [
"how-it-works",
"tanstack-start-descriptors",
"nextjs",
"studio-compatibility"
],
"confidence": "high",
"first_rated": null,
"rated_before_review": null,
"unconfirmed_sub_claim": false
},
"ab-traffic-split": {
"name": "Migration A/B traffic split",
"category": "runtime-deploy",
"status": "to-build",
"effort": "S",
"sites": [
"storefront-tanstack"
],
"summary": "Nothing gives `withABTesting` a home, and it isn't few-line app code. It also needs to bypass draft requests by default.",
"docs": [
"api-reference",
"internals",
"quickstart"
],
"confidence": "high",
"first_rated": null,
"rated_before_review": null,
"unconfirmed_sub_claim": false
},
"hosting-and-deploy-config": {
"name": "Hosting and deploy configuration",
"category": "runtime-deploy",
"status": "to-finish",
"effort": "M",
"sites": [
"storefront-tanstack",
"blog-tanstack",
"faststore"
],
"summary": "Only the single-instance happy path is documented: a cron or webhook `update()` refreshes one instance, serverless Node gives no staleness bound, and per-PR preview deploys swap in the production release.",
"docs": [
"tanstack-start-descriptors",
"tanstack-start-rsc",
"nextjs",
"api-reference",
"releases-and-deployment"
],
"confidence": "medium",
"first_rated": null,
"rated_before_review": null,
"unconfirmed_sub_claim": false
},
"content-storage-and-delivery": {
"name": "Content storage, snapshot and delivery",
"category": "runtime-deploy",
"status": "to-finish",
"effort": "L",
"sites": [
"storefront-tanstack",
"blog-tanstack",
"faststore"
],
"summary": "The file model matches, but filename encoding, bundling, the release service and skew protection are unspecified. Content is meant to be validated against the code in CI by `deco check`, which isn't built yet.",
"docs": [
"quickstart",
"blocks",
"api-reference",
"tanstack-start-descriptors",
"releases-and-deployment",
"hosted-releases-internals",
"studio-compatibility"
],
"confidence": "high",
"first_rated": null,
"rated_before_review": null,
"unconfirmed_sub_claim": false
},
"fast-deploy-kv": {
"name": "Fast Deploy (KV-first content)",
"category": "runtime-deploy",
"status": "to-finish",
"effort": "S",
"sites": [
"storefront-tanstack",
"blog-tanstack"
],
"summary": "`remoteLoader` will check once a minute (configurable with `interval`), cold isolates serve the deployed content module until their first check, a webhook reaches one isolate, and the KV loader is a template recipe, not yet in the templates. Impact on these sites is low: none serves content from KV today.",
"docs": [
"api-reference",
"releases-and-deployment",
"hosted-releases-internals"
],
"confidence": "high",
"first_rated": "done",
"rated_before_review": null,
"unconfirmed_sub_claim": false
},
"ci-and-release-workflows": {
"name": "CI, content regen and release workflows",
"category": "runtime-deploy",
"status": "to-finish",
"effort": "M",
"sites": [
"storefront-tanstack",
"blog-tanstack",
"faststore"
],
"summary": "The CI job is a few lines, but the CLI doesn't emit what the site editor reads and has no `deco check` yet. The blog's `regen-blocks.yml` is its live content-delivery path today; deleting it early freezes its content.",
"docs": [
"schema",
"releases-and-deployment",
"router-internals",
"studio-compatibility",
"renames-and-migrations"
],
"confidence": "high",
"first_rated": "site-code",
"rated_before_review": null,
"unconfirmed_sub_claim": false
},
"root-document-layout": {
"name": "Root document and layout",
"category": "runtime-deploy",
"status": "to-finish",
"effort": "M",
"sites": [
"storefront-tanstack",
"blog-tanstack",
"faststore"
],
"summary": "The document shell is app code, but the site editor bridge and the `section[data-manifest-key]` marker it needs are neither shipped nor documented. Dropping the DECO.events bootstrap also silently breaks OneDollarStats.",
"docs": [
"tanstack-start-descriptors",
"nextjs",
"rendering",
"studio-compatibility"
],
"confidence": "high",
"first_rated": null,
"rated_before_review": null,
"unconfirmed_sub_claim": false
},
"codegen-pipeline": {
"name": "Codegen and build pipeline",
"category": "build",
"status": "to-finish",
"effort": "M",
"sites": [
"storefront-tanstack",
"blog-tanstack"
],
"summary": "`deco schema` and a hand-written block map replace the registries, `deco content` (planned) generates the content module for every runtime, but there's no `deco check` to validate content against the code yet",
"docs": [
"schema",
"blocks",
"tanstack-start-descriptors",
"releases-and-deployment",
"hosted-releases-internals",
"renames-and-migrations",
"studio-compatibility"
],
"confidence": "high",
"first_rated": null,
"rated_before_review": null,
"unconfirmed_sub_claim": false
},
"bundler-config": {
"name": "Vite config",
"category": "build",
"status": "to-finish",
"effort": "S",
"sites": [
"storefront-tanstack",
"blog-tanstack"
],
"summary": "The guide configs build, but nothing replaces decoVitePlugin's dev and site editor duties: schema regeneration, the site editor tunnel, the build hash and block preloads. Next also needs transpilePackages and file-tracing notes.",
"docs": [
"how-it-works",
"tanstack-start-descriptors",
"tanstack-start-rsc",
"nextjs",
"internals"
],
"confidence": "medium",
"first_rated": null,
"rated_before_review": null,
"unconfirmed_sub_claim": true
},
"faststore-cli-overlay": {
"name": "FastStore CLI .faststore overlay",
"category": "build",
"status": "to-build",
"effort": "L",
"sites": [
"faststore"
],
"summary": "The overlay goes away by design, but the move off it has no guide and no serverless deployment note (the content importer is handled outside this roadmap). Everything the overlay supplied becomes app code, and its imports of core internals, `@faststore/core` and `@generated` have to go.",
"docs": [
"nextjs",
"how-it-works",
"schema",
"blocks",
"api-reference"
],
"confidence": "high",
"first_rated": null,
"rated_before_review": "goes-away",
"unconfirmed_sub_claim": false
},
"framework-import-surface": {
"name": "Framework import surface and compat shims",
"category": "build",
"status": "to-build",
"effort": "L",
"sites": [
"storefront-tanstack",
"blog-tanstack",
"faststore"
],
"summary": "These docs cover about 12 CMS-core symbols and say nothing about the 7.x sdk, hooks, admin or binding tiers that apps-* and the telemetry depend on. Widget aliases are missing, and there's no 7.x to next codemod.",
"docs": [
"api-reference",
"matchers-and-variants",
"routing",
"blocks",
"schema",
"internals",
"upstream-clients"
],
"confidence": "high",
"first_rated": null,
"rated_before_review": null,
"unconfirmed_sub_claim": false
},
"core-patches": {
"name": "patch-package patches to core",
"category": "build",
"status": "site-code",
"effort": "S",
"sites": [
"faststore"
],
"summary": "The patches go away, but the behaviours they add must be re-created in site code.",
"docs": [
"nextjs",
"rendering",
"blocks"
],
"confidence": "high",
"first_rated": null,
"rated_before_review": "goes-away",
"unconfirmed_sub_claim": false
},
"dev-tooling-and-repo-hygiene": {
"name": "Dev tooling, quality gates and repo hygiene",
"category": "build",
"status": "site-code",
"effort": "S",
"sites": [
"storefront-tanstack",
"blog-tanstack",
"faststore"
],
"summary": "Ordinary app work, and the CI drift check is one line, but there's no `deco check` content validator yet. Sites' own lint and quality scripts carry over as app scripts.",
"docs": [
"schema",
"router-internals",
"renames-and-migrations"
],
"confidence": "high",
"first_rated": null,
"rated_before_review": null,
"unconfirmed_sub_claim": false
},
"legacy-runtime-leftovers": {
"name": "Legacy Deno/Fresh leftovers",
"category": "build",
"status": "goes-away",
"effort": "S",
"sites": [
"storefront-tanstack",
"blog-tanstack"
],
"summary": "Dead Deno and Fresh files, with nothing to port.",
"docs": [
"tanstack-start-descriptors",
"releases-and-drafts",
"api-reference",
"caching"
],
"confidence": "high",
"first_rated": null,
"rated_before_review": null,
"unconfirmed_sub_claim": false
},
"favicon-generation": {
"name": "Build-time favicon generation",
"category": "build",
"status": "site-code",
"effort": "S",
"sites": [
"faststore"
],
"summary": "`metadata.icons` does it in one line.",
"docs": [
"rendering",
"nextjs"
],
"confidence": "high",
"first_rated": null,
"rated_before_review": null,
"unconfirmed_sub_claim": false
},
"e2e-lighthouse-config": {
"name": "E2E and Lighthouse config",
"category": "build",
"status": "site-code",
"effort": "S",
"sites": [
"faststore"
],
"summary": "Tests are the app's job. A 'resolve every page' smoke test needs a fake request context, and there's no framework harness, so every site writes the same test.",
"docs": [
"how-it-works",
"api-reference",
"renames-and-migrations",
"blocks"
],
"confidence": "high",
"first_rated": null,
"rated_before_review": null,
"unconfirmed_sub_claim": false
},
"ai-agent-instructions": {
"name": "AI-agent instructions",
"category": "build",
"status": "site-code",
"effort": "S",
"sites": [
"storefront-tanstack",
"faststore"
],
"summary": "Agent docs are repo content, but no canonical guidance ships, and the site editor's injected rules drift from the next major.",
"docs": [
"how-it-works",
"schema",
"quickstart"
],
"confidence": "high",
"first_rated": null,
"rated_before_review": null,
"unconfirmed_sub_claim": false
},
"workspace-packages": {
"name": "Sites and block types in workspace packages",
"category": "build",
"status": "to-finish",
"effort": "M",
"sites": [
"faststore"
],
"summary": "Undocumented: whether `deco schema` follows block types into a workspace or npm package, and how the Deco API and the site editor address a site that lives in a package inside a larger repository.",
"docs": [
"schema",
"releases-and-drafts",
"nextjs",
"api-reference",
"releases-and-deployment"
],
"confidence": "medium",
"first_rated": null,
"rated_before_review": null,
"unconfirmed_sub_claim": true
},
"theming-and-styling": {
"name": "Theming and styling",
"category": "design",
"status": "to-finish",
"effort": "M",
"sites": [
"storefront-tanstack",
"blog-tanstack",
"faststore"
],
"summary": "There's no pattern for site-wide content resolved outside the catch-all, so the theme streams late under Suspense and shifts the layout, and the theme and the page can come from different revisions.",
"docs": [
"blocks",
"renames-and-migrations",
"schema",
"rendering",
"releases-and-deployment",
"nextjs",
"studio-compatibility"
],
"confidence": "high",
"first_rated": null,
"rated_before_review": null,
"unconfirmed_sub_claim": false
},
"web-fonts": {
"name": "Web fonts",
"category": "design",
"status": "to-finish",
"effort": "S",
"sites": [
"storefront-tanstack",
"blog-tanstack",
"faststore"
],
"summary": "`googleFonts` has no home in the next-major packages and imports `sdk/fetchTimeout`. Making fonts editable also needs the CLI to link `font: Font` to loaders by return type, a rule these docs name but never define.",
"docs": [
"blocks",
"renames-and-migrations",
"caching",
"studio-compatibility",
"internals"
],
"confidence": "high",
"first_rated": null,
"rated_before_review": null,
"unconfirmed_sub_claim": false
},
"image-optimization": {
"name": "Image optimization",
"category": "design",
"status": "to-build",
"effort": "M",
"sites": [
"storefront-tanstack",
"blog-tanstack",
"faststore"
],
"summary": "Images aren't mentioned. Without a shipped URL builder, migrated sites serve full-size originals and ignore the site editor's quality choice, and without `format: image-uri` the site editor shows a text box instead of the image picker.",
"docs": [
"api-reference",
"internals",
"design-decisions",
"routing",
"schema"
],
"confidence": "high",
"first_rated": null,
"rated_before_review": null,
"unconfirmed_sub_claim": false
},
"i18n-and-currency": {
"name": "i18n and currency",
"category": "design",
"status": "site-code",
"effort": "S",
"sites": [
"storefront-tanstack",
"blog-tanstack",
"faststore"
],
"summary": "Locale is fixed per deployment, so the only framework need is cache keys. In the FastStore storefront, code that calls its own translation hook without `\"use client\"` throws as a Server Component until it's rewritten.",
"docs": [
"blocks",
"matchers-and-variants",
"caching",
"nextjs"
],
"confidence": "high",
"first_rated": null,
"rated_before_review": null,
"unconfirmed_sub_claim": false
},
"otel-observability": {
"name": "OTel and logging",
"category": "observability-analytics",
"status": "to-finish",
"effort": "L",
"sites": [
"storefront-tanstack",
"blog-tanstack",
"faststore"
],
"summary": "Sites trace inbound requests and page caches with their framework's own OpenTelemetry setup; the SDK's resolution, upstream and error measurements go wherever the `telemetry` option of `createCMS` points (your own OTLP collector or the hosted Deco CMS). Still open: `remoteLoader` fails silently, and spans around JSX blocks miss the upstream fetches.",
"docs": [
"telemetry",
"api-reference",
"hosted-releases-internals",
"releases-and-drafts",
"releases-and-deployment",
"troubleshooting",
"blocks",
"tanstack-start-descriptors",
"internals"
],
"confidence": "high",
"first_rated": null,
"rated_before_review": null,
"unconfirmed_sub_claim": false
},
"upstream-fetch-instrumentation": {
"name": "Upstream fetch instrumentation",
"category": "observability-analytics",
"status": "to-finish",
"effort": "M",
"sites": [
"storefront-tanstack",
"faststore"
],
"summary": "The storefront calls `createInstrumentedFetch(\"shopify\")` with no onComplete, so upstream metrics are dark today. The chokepoint rule is never stated, and there's no meter on Next or Node.",
"docs": [
"telemetry",
"blocks",
"rendering",
"internals",
"upstream-clients"
],
"confidence": "high",
"first_rated": null,
"rated_before_review": null,
"unconfirmed_sub_claim": false
},
"analytics-trackers": {
"name": "Analytics trackers",
"category": "observability-analytics",
"status": "to-finish",
"effort": "M",
"sites": [
"storefront-tanstack",
"blog-tanstack",
"faststore"
],
"summary": "Trackers carry over, but the DECO.events bootstrap is private and copied three times, and experiment results break: the site editor keys them on the random matcher's saved-entry name, which a pure block function never sees.",
"docs": [
"analytics",
"nextjs",
"matchers-and-variants",
"design-decisions",
"studio-compatibility",
"renames-and-migrations",
"blocks",
"quickstart",
"rendering"
],
"confidence": "medium",
"first_rated": null,
"rated_before_review": null,
"unconfirmed_sub_claim": false
},
"ecommerce-analytics-events": {
"name": "E-commerce events",
"category": "observability-analytics",
"status": "to-finish",
"effort": "S",
"sites": [
"storefront-tanstack",
"faststore"
],
"summary": "Emitters are app code, but the receiving pipeline is mounted only by the bindings' DecoRootLayout, which the guides don't use, so every commerce event would drop silently.",
"docs": [
"rendering",
"nextjs",
"internals",
"analytics"
],
"confidence": "high",
"first_rated": null,
"rated_before_review": null,
"unconfirmed_sub_claim": false
}
}
}