@decocms/blocks 8.10.0 → 8.11.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (163) hide show
  1. package/dist/v8/cli/index.d.ts +1 -0
  2. package/dist/v8/cli/index.d.ts.map +1 -1
  3. package/dist/v8/cli/index.js +1 -0
  4. package/dist/v8/cli/index.js.map +1 -1
  5. package/dist/v8/cli/run.d.ts +2 -0
  6. package/dist/v8/cli/run.d.ts.map +1 -1
  7. package/dist/v8/cli/run.js +30 -1
  8. package/dist/v8/cli/run.js.map +1 -1
  9. package/dist/v8/cli/skills.d.ts +25 -0
  10. package/dist/v8/cli/skills.d.ts.map +1 -0
  11. package/dist/v8/cli/skills.js +70 -0
  12. package/dist/v8/cli/skills.js.map +1 -0
  13. package/package.json +3 -2
  14. package/skills/deco-apps/SKILL.md +82 -0
  15. package/skills/deco-apps/references/algolia.md +51 -0
  16. package/skills/deco-apps/references/commerce-types.md +132 -0
  17. package/skills/deco-apps/references/instrumented-fetch.md +144 -0
  18. package/skills/deco-apps/references/magento.md +55 -0
  19. package/skills/deco-apps/references/messaging.md +76 -0
  20. package/skills/deco-apps/references/shopify.md +69 -0
  21. package/skills/deco-apps/references/vendored-loaders.md +135 -0
  22. package/skills/deco-apps/references/vtex-cookies-auth.md +146 -0
  23. package/skills/deco-apps/references/vtex.md +150 -0
  24. package/skills/deco-apps/references/wake.md +75 -0
  25. package/skills/deco-cms-schema/SKILL.md +80 -0
  26. package/skills/deco-cms-schema/references/annotations.md +147 -0
  27. package/skills/deco-cms-schema/references/content-hygiene.md +91 -0
  28. package/skills/deco-cms-schema/references/formats-and-widgets.md +112 -0
  29. package/skills/deco-cms-schema/references/shapes-that-break-the-form.md +165 -0
  30. package/skills/deco-cms-schema/references/types-to-fields.md +112 -0
  31. package/skills/deco-go-live/SKILL.md +127 -0
  32. package/skills/deco-go-live/references/content-releases.md +90 -0
  33. package/skills/deco-go-live/references/process.md +106 -0
  34. package/skills/deco-go-live/references/proxy-headers-checkout.md +139 -0
  35. package/skills/deco-go-live/references/qa-checklist-template.md +150 -0
  36. package/skills/deco-go-live/references/qa-inventory.md +120 -0
  37. package/skills/deco-go-live/references/react-spa.md +183 -0
  38. package/skills/deco-go-live/references/seo-analytics.md +114 -0
  39. package/skills/deco-go-live/references/traffic-ramp.md +87 -0
  40. package/skills/deco-go-live/references/worker-runtime.md +93 -0
  41. package/skills/deco-go-live/scripts/preflight.sh +221 -0
  42. package/skills/deco-images-media/SKILL.md +64 -0
  43. package/skills/deco-images-media/references/asset-upload.md +191 -0
  44. package/skills/deco-images-media/references/components-per-binding.md +167 -0
  45. package/skills/deco-images-media/references/providers-and-cdn.md +145 -0
  46. package/skills/deco-images-media/references/quality-and-lcp.md +93 -0
  47. package/skills/deco-images-media/references/troubleshooting.md +147 -0
  48. package/skills/deco-images-media/references/video.md +122 -0
  49. package/skills/deco-make-editable/SKILL.md +94 -0
  50. package/skills/deco-make-editable/references/a11y-and-e2e.md +104 -0
  51. package/skills/deco-make-editable/references/content-shapes.md +198 -0
  52. package/skills/deco-make-editable/references/from-figma.md +110 -0
  53. package/skills/deco-make-editable/references/i18n-fields.md +112 -0
  54. package/skills/deco-make-editable/references/inventory.md +79 -0
  55. package/skills/deco-make-editable/references/pixel-parity.md +175 -0
  56. package/skills/deco-make-editable/references/seeding-content.md +119 -0
  57. package/skills/deco-nextjs-site/SKILL.md +74 -0
  58. package/skills/deco-nextjs-site/references/caching.md +116 -0
  59. package/skills/deco-nextjs-site/references/metadata-seo.md +100 -0
  60. package/skills/deco-nextjs-site/references/proxy-and-drafts.md +177 -0
  61. package/skills/deco-nextjs-site/references/rendering.md +171 -0
  62. package/skills/deco-nextjs-site/references/setup.md +190 -0
  63. package/skills/deco-nextjs-site/references/studio-bridge.md +130 -0
  64. package/skills/deco-site-authoring/SKILL.md +75 -0
  65. package/skills/deco-site-authoring/references/lazy-blocks.md +155 -0
  66. package/skills/deco-site-authoring/references/loaders.md +192 -0
  67. package/skills/deco-site-authoring/references/pages.md +156 -0
  68. package/skills/deco-site-authoring/references/review-before-publish.md +95 -0
  69. package/skills/deco-site-authoring/references/sections.md +158 -0
  70. package/skills/deco-site-authoring/references/seo.md +116 -0
  71. package/skills/deco-site-workflow/SKILL.md +92 -0
  72. package/skills/deco-site-workflow/references/check.md +116 -0
  73. package/skills/deco-site-workflow/references/cli-reference.md +104 -0
  74. package/skills/deco-site-workflow/references/content-layout.md +93 -0
  75. package/skills/deco-site-workflow/references/content-sync.md +146 -0
  76. package/skills/deco-site-workflow/references/delivery.md +51 -0
  77. package/skills/deco-site-workflow/references/deploy.md +87 -0
  78. package/skills/deco-site-workflow/references/schema.md +173 -0
  79. package/skills/deco-site-workflow/references/serve-and-studio.md +138 -0
  80. package/skills/deco-storefront-caching/SKILL.md +67 -0
  81. package/skills/deco-storefront-caching/references/cache-keys.md +129 -0
  82. package/skills/deco-storefront-caching/references/case-study.md +82 -0
  83. package/skills/deco-storefront-caching/references/egress-traps.md +153 -0
  84. package/skills/deco-storefront-caching/references/nextjs.md +60 -0
  85. package/skills/deco-storefront-caching/references/perf-guardrails-e2e.md +123 -0
  86. package/skills/deco-storefront-caching/references/verification.md +136 -0
  87. package/skills/deco-storefront-caching/references/worker-page-cache.md +160 -0
  88. package/skills/deco-storefront-caching/scripts/html-anatomy.mjs +97 -0
  89. package/skills/deco-storefront-performance/SKILL.md +81 -0
  90. package/skills/deco-storefront-performance/references/cls-third-party.md +90 -0
  91. package/skills/deco-storefront-performance/references/hydration.md +116 -0
  92. package/skills/deco-storefront-performance/references/loaders-n-plus-1.md +107 -0
  93. package/skills/deco-storefront-performance/references/navigation-ux.md +130 -0
  94. package/skills/deco-storefront-performance/references/payload-trim.md +163 -0
  95. package/skills/deco-storefront-performance/references/render-location.md +152 -0
  96. package/skills/deco-storefront-performance/references/request-dedupe.md +147 -0
  97. package/skills/deco-storefront-performance/references/trace-reading.md +79 -0
  98. package/skills/deco-storefront-performance/references/worker-memory.md +176 -0
  99. package/skills/deco-tanstack-site/SKILL.md +68 -0
  100. package/skills/deco-tanstack-site/references/document-and-security.md +155 -0
  101. package/skills/deco-tanstack-site/references/router-and-navigation.md +137 -0
  102. package/skills/deco-tanstack-site/references/routes-and-pages.md +183 -0
  103. package/skills/deco-tanstack-site/references/server-functions.md +123 -0
  104. package/skills/deco-tanstack-site/references/setup.md +153 -0
  105. package/skills/deco-tanstack-site/references/worker-entry.md +152 -0
  106. package/skills/deco-v7-to-v8-migration/SKILL.md +122 -0
  107. package/skills/deco-v7-to-v8-migration/references/caching-and-privacy.md +10 -0
  108. package/skills/deco-v7-to-v8-migration/references/content.md +25 -0
  109. package/skills/deco-v7-to-v8-migration/references/editor-forms.md +27 -0
  110. package/skills/deco-v7-to-v8-migration/references/faststore.md +40 -0
  111. package/skills/deco-v7-to-v8-migration/references/framework-code.md +53 -0
  112. package/skills/deco-v7-to-v8-migration/references/hosted-releases.md +16 -0
  113. package/skills/deco-v7-to-v8-migration/references/import-map.md +81 -0
  114. package/skills/deco-v7-to-v8-migration/references/legacy-names.md +33 -0
  115. package/skills/deco-v7-to-v8-migration/references/manual-steps.md +10 -0
  116. package/skills/deco-v7-to-v8-migration/references/native-apps.md +43 -0
  117. package/skills/deco-v7-to-v8-migration/references/nextjs.md +19 -0
  118. package/skills/deco-v7-to-v8-migration/references/parity.md +66 -0
  119. package/skills/deco-v7-to-v8-migration/references/rendering.md +13 -0
  120. package/skills/deco-v7-to-v8-migration/references/running-the-script.md +29 -0
  121. package/skills/deco-v7-to-v8-migration/references/script-steps.md +13 -0
  122. package/skills/deco-v7-to-v8-migration/references/server-functions.md +15 -0
  123. package/skills/deco-v7-to-v8-migration/references/sibling-port.md +11 -0
  124. package/skills/deco-v7-to-v8-migration/references/site-code.md +15 -0
  125. package/skills/deco-v7-to-v8-migration/references/telemetry.md +10 -0
  126. package/skills/deco-v7-to-v8-migration/references/verify.md +20 -0
  127. package/skills/deco-v7-to-v8-migration/scripts/apps.ts +297 -0
  128. package/skills/deco-v7-to-v8-migration/scripts/asyncRendering.ts +73 -0
  129. package/skills/deco-v7-to-v8-migration/scripts/blockMap.ts +584 -0
  130. package/skills/deco-v7-to-v8-migration/scripts/ciSchemaCheck.ts +145 -0
  131. package/skills/deco-v7-to-v8-migration/scripts/compat.ts +357 -0
  132. package/skills/deco-v7-to-v8-migration/scripts/content.ts +121 -0
  133. package/skills/deco-v7-to-v8-migration/scripts/experiments.ts +81 -0
  134. package/skills/deco-v7-to-v8-migration/scripts/framework.ts +61 -0
  135. package/skills/deco-v7-to-v8-migration/scripts/imageCopy.ts +276 -0
  136. package/skills/deco-v7-to-v8-migration/scripts/imageModule.ts +285 -0
  137. package/skills/deco-v7-to-v8-migration/scripts/imports.ts +942 -0
  138. package/skills/deco-v7-to-v8-migration/scripts/invoke.ts +624 -0
  139. package/skills/deco-v7-to-v8-migration/scripts/legacyNames.ts +45 -0
  140. package/skills/deco-v7-to-v8-migration/scripts/main.ts +59 -0
  141. package/skills/deco-v7-to-v8-migration/scripts/matchers.ts +41 -0
  142. package/skills/deco-v7-to-v8-migration/scripts/migrate.ts +176 -0
  143. package/skills/deco-v7-to-v8-migration/scripts/redirects.ts +455 -0
  144. package/skills/deco-v7-to-v8-migration/scripts/report.ts +50 -0
  145. package/skills/deco-v7-to-v8-migration/scripts/scaffold.ts +1119 -0
  146. package/skills/deco-v7-to-v8-migration/scripts/secrets.ts +35 -0
  147. package/skills/deco-v7-to-v8-migration/scripts/sectionLoaders.ts +216 -0
  148. package/skills/deco-v7-to-v8-migration/scripts/siteSettings.ts +261 -0
  149. package/skills/deco-v7-to-v8-migration/scripts/stubs.ts +388 -0
  150. package/skills/deco-v7-to-v8-migration/scripts/tsconfig.json +7 -0
  151. package/skills/deco-v7-to-v8-migration/scripts/vendor.ts +249 -0
  152. package/skills/deco-v7-to-v8-migration/scripts/vtexInvoke.ts +240 -0
  153. package/skills/deco-v7-to-v8-migration/scripts/walk.ts +30 -0
  154. package/skills/deco-variants/SKILL.md +57 -0
  155. package/skills/deco-variants/references/caching-variants.md +63 -0
  156. package/skills/deco-variants/references/custom-matchers.md +83 -0
  157. package/skills/deco-variants/references/draft-preview.md +59 -0
  158. package/skills/deco-variants/references/experiments-and-campaigns.md +104 -0
  159. package/skills/deco-variants/references/multivariate.md +85 -0
  160. package/skills/deco-variants/references/v7-matchers.md +71 -0
  161. package/src/v8/cli/index.ts +1 -0
  162. package/src/v8/cli/run.ts +35 -1
  163. package/src/v8/cli/skills.ts +91 -0
@@ -0,0 +1,152 @@
1
+ # The worker entry
2
+
3
+ `src/worker-entry.ts` is the Worker (`wrangler.jsonc` `main`). It puts `createDecoWorker` from
4
+ `@decocms/tanstack/worker` in front of TanStack Start's server entry. The full contract is
5
+ `packages/tanstack/README.md`; this file is what a site needs to wire and debug it.
6
+
7
+ ## The smallest entry
8
+
9
+ ```ts
10
+ import { createDecoWorker } from "@decocms/tanstack/worker";
11
+ import handler, { createServerEntry } from "@tanstack/react-start/server-entry";
12
+ import { cms } from "./cms";
13
+
14
+ export default createDecoWorker({
15
+ serverEntry: createServerEntry({ fetch: handler.fetch }),
16
+ cms,
17
+ dev: import.meta.env.DEV,
18
+ });
19
+ ```
20
+
21
+ This caches no page: every request renders. A site with a page cache starts from
22
+ `examples/tanstack-worker-smoke/src/worker-entry.ts` (v7's edge cache on the Cloudflare Cache API,
23
+ its profiles and its purge route) and owns it from there. How to key and purge it:
24
+ `deco-storefront-caching`.
25
+
26
+ ## What it always does
27
+
28
+ No option turns these off.
29
+
30
+ - `/deco/_liveness` answers `OK`. v7's admin paths (`/deco/*`, `/live/*`, `/.decofile`) answer 404.
31
+ v8 has no `/deco/invoke`, `/deco/meta` or `/deco/render`.
32
+ - **Drafts.** `?__draft=<pointer>` or the `__deco_draft` cookie previews a draft, on the hosts the
33
+ CMS allows (`createCMS` `preview.hosts`, plus the ones Studio writes into the release). Any request
34
+ with a draft signal (`?__draft=off` too) is a preview: it never reaches `pageCache` and answers
35
+ `Cache-Control: max-age=0, no-cache, must-revalidate`, `Vary: Cookie` and
36
+ `X-Robots-Tag: noindex, nofollow`. A link to a
37
+ draft that can't be read renders the release, never a 500. A link on another host gets the
38
+ release.
39
+ - **The CMS redirects**, for `GET`/`HEAD` page requests, before anything else. Server-function
40
+ calls, assets and `/_build` are not redirected.
41
+ - **The visitor and the tests.** It reads the visitor (`deco_segment` cookie, or a new one) and
42
+ decides each test and campaign once, then hands them to the app on request headers it strips
43
+ from incoming requests (below). The visitor cookie goes out on a first visit only, and never on a request that renders a draft
44
+ or an old release.
45
+ - **Headers on the way out**: the security headers and Studio's CSP on HTML
46
+ ([`document-and-security.md`](./document-and-security.md)); `Cache-Control: public,
47
+ max-age=31536000, immutable` on fingerprinted assets; one `Set-Cookie` per cookie (the last one
48
+ for each name + Domain + Path); `x-page-status` turned into the status;
49
+ `CDN-Cache-Control: no-store` on any response that sets none.
50
+ - **A request with `Authorization`** never reaches `pageCache` and answers
51
+ `Cache-Control: private, no-cache, no-store, must-revalidate`.
52
+ - **`http.server.request.duration`** for every request, to the CMS's telemetry (nothing without a
53
+ token or endpoint).
54
+
55
+ Don't rebuild any of these in the site: a hand-written draft check that reads `?__draft=` lets
56
+ anyone bypass the cache on production.
57
+
58
+ ## Options
59
+
60
+ | Option | For |
61
+ |---|---|
62
+ | `serverEntry` | TanStack Start's server entry. Required. |
63
+ | `cms` | The site's CMS. Required. |
64
+ | `dev` | `import.meta.env.DEV`: `pageCache` is never called, and loopback may frame the site. |
65
+ | `csp` | `{ enforce?, reportOnly?, frameAncestors? }`: the site's Content-Security-Policy. Studio's origins are always added. |
66
+ | `studioOrigins` | The Studio origins the CSP allows. Set the same list on `DecoDocument`. |
67
+ | `pageCache` | `(page) => Promise<Response>`: the site's cache. Called only for requests `isCacheable` accepts. |
68
+ | `preload` | `{ styles?, fonts? }`: `Link: rel=preload` headers on every HTML response the app renders. |
69
+ | `routes` | `(request, env, ctx) => Response \| null`: the escape hatch. |
70
+
71
+ ## `routes`: requests the site answers itself
72
+
73
+ `routes` runs after the CMS redirects and before anything else. Return a `Response` to answer
74
+ (a commerce proxy, a sitemap, an A/B split to another origin), or `null` to let the worker serve
75
+ the request.
76
+
77
+ ```ts
78
+ export default createDecoWorker({
79
+ serverEntry: createServerEntry({ fetch: handler.fetch }),
80
+ cms,
81
+ dev: import.meta.env.DEV,
82
+ routes: (request, env) => {
83
+ const url = new URL(request.url);
84
+ if (url.pathname.startsWith("/checkout")) return proxyCheckout(request, env);
85
+ return null;
86
+ },
87
+ });
88
+ ```
89
+
90
+ Its response still gets the security headers and `CDN-Cache-Control: no-store` (unless it sets
91
+ one), but no `preload` hints: it is another origin's page. A v7 A/B split on Workers KV has a
92
+ ready handler for `routes`: `abTestingRoutes` from `@decocms/compat-v7/tanstack/worker`.
93
+
94
+ Code that must run around everything (a geo cookie, a purge endpoint) wraps the worker's `fetch`
95
+ instead, as the example does with `POST /_cache/purge`:
96
+
97
+ ```ts
98
+ const worker = createDecoWorker<Env>({
99
+ serverEntry: createServerEntry({ fetch: handler.fetch }),
100
+ cms,
101
+ dev: import.meta.env.DEV,
102
+ pageCache,
103
+ });
104
+ export default {
105
+ fetch(request: Request, env: Env, ctx: ExecutionContextLike) {
106
+ if (request.method === "POST" && new URL(request.url).pathname === "/_cache/purge") {
107
+ return purge(request, env);
108
+ }
109
+ return worker.fetch(request, env, ctx);
110
+ },
111
+ };
112
+ ```
113
+
114
+ ## What the app receives
115
+
116
+ The worker sets these on the request it passes to TanStack Start, and removes copies sent from
117
+ outside:
118
+
119
+ | Header | Holds | Read with (`@decocms/tanstack/server`) |
120
+ |---|---|---|
121
+ | `x-deco-version` | The draft or old release the request renders | `requestVersion()` |
122
+ | `x-deco-visitor` | The visitor | `requestVisitor()` |
123
+ | `x-deco-assignments` | Each test and campaign, on or off | `requestAssignments()` |
124
+ | `x-deco-release-check` | The draft's check of the latest release | (used by `contentClient`) |
125
+
126
+ `contentClient(cms, request)` builds the content client from all of them. Each helper defaults to
127
+ the current request (`getRequest()`). The header names are exported from `@decocms/tanstack`
128
+ (`VERSION_HEADER`, `VISITOR_HEADER`, `ASSIGNMENTS_HEADER`) for code that sets its own headers.
129
+
130
+ A request that reaches the app without the worker carries whatever headers it came with. Only
131
+ expose the app through the worker.
132
+
133
+ ## `pageCache` in one paragraph
134
+
135
+ `pageCache(page)` gets `page.request`, `page.url`, `page.visitor`, `page.assignments`,
136
+ `page.device`, `env`, `ctx` and `page.render(scope?)`. Answer from your cache or call `render()`,
137
+ and set `X-Cache` (`HIT`, `STALE-HIT`, `STALE-ERROR`, `MISS`) so the request metric counts it.
138
+ The worker adds the visitor's first-visit cookie after `pageCache` answers: never store a
139
+ response that sets any other cookie. The key helpers (`assignmentsKey`, `cacheVersion`,
140
+ `detectDevice`, `segmentKey`, `segmentToken`, `isCacheable`, `serverFnPagePath`,
141
+ `DEGRADED_HEADER`) are all in `@decocms/tanstack/worker`. Everything else about the cache:
142
+ `deco-storefront-caching`.
143
+
144
+ ## Debugging
145
+
146
+ | Symptom | Look at |
147
+ |---|---|
148
+ | `/deco/invoke/...` answers 404 | Expected. Replace each call with a server function ([`server-functions.md`](./server-functions.md)). |
149
+ | A draft link shows the published page | The host isn't in the CMS's preview hosts. Add it to `createCMS({ preview: { hosts } })`. |
150
+ | A redirect works on reload but not on a client-side navigation | `openPage` must check the redirects block too ([`routes-and-pages.md`](./routes-and-pages.md)). |
151
+ | Studio can't frame the site | A `frame-ancestors` the site set itself, or `studioOrigins` set on one side only ([`document-and-security.md`](./document-and-security.md)). |
152
+ | The page renders but the status is 200 for a CMS "not found" page | Set `x-page-status` from the route's `headers`. |
@@ -0,0 +1,122 @@
1
+ ---
2
+ name: deco-v7-to-v8-migration
3
+ description: "@decocms/blocks 8 (the next major): moves a v7 Deco site (@decocms/blocks 7.x with @decocms/tanstack or @decocms/nextjs, @decocms/blocks-admin, @decocms/blocks-cli, v7 @decocms/apps-*) onto @decocms/blocks 8, the v8 bindings (@decocms/tanstack 8, @decocms/nextjs 8) and the thin @decocms/apps-* clients. Runs the one-time migration script (scripts/main.ts: block map with legacy aliases, vendored app loaders, content in .deco/blocks, v7 secrets listed for the deploy platform, import report), then guides the manual work it reports. Use when a site's package.json depends on @decocms/blocks ^7, @decocms/tanstack, @decocms/nextjs or @decocms/blocks-admin and should move to v8; when the report lists /deco/invoke calls, createDecoWorkerEntry, RequestContext, useCart or other v7 imports to replace; when deco check rejects migrated content; or when a migrated page, draft preview, editor form or parity run differs from v7. Replaces the unpublished @decocms/blocks-migrate package."
4
+ ---
5
+
6
+ # Deco v7 → v8 Migration
7
+
8
+ A script does the mechanical, content-safe part in one pass and prints the manual steps. Proven on `deco-sites/storefront-tanstack`, `deco-sites/demo-storefront`, `deco-sites/blog-tanstack` and four private VTEX storefronts (two ejected FastStore on Next.js, one TanStack Start, one non-ejected FastStore).
9
+
10
+ The spec is the docs page **Migrating from v7** (`/next/renames-and-migrations`). When this skill and the docs disagree, the docs win.
11
+
12
+ ## When this applies
13
+
14
+ - `package.json` depends on `@decocms/blocks` `^7`, and on `@decocms/tanstack` or `@decocms/nextjs`, `@decocms/blocks-admin`, `@decocms/blocks-cli` or v7 `@decocms/apps-*`.
15
+ - Saved content lives in `.deco/blocks/*.json`, or the site serves it at `/.decofile`.
16
+
17
+ **FastStore storefronts that aren't ejected** (FastStore owns the Next.js app) keep v7's seam with v8 behind it: follow [`references/faststore.md`](./references/faststore.md) for steps 2, 3 and 6. **Native or mobile apps** (bundled JSON, native rendering): the script still runs, but most manual steps don't apply; follow [`references/native-apps.md`](./references/native-apps.md).
18
+
19
+ Not for sites on `@decocms/start@6.x` (upgrade to 7.x first: v7's `@decocms/blocks-cli` ships `deco-upgrade-6-to-7`) or on Fresh/Deno (first the `deco-to-tanstack-migration` skill).
20
+
21
+ ## Prerequisites
22
+
23
+ 1. A clean working tree: the script edits files in place.
24
+ 2. **Install `@decocms/blocks@^8.4` before running the script** (not `^8`: `8.0.0` is an accidental v7 build). Keep the v7 `@decocms/apps-*` installed until the script has run: it vendors the app loaders your content calls from `node_modules`.
25
+ 3. `typescript` resolvable from the site (the import codemod parses `src/` with it).
26
+
27
+ ## Run
28
+
29
+ The script is `scripts/main.ts`. It resolves `@decocms/blocks` relative to its own files, so run it where that resolves to v8.
30
+
31
+ **From a `decocms/blocks` checkout on the v8 line** (run `bun install` there first):
32
+
33
+ ```bash
34
+ bun <blocks>/.agents/skills/deco-v7-to-v8-migration/scripts/main.ts --root <site>
35
+ # under Node: npx tsx <blocks>/.agents/skills/deco-v7-to-v8-migration/scripts/main.ts --root <site>
36
+ ```
37
+
38
+ **From an installed copy of the skill** (outside the repo): copy `scripts/` into the site first ([`references/running-the-script.md`](./references/running-the-script.md)).
39
+
40
+ | Flag | What it does |
41
+ |---|---|
42
+ | `--root <dir>` | The app root, the folder with the site's `package.json`. Default: `.` |
43
+ | `--decofile <file>` | Content to split into `.deco/blocks` when the site has none: the JSON the v7 site serves at `/.decofile`. |
44
+ | `--vtex-invoke keep\|v8` | No default. Needed if the site calls v7's VTEX invoke-map keys (else it stops, listing them): `keep` vendors v7's handler; `v8` uses the v8 client or a stub ([`references/server-functions.md`](./references/server-functions.md)). |
45
+
46
+ Steps, in order: **content** (redirects, settings and app blocks folded into `.deco/blocks` and `src/clients/`), **secrets**, **block map**, **invoke**, **scaffold**, **imports**, **scripts**. Each step: [`references/script-steps.md`](./references/script-steps.md).
47
+
48
+ Commit the script's output unedited as its own commit (`chore: run the v7-to-v8 migration`), apart from hand-written changes.
49
+
50
+ **A sibling site already migrated?** Port its v8 changes with a three-way merge per file ([`references/sibling-port.md`](./references/sibling-port.md)).
51
+
52
+ ## Review the report
53
+
54
+ The script prints **Done** and **Left to do**, grouped by step. Work through "Left to do" top to bottom: each line names its subject and where the replacement lives.
55
+
56
+ ## Manual steps
57
+
58
+ The full text of each step: [`references/manual-steps.md`](./references/manual-steps.md).
59
+
60
+ 1. **Dependencies**: `@decocms/blocks@^8.4`, the v8 binding and `@decocms/compat-v7` at the same version, and the v8 `@decocms/apps-<platform>` client; remove v7 packages and codegen once nothing imports them.
61
+ 2. **Check the page setup the script wrote** (`/next/tanstack-start-descriptors`, `/next/nextjs`), carry over what the site added to v7's page routes, and delete the v7 setup files and CI jobs.
62
+ 3. **Worker, drafts, Studio and images from the binding; v7's pure helpers from `@decocms/compat-v7`; the rest is site code** ([`references/framework-code.md`](./references/framework-code.md), [`references/site-code.md`](./references/site-code.md)).
63
+ 4. **Finish `/deco/invoke`**: validate the server functions the script wrote, and replace each stub in `src/migration-stubs.ts` ([`references/server-functions.md`](./references/server-functions.md)).
64
+ 5. **Fix the content `deco check` rejects** ([`references/content.md`](./references/content.md)).
65
+ 6. **Telemetry, analytics and previews** ([`references/telemetry.md`](./references/telemetry.md)).
66
+
67
+ ## Verify
68
+
69
+ ```bash
70
+ bunx deco schema && bunx deco content && bunx deco check # 0 errors
71
+ bun run typecheck && bun run build
72
+ ```
73
+
74
+ Then the rest of [`references/verify.md`](./references/verify.md): the committed schema, type errors counted against v7, drafts probed by hand, and a page-by-page parity run with every approved difference encoded as a rule ([`references/parity.md`](./references/parity.md)).
75
+
76
+ ## DO NOT
77
+
78
+ - Add compat shims that re-create v7 APIs (`useCart` from a package, `invoke`, `RequestContext`, `ctx`). `@decocms/compat-v7` is the one approved home of v7's pure helpers: import them from it, never copy them in. The rest is site code.
79
+ - Copy v7's worker entry, draft middleware, Studio bridge, preview badge or `Image` into the site: the bindings ship them. A site-local `invoke` object or `runInvoke(key)` dispatcher is the same shim.
80
+ - Strip `"use client"` from hook, event or browser-API components to render them.
81
+ - Rename saved type names. Content stores them; keep the v7 name as an alias (`/next/renames-and-migrations#rename-a-type-with-an-alias`).
82
+
83
+ ## When to load what
84
+
85
+ | Reference | Load it when |
86
+ |---|---|
87
+ | [`script-steps.md`](./references/script-steps.md) | You need what each script step did |
88
+ | [`manual-steps.md`](./references/manual-steps.md) | You work through the report's "Left to do" |
89
+ | [`verify.md`](./references/verify.md) | The site builds and you're checking it before review |
90
+ | [`import-map.md`](./references/import-map.md) | A v7 import needs its v8 replacement |
91
+ | [`legacy-names.md`](./references/legacy-names.md) | A saved `__resolveType` is an alias or one of the seven rewritten names |
92
+ | [`parity.md`](./references/parity.md) | Running the parity harness, approving differences, the pending state |
93
+ | [`editor-forms.md`](./references/editor-forms.md) | v7 `meta.gen.json` and v8 `schema.gen.json` forms differ |
94
+ | [`native-apps.md`](./references/native-apps.md) / [`faststore.md`](./references/faststore.md) | The site is a native app, or a FastStore storefront that isn't ejected |
95
+
96
+ ### Gotchas by subject
97
+
98
+ What the site migrations taught, one subject per file. Commit hashes refer to `deco-sites/storefront-tanstack` and `deco-sites/blog-tanstack` (some carry a "blog" prefix; look a hash up in both); the private sites have none.
99
+
100
+ | Reference | Subject |
101
+ |---|---|
102
+ | [`running-the-script.md`](./references/running-the-script.md) | Before the run (install order, vendoring, stale lockfiles), running from an installed copy, dependencies after |
103
+ | [`sibling-port.md`](./references/sibling-port.md) | What a three-way merge from a sibling site brings along |
104
+ | [`rendering.md`](./references/rendering.md) | No async rendering, streaming and hydration, awaited blocks, section wrappers, Tailwind |
105
+ | [`framework-code.md`](./references/framework-code.md) | The bindings: worker, drafts, Studio, images |
106
+ | [`site-code.md`](./references/site-code.md) | What stays site code: SEO, devices, cookies, commerce code, error reporting, A/B splits |
107
+ | [`server-functions.md`](./references/server-functions.md) | `/deco/invoke` → server functions |
108
+ | [`caching-and-privacy.md`](./references/caching-and-privacy.md) | Per-visitor data, QueryClient scope, draft bypass, hydration waits |
109
+ | [`nextjs.md`](./references/nextjs.md) | Next.js App Router: `@decocms/nextjs` drafts and proxy, `list('page')`, head order, Jest |
110
+ | [`hosted-releases.md`](./references/hosted-releases.md) | Hosted CMS instead of fast deploy, bundled content, v7 leftovers to delete |
111
+ | [`content.md`](./references/content.md) | `deco check` as a deploy gate, content it rejects, editing the bundled content, moving it to Studio's hosted CMS |
112
+ | [`telemetry.md`](./references/telemetry.md) | Telemetry params, resource attributes, dropped v7 bindings, analytics |
113
+
114
+ `scripts/` is the migration (`main.ts`), tested by the repo's `bun run test`.
115
+
116
+ ## After the migration
117
+
118
+ Other skills cover the site once it runs on v8:
119
+
120
+ - **`deco-go-live`**: launch QA beyond the parity run (cache checks, checkout headers, SEO), the traffic ladder and the first 72 hours.
121
+ - **`deco-tanstack-site`** / **`deco-nextjs-site`**: the binding's wiring, for changes after the migration.
122
+ - **`deco-storefront-caching`**: tuning the site-owned `pageCache`, cache keys and purges.
@@ -0,0 +1,10 @@
1
+ # Caching and privacy
2
+
3
+ From the site migrations; the sites and what the commit hashes refer to are listed in `SKILL.md` ("Gotchas by subject").
4
+
5
+ - **Keep per-visitor data out of the edge cache** (`844ce9f`): cache a GET server function only when its payload is page data; cart, user, wishlist, addresses answer `Cache-Control: private, no-store`, and the cache wrapper never stores such a response. Detect signed-in shoppers by the cookie the sign-in flow actually sets.
6
+ - **One QueryClient per router**, never per isolate: a shared one leaks the previous request's cart and user.
7
+ - v7's admin paths (`/deco/*`, `/live/*`, `/.decofile`) should answer 404, not a cacheable page. `createDecoWorker` does; on Next.js, check them in the parity run (`hosted-releases.md`).
8
+ - **The draft decision is the binding's.** v7's edge cache skipped a request with `?__draft=` or the draft cookie only on an allowed preview host; a hand-copied worker that checks the raw param lets anyone skip the cache on production (`?__draft=x`). `createDecoWorker` decides once per request with v7's allowlist, never calls the site's `pageCache` for a draft it accepted, and hands the page that draft (`contentClient(cms)`); on Next.js, `decideDraft` in the proxy does the same. Don't add a second draft check of your own.
9
+ - **A signed-in shopper never shares a cached page**: return `loggedIn: true` from `buildSegment` in the worker entry (carry v7's over from git; the report lists it) for the cookie the sign-in flow actually sets; a server function answering per-visitor data calls `markPrivate()` (`@decocms/tanstack/server`).
10
+ - **Don't let hydration wait on a cross-origin call.** Prefetching the shopper's profile in the router's `hydrate` so widgets hydrate with it keeps v7's pixels, but `hydrate` is awaited: a slow or hung gateway keeps the page from ever becoming interactive. Cap the wait (a few hundred milliseconds) or don't await it. A parity harness replays upstream calls, so it never shows this cost.
@@ -0,0 +1,25 @@
1
+ # Content and local editing
2
+
3
+ From the site migrations; the sites and what the commit hashes refer to are listed in `SKILL.md` ("Gotchas by subject").
4
+
5
+ ## Content
6
+
7
+ - **`deco check` in the build gates the deploy.** Once `build` runs it, a Studio save or a content importer that writes something check rejects fails the next deploy. Make importers emit check-clean content (and run `deco check` at their end), and say in the README that the gate exists.
8
+ - **Don't let rendering depend on undeclared `__`-prefixed fields.** `deco check` accepts `_`/`$`/`@` keys, but the docs say the site editor keeps only declared fields, and whether those keys survive a save isn't documented. Routing data (a page type) belongs in a declared field.
9
+ - **Case-only name pairs.** Two saved blocks whose names differ only by letter case can't coexist on macOS disks; v7 silently bundled one. Check which one content references, keep it, and fail the build on such a pair (reading the git index too). v8's write path refuses new ones; `deco content`/`deco check` don't flag an existing pair.
10
+ - **Required fields saved content omits.** `deco check` rejects a saved block missing a field its type requires, which v7 tolerated. If the component renders without it, make the field optional (an editor-visible change to list), and don't fill content with placeholders.
11
+ - `deco check` rejects fields no type declares, `.tsx`-named preview blocks and dangling references: delete or type them (`9a097a1`, `ffa866a`).
12
+ - v7 app blocks (`deco-shopify`, `deco-blog`, `site`) go: apps are code now, configured from the deploy platform's variables and secrets (e.g. `SHOPIFY_STORE_NAME`), passed as params. Delete each v7 secret block once its value is in the deploy platform's secrets.
13
+ - **Redirects are one block.** v8 routes only the block typed `redirects` (`Redirects`); a v7 `website/loaders/redirect.ts`, `website/loaders/redirects.ts` or `deco-sites/std/loaders/x/redirects.ts` block isn't routed, and `deco check` warns about the first two. The script folds them all into `Redirects`, and the rows of each `website/loaders/redirectsFromCsv.ts` CSV (saved or inline; v8 reads no CSV, so the file is kept and reported: delete it once checked), and reports route conflicts (as in 7.x, for one exact `from` the last rule wins, CSV rows loading before the saved blocks and those in block name order, and for a glob the first; an existing `Redirects` rule always wins): settle each one there, and add the rules of any v7 redirect it reports inline in another block and of any CSV it couldn't read. A temporary rule is `permanent: false`, which v8 answers 307: a site on 7.x's default `legacy` redirect semantics answered 302, so check the temporary ones in the parity run.
14
+ - `website/functions/requestToParam.ts` in a string field becomes the page's route `param` (`/:slug`) the block reads itself.
15
+ - Register blocks under their v7 names only, or the site editor lists them twice (`57561bd`).
16
+
17
+ ## Editing content
18
+
19
+ The migrated site bundles its content: `deco content` turns `.deco/blocks` into `.deco/blocks.gen.ts`, and `src/cms.ts` passes it to `createCMS({ blocks, content })`; with no `DECO_SITE` set, `deco check` checks `.deco/blocks`. Edit the JSON files and commit them; `deco serve` is gone. A content change needs a deploy.
20
+
21
+ To move the content to Studio's hosted CMS (published without a deploy), switch `src/cms.ts` to `createCMS({ blocks, site })` (no `content`; it comes from the CDN at runtime) and drop `deco content` from the scripts. Then `deco check` checks production:
22
+
23
+ - **Publish the migrated content once.** The CLI finds the site from `DECO_SITE` (the environment, else `.env`, `.dev.vars`, then `vars.DECO_SITE` in `wrangler.jsonc` / `wrangler.json` / `wrangler.toml`); then `deco push --draft=<name>` sends `.deco/blocks` to a draft, and `deco publish --draft=<name>` makes it live. Then delete `.deco/blocks` and git-ignore it; `deco pull` fills it again when you need it.
24
+ - **Edit in Studio, or locally with the CLI.** `deco pull [--draft=<name>]`, edit `.deco/blocks/*.json`, `deco check && deco diff`, `deco push --draft=<name>`. A push never publishes; only `deco publish` goes live.
25
+ - **Schema.** On production deploys run `deco schema && deco schema push` (a Studio API key as `DECO_TOKEN`) so Studio's forms follow the deployed code. Add `deco check` there for the guard: it checks production (the live release, from the CDN) against the code.
@@ -0,0 +1,27 @@
1
+ # Editor-form differences (v7 `meta.gen.json` → v8 `schema.gen.json`)
2
+
3
+ Compare each section's form, not just the content. Sort each difference into one of three causes before you approve or fix it.
4
+
5
+ **1. The v7 file was stale.** v7 committed `meta.gen.json`, and sections changed without anyone regenerating it. For each field, check the source's history after the file's last change (`git log <meta.gen.json commit>.. -- <section or shared type>`). If a field was added or removed there, v8 is right. Approve it with the commit as the reason.
6
+
7
+ **2. v7 heuristics v8 drops on purpose.** Approve these, don't "fix" them:
8
+ - **"Select from saved" on every list.** v7 offered it on every array. v8 offers it only where a saved block fits the field's type. Check that no content uses it, and whether the renderer could even resolve a saved block there.
9
+ - **Every file under `sections/` as a section.** v7 listed helper files (shared `types.ts`) as sections. v8 lists only what the block map declares.
10
+ - **Dynamic option pickers.** v7's `@format dynamic-options` fields ran a site loader through `/deco/invoke` to suggest values as the editor typed. The v8 site editor never runs site code, so they become text fields. Make sure the field still accepts what an editor would type (a bare ID, a plain place name), update copy that promises suggestions (grep each such field's `@description` for search wording in the site's language: search, type part of the name, pick from the list), and list each field, with its new copy, for approval.
11
+ - **Page form order and labels.** A site page type that `extends Route` and adds `seo`/`sections` lists its own fields first and labels `seo` as "Seo". Redeclare `name` and `path` (with their `@title`) before them and give `seo` an explicit `@title SEO` to keep v7's form.
12
+ - **The rich-text widget from a substring.** v7 gave the rich-text editor to any type whose name contained `RichText` (`PromoRichText`). v8 matches the alias name as a whole word. When editors rely on the toolbar, keep it with `/** @format rich-text */` on the alias rather than approving its loss.
13
+
14
+ **A color picker from a substring: keep it, don't approve its loss.** v7 added the color widget whenever the type's *name* contained `Color`, even on a string-literal union such as a black/white choice. v8 doesn't guess from names: put `/** @format color */` on the alias (`type TextColor = "black" | "white"`) or on the field, and `deco schema` writes the same `format: "color"` v7 did, with the select's values kept.
15
+
16
+ **Product pickers gain "Inline data".** A field typed as loader data (`Product[] | null`) offers the loaders the block map registers plus an inline-data option v7 didn't have; the loaders are listed in the block map's order. Register the loaders v7 offered (vendor them if needed) in v7's order, and list the inline option for approval.
17
+
18
+ **3. CLI fidelity bugs: fix them in the CLI, don't approve them.** If your `@decocms/blocks` predates these fixes, you'll see:
19
+ - a literal union's dropdown in TypeScript's internal order instead of the source order;
20
+ - `@format datetime` without the date-time picker;
21
+ - `Record<string, any>` offering "Select from saved" and every block type.
22
+
23
+ Upgrade to a release that includes them rather than approving the differences.
24
+
25
+ **Literal order depends on the v7 generator.** Check the site's own v7 `meta.gen.json` before calling an order a bug. Deno-era generators wrote a union's values in source order. `@decocms/blocks-cli` 7 (TanStack and Next.js sites) took the TypeScript checker's order, which is source order unless the same literals already appeared in another type (`'both' | 'desktop' | 'mobile'` came out `desktop, mobile, both`). On such a site the source-order fix reorders those dropdowns relative to v7. That's a stable, intended order, but it's still an editor-visible change, so list it for approval.
26
+
27
+ Encode the ones the product owner approves as rules, and keep the rest pending ([`parity.md`](./parity.md)).
@@ -0,0 +1,40 @@
1
+ # FastStore storefronts that aren't ejected
2
+
3
+ Learned on a VTEX FastStore storefront (`@faststore/cli` 4.x, Next.js 16 Pages Router, private) whose v7 integration monkey-patched FastStore's content requests. FastStore owns the Next.js app (it generates it into `.faststore/` at build) and only compiles some of the store's folders, so there is no place for a framework guide's `createCMS` page. v8 keeps the same seam; only what sits behind it changes. The patches are site-owned glue: say so in the code and the README.
4
+
5
+ ## The seam
6
+
7
+ - **Vendored runtime.** FastStore won't compile `@decocms/blocks` or `.deco/index.ts` from the store, so bundle them (esbuild, CommonJS) into a file under a folder FastStore copies (e.g. `src/server/vendor/deco-cms.cjs`), exporting `createCMS`, `parseDraftPointer` and the block map. Build it in `dev`, `test` and `build`, commit it, and build the committed copy from the **published** package: a bundle built from a linked checkout ships unpublished code. Say in the PR which version it was built from.
8
+ - **Content at runtime.** Create the CMS in the vendored runtime with `createCMS({ blocks, site })`, so content comes from the CDN at runtime; nothing is bundled. Don't read `.deco/` from disk at runtime: FastStore's deploy doesn't ship it.
9
+ - **Content client patch.** Patch the VTEX Content Platform client FastStore's content service calls (`@vtex/client-cp`) so it answers from `cms.forRelease()` / `cms.forDraft(pointer)`, in FastStore's `{ $componentKey, data, name }` section shape. Section blocks return a descriptor (`{ component, props }`) and FastStore renders the component.
10
+ - **Schema-derived defaults by block map, not by name.** A rule that reads a section's schema (a `default` that forces server rendering, say) must map `deco schema`'s `base64(<block name>)@Props` keys to sections through the block map's registrations. Parsing a v7 alias (`site/sections/X.tsx`) works only until the aliases go, and then every section silently changes behavior.
11
+
12
+ ## Drafts on Pages Router SSG pages
13
+
14
+ FastStore's CMS pages are SSG and its CLI forbids `middleware`/`proxy` and `/api` routes, so the only point where a request can turn a static page into a per-request `getStaticProps` is Next's `tryGetPreviewData` (a non-`false` return is draft mode: no SSG cache, `Cache-Control: private, no-cache, no-store`, the value as `context.previewData`).
15
+
16
+ - **Patch the compiled runtimes, not `next/dist/server`.** Next 16 serves pages from `next/dist/compiled/next-server/pages.runtime.{dev,prod}.js`, and each inlines its own `tryGetPreviewData`. Replacing `next/dist/server/api-utils/node/try-get-preview-data` in `require.cache` reaches neither, so drafts never run, in dev or production. Add one statement after the function's per-request memo in both runtimes (webpack builds; FastStore builds with `--webpack`, so the turbo runtimes are unused) that calls a global hook and returns its answer unless it's `undefined`. A `patch-package` file of a minified runtime is hundreds of KB; an idempotent install/build script that fails when the anchor is missing is reviewable. Re-check it on every Next upgrade.
17
+ - **The hook.** Answer synchronously (Next calls it twice per request, from the route's `prepare` and from the renderer, so memoize on the request). Only a `?__draft=` or draft cookie that `parseDraftPointer` accepts is a signal: junk on a production host must not switch a page to per-request rendering. `cms.draftPointer`/`cms.draftCookie` are async, so return a token as preview data, let the content patch await the CMS's answer for it, and remember hosts the CMS refused so they go back to the SSG cache.
18
+ - **`x-nextjs-cache: HIT` is no evidence.** Next stamps it on draft-mode responses too. The draft ran when the response is `Cache-Control: private, no-cache, no-store, …` and shows the draft's content.
19
+ - **Password-protected preview domains.** FastStore protects `*.vtex.app` with a password gate that runs before the page. A store that patched it to let the Studio preview through must read the draft cookie (`__deco_draft`, the same name in v7 and v8), and accept only a value shaped like a pointer, never any `?__draft=`.
20
+ - **Prove drafts end to end; parity can't.** If the v7 draft path was dead (a `require.cache` patch is), the v7 baseline recorded the published page for the draft cases and a dead v8 path passes the compare. Probe the dev server and a production build (`next start`) by hand: `?__draft=<pointer>` on an allowed host shows the draft and sets the cookie; the cookie alone keeps the next page in the draft; a host outside the release's preview hosts and `?__draft=<junk>` get the published page; `?__draft=off` expires the cookie. Then let the draft cases differ from the baseline and list that for approval.
21
+
22
+ ## Preview hosts and draft sources
23
+
24
+ - Preview hosts come from Studio, in each release's metadata (`createCMS({ site })` reads them); until the first publish writes them, and for local content with no `site`, every host previews (`createCMS({ preview: { hosts: ["localhost"] } })` narrows local content to the dev host). v8 ignores v7's `DECO_ALLOWED_PREVIEW_HOSTS`: remove it from env files and harness env too.
25
+ - Drafts need no site loader: `cms.forDraft` fetches the pointer itself, only from v7's preview API domains (`*.decocms.com` and the loopback hosts by default; `createCMS({ preview: { draftHosts } })` replaces the list. The SDK reads no environment variable, so v7's `DECO_PREVIEW_API_DOMAINS` is read by the site, if at all, and passed in). Delete any draft-fetching loader the site kept from v7.
26
+ - If the site keeps v7's policy that a draft that fails to load falls back to the release, write that down: the docs say a failed draft is an error.
27
+
28
+ ## Content imported from FastStore's CMS
29
+
30
+ - Pages imported from FastStore's Headless CMS carry FastStore's settings (`__settings`) next to the SEO object the editor's form edits (`seo`). Merge the form's `seo` over the imported one, or an SEO edit never renders.
31
+ - Don't route on undeclared `__`-prefixed metadata (`__cms.contentType`). The docs say the site editor keeps only declared fields, and whether `_`-keys survive a save isn't documented. Encode what routing needs in a declared field (the template's synthetic `path`, say) or declare it.
32
+ - The store's build runs `deco check`, so an importer that writes content check rejects breaks the next deploy. Make the importer apply the same cleanup rules as the migration's content commit, and run `deco check` at its end.
33
+
34
+ ## Saved-block names that differ only by letter case
35
+
36
+ A case-insensitive disk (macOS) checks out one of the two files, so v7 silently bundled one of them on macOS while Linux had both. Before migrating, find which one content references (grep every saved block for both names), compare the two, and keep the referenced one; record the decision in its own commit. Make the build fail on such a pair, reading the git index too (the disk can't show it). v8's write path refuses a new name that differs from an existing one only by case, but `deco content` and `deco check` don't flag a pair that is already there.
37
+
38
+ ## Global sections with per-URL matchers
39
+
40
+ v7 resolved a store-wide "global sections" list per request, so a matcher in it could show a section on some URLs only. In v8 a matcher reads the request only through the site's own request-scoped storage (`/next/blocks#reading-the-request`), and FastStore fetches global sections apart from the page, for SSG pages at build time. An adapter that resolves the list once per revision drops per-URL matching. If content uses it, keep it (resolve the list per page path, passing the path to the matcher through the site's storage); if it doesn't, list the loss for the product owner anyway, since editors could rely on it.
@@ -0,0 +1,53 @@
1
+ # Framework code: the v8 bindings, and what stays site code
2
+
3
+ From the site migrations; the sites and what the commit hashes refer to are listed in `SKILL.md` ("Gotchas by subject").
4
+
5
+ v8 keeps the framework layer in two bindings, released with `@decocms/blocks` at one version (`^8.4.0`): `@decocms/tanstack` (TanStack Start on Cloudflare Workers, deployed the Deco way) and `@decocms/nextjs` (any Next.js App Router app). Use them; don't copy v7's worker, draft, preview or image code into the site. What neither binding covers is site code ([`site-code.md`](./site-code.md)). Each package's README has the full wiring; `examples/tanstack-worker-smoke` and `examples/nextjs-binding-smoke` in this repo are complete apps.
6
+
7
+ ## TanStack Start (`@decocms/tanstack`)
8
+
9
+ - **Worker entry**: `createDecoWorker({ serverEntry, cms, dev, pageCache })` from `/worker` replaces v7's `createDecoWorkerEntry`. Built in: `/deco/_liveness`, 404 for v7's admin paths, drafts (on the hosts the CMS allows: Studio's, from the release metadata; the cookie, `max-age=0, no-cache, must-revalidate` and noindex on any request with a draft signal), CMS redirects before any route, the visitor and its first-visit cookie, Studio's origins in the CSP (`frame-ancestors`, and `script-src` when the site's policy restricts scripts), one `Set-Cookie` per cookie, `x-page-status`. The worker caches no page (PO, 2026-10-21: the page cache is site-owned, as on Next.js): copy the example worker entry ([`examples/tanstack-worker-smoke/src/worker-entry.ts`](https://github.com/decocms/blocks/blob/main/examples/tanstack-worker-smoke/src/worker-entry.ts)) to `src/worker-entry.ts`: the site's own cache on the Cloudflare Cache API (`pageCache`, which the worker calls only for a `GET` of the current release, never a preview). Carry over by hand what the report lists from v7's `createDecoWorkerEntry`: v7's `buildSegment` as the cache's segment (`loggedIn: true` is never cached), v7's `csp` as `csp: { reportOnly }`. It has v7's cache profiles in `PROFILES`, the key on path, device, segment, assignments (`assignmentsKey(page.assignments)`: what the worker decided once per request) and `<build>.<revision>` (`cacheVersion`; declare `__BUILD_HASH__` once), `__cseg` CDN caching of navigation data, and v7's `POST /_cache/purge` with the `PURGE_TOKEN` secret and `{ paths, segments? }`. It's the site's code now: change the profiles, the key or the purge there. The visitor's cookie is added by the worker after `pageCache` answers, so a cached copy never stores one and a new visitor served from the cache still gets theirs: never add it, or any other visitor cookie, inside the cache. The other options: `preload` and `routes` for requests the site answers itself (a commerce proxy, a sitemap; v7's `proxyHandler`). Code the site keeps (geo cookies, a v7 request context) wraps the worker's `fetch`; it needs no new option.
10
+ - **Build hash**: `decoTanstack({ buildHash: <CI commit sha> })` from `/vite` (CI sha, then git, then the time) defines `__BUILD_HASH__` and includes `decoContent()` from `@decocms/blocks/vite`. The package reads no env: the site passes the CI value.
11
+ - **Root document**: `DecoDocument` from `/react` (`site`, `lang`, `nonce`, `editShortcut`) mounts `StudioBridge`, `StudioChannel` (Studio's editor code inside the page when Studio frames it, from exact origins: `studioOrigins`, else `DECO_STUDIO_ORIGIN`, comma-separated, else Studio's production and staging origins; the worker adds the same list to the CSP) and `DraftBadge` from `@decocms/blocks/preview`, the events bus, `NavigationProgress` and `StableOutlet`. A layout it can't express (a skip link before `<main>`) keeps its own document and renders `<DecoPreview site="…" />` from `/react` in its `<body>`: the bridge, the draft badge and the draft they read (`StudioBridge` alone leaves draft pages without the badge).
12
+ - **Studio**: the page loader returns `pathTemplate: match.entry.path` (the page `matchRoute` matched) in its loader data, so "." on the store page opens that page in Studio's editor, as v7's `cmsRoute` did with `path`. Each page section renders in v7's wrapper, `<section id={sectionId} data-manifest-key={component}>`: Studio's editor outlines, selects and scrolls to those.
13
+ - **Router and server functions**: `createDecoRouter` (`/router`) keeps `?q=`; a router that needs TanStack's `hydrate` builds its own router with `decoParseSearch`/`decoStringifySearch`. `createStart(() => ({ serverFns: { fetch: decoServerFnFetch } }))` (`/start`). The worker decides the draft, so delete the draft middleware in `start.ts`; pages read it with `contentClient(cms)` (`/server`).
14
+ - **Image**: `Image`, `Picture` and `Source` from `/react` render v7's markup with v7's props (the script moves those imports). The binding knows no commerce platform, so the script writes the site's own URLs to `src/imageUrl.ts` and wires them as `createDecoRouter({ routeTree, Wrap: ({ children }) => <ImageUrlProvider value={imageUrl}>{children}</ImageUrlProvider> })`, where `imageUrl = createImageUrl({ providers: [vtexCatalog(), shopifyCdn(), decoCdn({ domain, quality, sources: "all", ...byRelease })] })`: `createImageUrl` and `decoCdn` from `@decocms/blocks/image`, `vtexCatalog` from `@decocms/apps-vtex/image`, `shopifyCdn` from `@decocms/apps-shopify/image`. Keep both helpers whatever the site's platform: v7 resized VTEX and Shopify images on every site, so dropping one changes those URLs. A store with Nuvemshop images (`*.mitiendanube.com/stores/…/products/…-{w}-{h}.{ext}`) also lists its own provider before `decoCdn`, since no `@decocms/apps-*` package covers Nuvemshop (see below). That is v7's `Image` byte for byte, an `Image` or `Source` without a width included (`width=NaN … NaNw`, as v7 wrote it); `domain` and `quality` are what the site passed to `registerImageCdnDomain`/`registerImageQuality`, else left out. v7's `Image` changed across 7.x releases; `byRelease` is, for the `@decocms/blocks` version the site ran (the script's report spells the whole line for it):
15
+
16
+ | Site's 7.x | `decoCdn` options besides `domain`, `quality`, `sources: "all"` |
17
+ |---|---|
18
+ | before 7.71.0 | `legacyHosts: []`; `domain` defaults to `"decoims.com"` there |
19
+ | 7.71.0 to 7.71.3 | `legacyHosts: []` |
20
+ | 7.71.4 | `legacyHosts: ["decoims.com"]` |
21
+ | 7.71.5 on | none (and, from 7.77.1, the Nuvemshop provider below for a store with Nuvemshop images) |
22
+
23
+ `stripAssetHosts` stays at its default, `"leading"`, on every row. Before 7.71.4, v7 stripped the asset hosts anywhere in a source; the switch is approved (PO, 2026-10-15) and changes only a source that merely contains an asset URL. The report's "image URLs" line lists those URLs for the PR.
24
+
25
+ A site that kept its own copy of v7's image helper (a file under `src/` that defines `getOptimizedMediaUrl`) keeps that copy's rules, not its release's: the script reads the options from the copy and from the site's `registerImageCdnDomain`/`registerImageQuality` calls, and reports them on the copy's own line (fuzzed against each release's `Image.tsx` and two storefronts' edited copies). A copy whose rules it can't read is reported for you to compare by hand. One approved change from v7 (PO, 2026-10-14): an already-resized Deco CDN URL in the content (`https://assets.decocms.com/image?…&src=…`, or the `decoims.com`, `deco-assets.edgedeco.com` and `deco-assets.decoazn.com` endpoints) is re-resized from its `src`. v7 wrote `src=image`, which the CDN can't serve. Without a provider every source goes through the Deco CDN, VTEX and Shopify images too. Check a page's image URLs against v7's. v7's Nuvemshop rule, for the site's `src/imageUrl.ts` (`tests/tanstack-image-markup.golden.test.ts` holds it to v7's markup):
26
+
27
+ ```ts
28
+ const NUVEMSHOP_IMAGE = /^(https:\/\/[a-z0-9-]+\.mitiendanube\.com\/stores\/.+\/products\/.+)-\d+-\d+\.(\w+)$/;
29
+ const NUVEMSHOP_SIZES = [50, 100, 240, 320, 480, 640];
30
+ const nuvemshop: ImageProvider = {
31
+ name: "nuvemshop",
32
+ match: (src) => NUVEMSHOP_IMAGE.test(src),
33
+ format(src, { width }) {
34
+ const m = src.match(NUVEMSHOP_IMAGE);
35
+ if (!m) return null;
36
+ const size = NUVEMSHOP_SIZES.find((s) => s >= width);
37
+ return `${m[1]}-${size ? `${size}-0` : "1024-1024"}.${m[2]}`;
38
+ },
39
+ };
40
+ // providers: [vtexCatalog(), shopifyCdn(), nuvemshop, decoCdn({ domain, quality, sources: "all" })]
41
+ ```
42
+ - **Draft names and Studio's origins**: `DRAFT_PARAM`, `DRAFT_COOKIE`, `VERSION_HEADER`, `VISITOR_HEADER`, `ASSIGNMENTS_HEADER`, `draftResponseHeaders`, `STUDIO_ORIGINS`, `STUDIO_FRAME_ANCESTORS` and `isStudioOrigin` come from the root, `@decocms/tanstack` (not from `@decocms/blocks`); the script moves them.
43
+ - **Cache metrics**: the worker records `http.server.request.duration` (route template, method, status class, cache decision, device) in the CMS's telemetry by itself (`recordServerRequest` from `@decocms/blocks/metrics`, the bindings' API; the site imports nothing); its `cache` label is the `X-Cache` the site's `pageCache` answers with. v7's `DECO_METRICS` writes have no writer; the worker entry's `pageCache` is where a site sends hit/miss/bypass anywhere else (`telemetry.md`).
44
+
45
+ ## Next.js (`@decocms/nextjs`)
46
+
47
+ - **Drafts**: `decideDraft`, `draftRequestHeaders`, `rewriteToDraftRoute`, `applyDraft` and `isDraftRoutePath` from `/proxy` in `proxy.ts` (or `draftProxy` for a site with no proxy of its own); `bindDraft(cms, { searchParams })` and `contentClient(cms)` from `/server` on the `/_draft` route and in a layout that reads content. Both ask the CMS which hosts may preview (Studio's, from the release metadata). Details and gotchas: `nextjs.md`.
48
+ - **Studio and the badge**: `<StudioBridge site="…" />` in the root layout (it mounts the Studio channel too) and `<DraftPreviewIndicator />` on the draft route, from `@decocms/nextjs`. Each CMS page renders `<StudioPage pathTemplate={match.entry.path} />` (a `<meta>` React puts in the head), so "." opens that page in Studio; the root layout stays across navigations and can't know it. Studio's editor outlines, selects and scrolls to top-level `<section id data-manifest-key={component}>` elements, v7's `SectionRenderer` wrapper: a site whose section list renders its own wrapper (v7 storefronts on Next often did) makes that wrapper a `<section>` with those two attributes.
49
+ - **Request metric**: `instrumentation.ts` (next to `app/`) is `export { register } from "@decocms/nextjs/instrumentation";`, which records `http.server.request.duration` from Next's own request span; a site already on `@vercel/otel` or an OpenTelemetry SDK adds `serverRequestSpanProcessor()` to its span processors instead (`telemetry.md`).
50
+ - **next.config**: `withDeco(config)` from `/config` puts v7's draft header rules first and adds Studio's dev origins; it adds no rewrites (v7's `/deco/*` handlers are gone) and no `transpilePackages`.
51
+ - **Image**: `createDecoImageLoader(imageUrl, { fallback: nextImageOptimizer })` from `/image-loader` as the `loaderFile`, over the site's `createImageUrl`. The loader knows no platform: a VTEX store lists `vtexCatalogWebp()` and `vtexFileManager({ via })` from `@decocms/apps-vtex/image` (`via` is the resizer its loader uses today: `"query"` or `"thumbor"`), then `decoCdn({ quality: "high", fit: "contain", layout: "quality-last" })` from `@decocms/blocks/image`. URLs match the site's current loader byte for byte, except the approved re-resizing of an already-resized Deco CDN URL (above). A loader still on `via: "query"` should move to `"thumbor"`: VTEX's `?width=&aspect=true` resizer answers 500 for raster files since 2026-10-07 (PO-approved, a site change).
52
+ - **Draft names and Studio's origins**: from the root, `@decocms/nextjs` (its own copy; never `@decocms/tanstack` or `@decocms/blocks`).
53
+ - **Dev**: `createCMS` has no dev mode and no `dev` option. With `site` it reads the hosted release from the CDN at runtime, dev server included; without `site` it serves the `content` you pass (passing both throws). Drop a v7 `isNextDev`/`dev` line.
@@ -0,0 +1,16 @@
1
+ # Hosted releases, bundled content and v7 leftovers
2
+
3
+ From the site migrations; the sites and what the commit hashes refer to are listed in `SKILL.md` ("Gotchas by subject").
4
+
5
+ ## Hosted releases and bundled content
6
+
7
+ **v7 fast deploy becomes the hosted CMS.** A v7 TanStack site that published content without a deploy (`DECO_FAST_DEPLOY` plus a `DECO_KV` namespace) needs `site` on `createCMS` for the same feature (and `token` for hosted telemetry): the site reads its own `DECO_SITE` var and `DECO_SITE_TOKEN` secret and passes them, since the SDK reads no environment variable; without `site` every content change needs a deploy. Put the two `wrangler secret put` commands in the deploy checklist. v8 keeps content out of the bundle too: with `site`, it is fetched at runtime only. On a site with ~300 saved blocks (11 MB of JSON), Node measured about 13 MB per parsed copy, plus a transient string up to twice the JSON while a snapshot parses: under the Workers 128 MB limit, but measure memory and cold start with `wrangler tail` on a preview before turning it on.
8
+
9
+ With `site` set on `createCMS`, a published release goes live without a deploy, but only for what reads through the CMS client. Before turning it on, grep for direct imports of `.deco/blocks/*.json` (redirects, proxy tables, config blocks) and for build-time scripts that read `.deco/blocks`: those stay on the last deploy. v7 behaved the same, so it isn't a parity break; route them through the client or document the limitation and keep hosted releases off until you do.
10
+
11
+ ## v7 leftovers to delete
12
+
13
+ - Env vars and comments for the v7 admin protocol (`DANGEROUSLY_ALLOW_PUBLIC_ACCESS`, admin public keys) and for settings that lived in the v7 `site` app block.
14
+ - Middleware/proxy exclusions for `/deco`, `/live` and `/.decofile`: the routes are gone. Removing the exclusion sends these paths down the unknown-path route, which may ask upstream (a redirect lookup) on every stray hit from old tooling and scanners; keeping it may send them to a catch-all that does worse (a search fallback answering 200). Skip the upstream work for them explicitly, and check the status (404) and the upstream calls for each path in the parity run.
15
+ - Add the site's new env vars (`DECO_SITE`, `DECO_SITE_TOKEN`, which the site passes as `createCMS({ site, token })`) to its env example, the token marked secret, and blank them in parity runs.
16
+ - **Editor settings that disappear with the `site` block.** Deleting the v7 `site` app block (apps are code now) also deletes any setting editors changed there, such as the site's name. Moving it to code is fine, but it is an editor-visible change: list it for the product owner. Its preview hosts need nothing: Studio writes where each site previews into the release metadata, and `createCMS({ site })` reads them.
@@ -0,0 +1,81 @@
1
+ # Import map: v7 → v8
2
+
3
+ What `scripts/imports.ts` does with each v7 `@decocms/*` import in the site's `src/`. Source of truth: `V8_API`, `MOVES`, `NAME_HINTS` and `HINTS` in that file; keep these tables in step with them.
4
+
5
+ ## Rewritten by the script
6
+
7
+ | v7 import | Becomes |
8
+ |---|---|
9
+ | `@decocms/apps-<x>/loaders/…`, `…/actions/…` that the content calls | the vendored copy in `src/vendor/<app>/…` (relative import) |
10
+ | `createInstrumentedFetch` from `@decocms/blocks/sdk/instrumentedFetch` | `createInstrumentedFetch` from `@decocms/blocks/fetch`; `createInstrumentedFetch("x")` becomes `createInstrumentedFetch({ provider: "x" })` |
11
+ | `createDecoRouter`, `decoParseSearch`, `decoStringifySearch` (`@decocms/tanstack`) | the same names from `@decocms/tanstack/router` |
12
+ | `NavigationProgress`, `StableOutlet` (`@decocms/tanstack`) | the same names from `@decocms/tanstack/react` |
13
+ | `decoServerFnFetch` (`@decocms/tanstack/sdk/serverFnFetch`) | `@decocms/tanstack/start` |
14
+ | `Image`, `Picture`, `Source` and their props types (`@decocms/blocks/hooks`), on a TanStack site | `@decocms/tanstack/react`, same props and markup. The binding knows no platform, so the script writes `src/imageUrl.ts` (v7's URLs: the platforms' helpers from `@decocms/apps-vtex/image` and `@decocms/apps-shopify/image`, then `decoCdn` with the site's release rules, or its own copy's, and its registered domain and quality) and puts `<ImageUrlProvider value={imageUrl}>` in `createDecoRouter`'s `Wrap` |
15
+ | `DRAFT_PARAM`, `DRAFT_COOKIE`, `draftResponseHeaders`, `STUDIO_ORIGINS`, `STUDIO_FRAME_ANCESTORS`, `isStudioOrigin` (`@decocms/blocks`, a prerelease) | the site's binding root: `@decocms/tanstack` or `@decocms/nextjs` (reported when the site has neither) |
16
+ | `@decocms/apps-commerce/<subpath>` (`types`, `types/cart`, `sdk/*`, `utils/*`; also a stray 6.x `@decocms/apps/commerce/<subpath>`) | `@decocms/compat-v7/commerce/<subpath>`: the same files, React-free, v7's output. v7's app runtime (`app-types`, `registry`, `resolve`, `manifest-utils`) is reported |
17
+ | `clx` (`@decocms/blocks/sdk/clx`, `/sdk`) | `@decocms/compat-v7/clx` |
18
+ | `useScript`, `useScriptAsDataURI`, `inlineScript` (`/sdk/useScript`, `/sdk`) | `@decocms/compat-v7/script`, v7's bytes |
19
+ | `detectDevice`, `isMobileUA`, `Device`, `MOBILE_RE`, `TABLET_RE` (`/sdk/detectDevice`, `/sdk/useDevice`, `/sdk`) | `@decocms/compat-v7/device` |
20
+ | `useDevice`, `DeviceProvider`, `DeviceContext` (`/sdk/useDevice`, `/sdk`) | `@decocms/compat-v7/tanstack` or `/nextjs`, by binding; the report says how to seed the provider with `requestDevice()` |
21
+ | `SectionProps`, `Resolved`, `LoadingFallbackProps`, `Flag` (`@decocms/blocks`, `/types`); the widgets (`ImageWidget`, `Color`, `RichText`, …, `/types/widgets`) | `@decocms/compat-v7/types`, `@decocms/compat-v7/types/widgets` (`deco schema` reads the widget names from there too) |
22
+ | `compose`, `withDevice`, `withMobile`, `withSearchParam`, `withSectionLoader` (`@decocms/blocks/cms`) | `@decocms/compat-v7/sections` |
23
+ | `registerSectionLoaders({ … })`, `registerNonCriticalSections([…])` | `export const sectionLoaders` and `nonCriticalSections` in the same file, run by `loadSections` in `.deco/index.ts` (`runSectionLoaders` with v7's rules; the nested walk follows the site's 7.x release) |
24
+ | `ctx.device` in a v7 loader `(props, req, ctx)` | `detectDevice(req.headers.get("user-agent") ?? "")`, exactly v7's `ctx.device`; any other `ctx.*` read is reported (it throws in v8) |
25
+
26
+ An import that mixes moved and other names is split; the rest is reported.
27
+
28
+ ## Left alone (already the v8 API)
29
+
30
+ `@decocms/blocks` (the root's v8 names: `createCMS`, `matchRoute`, `remoteLoader`, `parseDraftPointer`, `Blocks`, `Lazy`, `Seo`, …), `@decocms/blocks/fetch`, `/analytics`, `/cli`, `/image` (platform-neutral: `createImageUrl`, `decoCdn`, `srcSet`, `parseSrcSet`, `preloadLink`), `/vite`, `/preview` (`DraftBadge`, `StudioBridge`, `StudioPage`); the platforms' image helpers, `@decocms/apps-vtex/image` and `@decocms/apps-shopify/image`; the root of `@decocms/tanstack` 8 (the draft names and Studio's origins) and every subpath (`/worker`, `/server`, `/start`, `/router`, `/react`, `/scope`, and `/vite`'s `decoTanstack`), and of `@decocms/nextjs` 8 (`/proxy`, `/server`, `/image-loader`, `/config`'s `withDeco`, the root's `StudioBridge`, `StudioPage`, `DraftBadge`, draft names and Studio's origins); every `@decocms/compat-v7` entry point.
31
+
32
+ ## Reported, with where the replacement lives (first match wins)
33
+
34
+ | v7 import | Replacement |
35
+ |---|---|
36
+ | `@decocms/start`, `@decocms/start/*` | a 6.x import: upgrade the site to 7.x first |
37
+ | `@decocms/blocks/sdk/cachedLoader` | gone: an upstream cache is your own `fetch`, passed to `createInstrumentedFetch` (`/next/caching#upstream-data`) |
38
+ | `…/invoke`, `createInvoke`, `@decocms/blocks/sdk/invoke` | `/deco/invoke` is gone: the script writes one server function per key and imports it at each call site (`references/server-functions.md`), never a rebuilt invoke tree (`/next/renames-and-migrations#loaders-actions-and-invoke`) |
39
+ | `@decocms/blocks-admin/*` | v8 sites serve no admin endpoints; the site editor uses the content protocol (`/next/studio-compatibility`) |
40
+ | `@decocms/blocks-cli/*` | codegen is the `deco` CLI in `@decocms/blocks`: `deco schema`, `deco content`, `deco check` (`/next/cli`) |
41
+ | `@decocms/blocks/setup`, `@decocms/blocks/cms/*` | `createCMS` from `@decocms/blocks`, with the block map in `.deco/index.ts` (`/next/content#create-the-cms`) |
42
+ | `@decocms/blocks/sdk/instrumentedFetch` (other names) | `createInstrumentedFetch({ provider, fetch?, retry?, circuitBreaker? })` from `@decocms/blocks/fetch` |
43
+ | `@decocms/blocks/sdk/otel`, `/sdk/observability`, `/sdk/logger`, `/middleware/observability` | the `telemetry` option of `createCMS` (`/next/telemetry`) |
44
+ | `…/Analytics`, `…/OneDollarStats`, `@decocms/blocks/sdk/analytics` | `AnalyticsScript` and `track` from `@decocms/blocks/analytics`, with the `analytics` section of `cms.settings()` (`/next/analytics`) |
45
+ | `@decocms/apps-salesforce`, `@decocms/apps/salesforce` | `@decocms/apps-sfmc-personalization` |
46
+ | `@decocms/apps-website`, `@decocms/apps/website` | SEO, sitemaps, redirects live in your platform template |
47
+ | any other `@decocms/apps-<x>`, `@decocms/apps/<x>` | apps are thin upstream clients: call `create<X>Client` from your own code (`/next/upstream-clients`) |
48
+ | `@decocms/blocks/sdk/cacheHeaders`, `/responseCache`, `/cacheStorage`, `/mergeCacheControl` | on TanStack, the page cache in the site's worker entry (the example worker entry you copy: `PROFILES` are v7's); a Next.js site keeps its own |
49
+ | `@decocms/blocks/sdk/csp`, `/sdk/redirects` | `createDecoWorker`'s `csp` option; the worker applies CMS redirects |
50
+ | `createDecoWorkerEntry` (`@decocms/tanstack`) | `createDecoWorker({ serverEntry, cms, pageCache })` from `@decocms/tanstack/worker`, behind the site's own page cache: copy the example worker entry and carry v7's `buildSegment` and `csp` over by hand, as the report lists (`references/framework-code.md`) |
51
+ | `DecoRootLayout`, `PreviewProviders`, `DraftPreviewIndicator` (`@decocms/tanstack`) | `DecoDocument` from `@decocms/tanstack/react` |
52
+ | `cmsRouteConfig`, `loadCmsPage`, `DecoPageRenderer`, … (`@decocms/tanstack`) | `createCMS` and `matchRoute` (`/next/tanstack-start-descriptors`), the draft from `contentClient(cms)` (`@decocms/tanstack/server`) |
53
+ | `decoInvokeRouteConfig`, `decoMetaRouteConfig`, `decoRenderRouteConfig` | delete: the worker answers 404 on v7's admin paths |
54
+ | `setupTanstackFastDeploy`, `kvLoader` | `createCMS({ site, token })` (`references/hosted-releases.md`) |
55
+ | `@decocms/tanstack/vite` (`decoVitePlugin`) | `decoTanstack({ buildHash })` from `@decocms/tanstack/vite` |
56
+ | `@decocms/tanstack/sdk/startEntry`, `/sdk/cdnSegment`, `/sdk/cookiePassthrough` | `decoServerFnFetch` in `createStart`; `buildSegment` in the worker entry's page cache; the worker's Set-Cookie handling |
57
+ | `createDecoPage`, `DecoPageRenderer`, `DecoRootLayout`, … (`@decocms/nextjs`) | `createCMS` (`/next/nextjs`); `bindDraft` and `contentClient` from `@decocms/nextjs/server`; `StudioBridge` in the root layout |
58
+ | `DraftPreviewIndicator` (`@decocms/nextjs`) | the same name in v8, showing what `bindDraft` bound: call that first |
59
+ | `@decocms/nextjs/middleware` | `decideDraft` … `applyDraft` (or `draftProxy`) from `@decocms/nextjs/proxy` |
60
+ | `@decocms/nextjs/routeHandlers`, `DECO_REWRITES` | delete: no `/deco/*` handlers in v8 |
61
+ | `LiveControls` (`@decocms/blocks/hooks`) | `StudioBridge`: `DecoDocument` mounts it (`DecoPreview` in a site's own document); a Next.js layout renders it from `@decocms/nextjs`, and each page renders `StudioPage` |
62
+ | `DraftPreviewBadge` (`@decocms/blocks/preview`, `@decocms/nextjs`) | `DraftBadge` from `@decocms/blocks/preview` |
63
+ | `registerImageCdnDomain`, `registerImageQuality`, `getOptimizedMediaUrl`, `getSrcSet` | `createImageUrl({ providers: [vtexCatalog(), shopifyCdn(), decoCdn({ domain, quality, sources: "all", ...byRelease })] })` (`byRelease` by the site's 7.x release, or read from the site's own copy of the helper: `framework-code.md`): `createImageUrl`, `decoCdn` from `@decocms/blocks/image`, `vtexCatalog` from `@decocms/apps-vtex/image`, `shopifyCdn` from `@decocms/apps-shopify/image`; `url(src, opts)` and `srcSet(url, src, opts)`; on TanStack, `ImageUrlProvider` |
64
+ | `Image`, `Picture` on a Next.js site | next/image with `createDecoImageLoader` from `@decocms/nextjs/image-loader` |
65
+ | other v7 names under `@decocms/tanstack`, `@decocms/nextjs` | the v8 binding has no such name; see the rows above and `references/framework-code.md` |
66
+ | anything else under `@decocms/*` | no v8 equivalent (several have a site-code replacement: the next table) |
67
+
68
+ ## What sites ended up writing themselves
69
+
70
+ From the storefront and blog migrations, the reported imports with no binding equivalent were replaced by site code like this:
71
+
72
+ | v7 import | Site code |
73
+ |---|---|
74
+ | `BreadcrumbJsonLd`, `PLPJsonLd`, `ProductJsonLd` (`@decocms/blocks/hooks`) | `src/vendor/blocks/JsonLd.tsx` |
75
+ | `ANALYTICS_SCRIPT` (`@decocms/blocks/sdk/analytics`) on a site with no analytics SDK | on TanStack, nothing: `DecoDocument` renders the `data-event` observer; elsewhere the same observer string in the site's root document, copied from the installed version (7.6x defers it until a Speculation Rules prerender activates) |
76
+ | `withABTesting` (`@decocms/blocks/sdk/abTesting`), or a vendored copy | on TanStack Start, `abTestingRoutes({ worker: () => worker, kvBinding, shouldBypassAB, preHandler })` from `@decocms/compat-v7/tanstack/worker`, run first in `createDecoWorker`'s `routes`; the script reports the import (a wrapper becomes a routes handler, so it isn't rewritten). If the KV holds no config for the site's hosts, nothing was split: delete it and the binding instead ([`site-code.md`](./site-code.md)) |
77
+ | `signal` (`@decocms/blocks/sdk/signal`) | delete it when nothing imports the site's re-export; otherwise a local signal |
78
+ | `withFetchTimeout`, `FetchFn` (`@decocms/blocks/sdk/fetchTimeout`, 7.6x) in vendored loaders | a local `fetch(url, { ...init, signal: AbortSignal.timeout(10_000) })` (v7's default), or the v8 client's own fetch |
79
+ | `getCookies`/`setCookie`, `RequestContext` | read the request and write response headers explicitly, or a site-owned `AsyncLocalStorage` (`src/request-state.server.ts`) |
80
+ | `useCart`/`useUser`/`useWishlist`, cart loaders (`@decocms/apps-<x>`) | `src/vendor/<platform>/…` copies, sending through the v8 client (`createShopifyClient`, …) |
81
+ | `Seo`, JSON-LD components | the site's head builder (`src/head.ts`) and `src/vendor/blocks` |